You are here: Home / Blog / A way forward for plone.api

A way forward for plone.api

Posted by fulvio at Mar 04, 2012 03:41 PM |
Filed under:

As one of the Munich plone.api sprint participants, and following up to a lively discussion on the plone-developers list that brought in the voices of many dedicated Plone contributors, I want to make a modest proposal.

It is significant that so many of the dedicated contributors to the Plone core and its ecosystem as a whole felt compelled to weigh in to the discussion.   Without exception, all the voices in the discussion melded together to form a decidedly constructive chorus.  Clearly, a nerve was struck.  If you were not in Munich, I can attest to the fact that this topic had the ability to galvanize every single person who participated in the discussions, no matter their level of experience in Plone development.

As so often happens in a lively debate, minds produce copious amounts of ideas.  This, of course, is a good thing.  It can be bewildering, too.  We are lucky that all of these ideas were not just voiced in fleeting verbal conversations, but that we have them, black on white (or whatever colors you use), in our inboxes and list archive.  It would certainly be useful to attempt to synthesize all the viewpoints we have heard so far.

My intention, though, is to go back to the start.  It seems to me that there was a point in the Munich open space where the discussion definitely lifted off.  The lift-off happened when someone admitted to not knowing, or not being able to remember, how to write the code to do something that should be simple, such as copying a content object.  Everyone could relate to that frustration.  Everyone.  No doubt, it wasn't just about "copying an object".

I think we should not confuse the momentum behind plone.api with wanting to create a "great" API.  If we let the conversation go in that direction, everyone is going to produce a different wishlist, and there is no way we can make everyone happy.  I'm also not completely on board with the idea of solving 20% of the use cases that cause 80% of the problems.  That sounds too much like a common denominator approach, that could end up making everybody unhappy.

The momentum originates from the possibility that, someday, with this API I might actually be able to write (and remember) the simple method call required to do a very simple thing.  And so, while I'm proud of the sphinx docs we produced, and of our "document first" approach, perhaps to some extent this approach distracts us from where the energy is, and what we are trying to do.

Instead (or in addition) the energy comes from:  "I really hate that to do A I have to use this crappy xyz code!"

So, can we start a collection, a little gallery of horrors?  Here is a silly example of what I mean.  I'm going to paste a code snippet that I hate, and I'm going to explain what I would like to have instead.  After that, people can weigh in on what disadvantages my desired "API" would have, or why it would not work, or how it could be solved better.

My example

<tal:control_panel
tal:define="is_manager python:context.portal_membership.checkPermission('Manage portal', context);"
tal:condition="is_manager">
<dd>
<a href=""
tal:content="string:Site Setup"
tal:attributes="href string:${context/portal_url}/plone_control_panel;
title string:Site Setup">
Site Setup
</a>
</dd>
</tal:control_panel>

Why this sucks

The problem is not TAL, it's the double indirection to a method that I have to call with what looks like a set of positional arguments in an arbitrary order.  Could I please just have a global is_manager that I don't need to define?  If I set up my own set of custom permissions, I guess I'll be fine doing the python:context.portal_membership.checkPermission('Do something unusual', context).  Plone ships with a set of stock permissions, other than manager, so all of those should be available globally.  Actually, it would be nice if a global is_mycustomperm could be generated automatically when a new permission is defined.

Actually, this example contains two horribles in one.  What's with the ${context/portal_url}?  I can never remember when I can use portal_url and when I can't.  Why context?  Why would portal_url depend on it?  Subsites don't ship with Plone out of the box.

What would be better

Can I have this, please?

<tal:control_panel
tal:condition="is_manager">
<dd>
<a href=""
tal:content="string:Site Setup"
tal:attributes="href string:${portal_url}/plone_control_panel;
title string:Site Setup">
Site Setup
</a>
</dd>
</tal:control_panel>

Discussion, pros/cons

Is there a performance penalty to having all the permissions computed for the context at request time?

 

 

I don't have a strong preference on how this little gallery of horrors should be implemented.  Sphinx might work.  Google moderator, maybe.  [I'm a fan of wikis, I like how in MediaWiki (e.g. wikipedia) there is a separation between the content and the discussion about the content (they are on different tabs), and yet there is no barrier to either editing the content, or adding to the discussion, and full history is preserved (again with no barrier, no context switch).]

It's great that we started writing the documentation for plone.api, and even included examples for each element of it.  But somehow divorcing this documentation from the horrors we are trying to fix seems counterproductive.

Of course, the "little gallery of horrors" and the "official" documentation have to be integrated somehow, and this is another problem.

Finally, I think that while it's certainly better to start small than not at all, it should be possible to let plone.api grow over time to cover more than the 20/80 scenario that was proposed.

Filed under: