Having trouble wrapping my head around Dexterity (and the docs are not helping!)

I’m a Plone newbie, I’ve attacked the problem of learning Plone several times over the last few years with no real success. In my latest attempt, I’ve theorized that content types are the most central concept to plone, therefore I’ve chosen to go through the dexterity documentation (Dexterity Developer Manuall). I've been at it for a few days now, I’m recreating the tutorial example on a virtual machine, albeit with very great difficulty, because the docs clearly describe an earlier incarnation of plone 4, if indeed it was written around plone 4 at all! Up until this point I’ve been getting help in IRC translating the steps from the (outdated) zopeskel examples the tutorial presents into a bobtemplates driven set of steps.
My latest challenge is this: I’ve reached The FTI, but the xml content type file which the docs present is very different to the one that I got bobtemplates to generate. In the IRC I was told to copy and paste and modify my bobtemplates generated file for the other types I want to make up in this package, but the API has clearly changed between the time the docs were written and now. I prefer to be intentional in my efforts, so I don’t want to just blindly cut-and-paste code from an older version of the API (presented in the docs) into my test plone site. I need someone to explain to me what the directives in the XML file for the type mean.

P.S. The documentation needs some work. I would be happy to chip in and help re-write them so they reflect the way Plone works today. Obviously though, I would need to gain an understanding of the subject matter before I would be able to expound upon it.


The training documentation at https://training.plone.org/ is more up to date and may be helpful for you.

What are you trying to do? To be honest in only 10% of the sites we customise do we need new content types so I'm not sure it's the most central concept.
But please do list out the inconsistancies with the documentation. That will give people a starting point on where to help you.

1 Like

If you try to learn, then I think the best approach is not the Plone doc, but the training doc:
and once you start being confortable with Plone, then you can use the doc as a reference to understand more detailed and complex things.


Do you mean anything that is not here?

1 Like

Hey, it's good to see your energy to learn Plone!

I think you may be duplicating a solution though as mrbob templates for Plone Dexterity items already exist....

Just look at https://github.com/plone/bobtemplates.plone, follow the install instructions there, and then run

 <path/to>/mrbob -O collective.foo bobtemplates:plone_addon

It's first question is:

--> What kind of package would you like to create? Choose between 'Basic', 'Dexterity', and 'Theme'. [Basic]:

Obviously you then answer Dexterity, and the rest is history....

The FTI generated by that package will be good for modern Plone (4.3 or 5.x)


1 Like

What he was asking on IRC was local commands like in paster to create additional CTs without copy&pasting, and also to add new custom views, portlets etc.

1 Like

Ah, I only saw (in Slack/IRC) that @altophen was confused about the FTI xml. My aim was to reassure him that what mrbob generates is correct.

Code generation can be overdone anyway.... an original Plonista once told me (something like) "if you think code generation is the answer, then you are asking the wrong question"

1 Like

If you are new to Plone, and using Plone 5, you should have a look at:
Where you can make new content types TTW. You can always export them later.
Notice that you can add fields and also behaviors

After that, you will need a view for your content type.
Although it is not too hard to make a new view, you defently should take a look at 'Mosaic', which will let you do this by pointing and clicking.

To make mosaic (plane.app.mosaic) available for you content type, you will have to enable 'layout' behavior, and then choose 'Mosaic layout' in "Display menu".
(After you have added it to buildout.cfg and installed it, that is)


I already came across plone training in my research, I was trying to follow it but tripped up by starting somewhere in chapter 13 or so (the dexterity part, of course!), my boss eventually told me it was designed to be followed sequentially from the beginning, and that what I'd missed was some setup that I would have missed because I didn't do an earlier chapter.

But more to your point, I want to point out something in chapter 13: under Using zopeskel to create an egg there are commands to run zopeskel which it says comes with the unified installer.. this part also did not work for me; zopeskel is not included in plone 4.3.9 and I had a huge amount of trouble getting it to work with 4.3.9, this was part of my discussions in IRC, I was trying to get a sequence of steps centered around bobtemplates to work..
In other words, if I'm having to be fighting with zopeskel while following training.plone.org, is it really more current than docs.plone.org?

@ebrehault thanks, see my reply to guido stephens above

@davilima6 does that page describe the api that are used here: The FTI (in Session.xml and in Program.xml)? because those are the files I want to reproduce in plone 4.3.9

@djowett BIg UP! lol! thanks!

You should use mr.bob and its companion bobtemplates.plone, as described in https://training.plone.org/5/theming/theme-package.html

I've gotten as far as the individual xml files for the types, bobtemplates does not allow you to create any more than one type when it makes up a package for a dexterity type, and the example in the docs calls for three types to be made; you could create as many types as you wanted with zopeskel/paster addcontent, but I'm not using paster addcontent, I'm using bobtemplates, so how do I do that?

As I told you on IRC, there's currently no equivalent in bobtemplates.plone. You must understand one of the following (eventually, both, so you can choose which you prefer, it's mostly a matter of taste):

  • which of the existing files/classes need to be duplicated in order to add a new content type: basically your type interface in interfaces.py, and your type registration and definition in profiles/default/types.xml and profiles/default/types/yournewtype.xml
  • how to create a content type through the web and then export its XML into your site package (the first link I posted)

Now we're talking! Thanks for this response! This one is so important I have to deal with it in a separate reply!

I have to start by saying that (of course) I'm following this document: Dexterity Developer Manual. It is a tutorial style introduction to Dexterity, however it appears to be built around a previous version of plone. So the first place I tripped was here: Creating a package. I won't exhaustively go over the fact that in the very first info bar it mentions that you can find a completed version of the package you're about to build (example.conference) in the collective repository. And of course, it is no longer there.. anyway... the first place I tripped in earnest was the paragraph below that where it gives you the commandline to run zopeskel. Of course, zopeskel does not come with plone anymore (I'm using plone 4.3.9) so here started a world of trouble trying to get zopeskel to work with my new plone.. I won't go into all of my adventures here, but I'll just say that the closest I came was installing zopeskel in a separate virtualenv. that seemed to work except that I thought it didn't modify my plone's buildout.cfg but this was where I veered from docs.plone.org and I'd gone to training.plone.org and my boss told me that there was probably something that was included in a step that was documented several chapters earlier which I had missed because the dexterity part is in chapter 13.. But this is not about training.plone.org it's about docs.plone.org..

I subsequently installed bobtemplates and I managed to adapt the code in my package to what I was seeing in the docs; I realized the interfaces were in interfaces.py and not in their own files (Session.py, Program.py) anymore, I found the message factory in the package root, and the part in configure.zcml what tells generic setup how to make my package installable. I was doing well enough until I reached The FTI (Adding a Factory Type Information object for the type). where I then needed to add/edit an XML file for each of the types, where the file name matches the type name. This is where I'm now stuck. As I said earlier, I prefer to be intentional in my code writing, I prefer to write my code knowing exactly what each clause does, I would prefer not to blindly copy-and-paste code and see what effect that has.. (there's a place for that, but not as part of my normal process) @davilima6 linked to a document which I'm not sure describes the API of the files in question.

BTW: While writing this, I was amazed at how much I'm sounding like I know plone! lol! These gymnastics I've been having to put myself through have taught me a lot about plone, but I believe I would be FAR more knowledgeable if I had a current set of docs to just go to and read through and do the examples from- instead of guessing why this doesn't work and why that doesn't do what the docs say it should and then having to strategize as to what to do next after that failure...

I can understand your preferences. However, it is extremely difficult to have an accurate and detailed documentation for even the major Plone versions used in the wild - especially where things like "best practises" are involved. Code and (even more so) "best practises" tend to change far more rapidly than the documentation which lets the documentation outdate fast.

Things in the Plone world are mostly good: things usually are well named, follow some general principles, are quite straight forward (despite some important exceptions). This means, one can use the available documentation and examples to get quite a good feeling about how things work. It is not good enough to prevent occasional surprises; but, for me, those surprises make the work interesting.

The first link I sent you refers to the XML model syntax. I mentioned other files, like views:

And the type info and FTI:

Good readings. There's nothing out of date in these.

The link you quote is a pretty good resource for understanding (some) of the FTI - I've not understood it all yet myself. But to start with I would suggest you ignore everything below <!-- View information --> on that page.
Though I now see that mrbob orders things differently, so to summarize briefly what you need....
I ran mrbob twice to build different types - "Boot" then "Shoe", that creates the FTI files for both correctly (though other files like interfaces.py & types.xml will not be correct). The differences are as follows:

$ diff collective.foo/src/collective/foo/profiles/default/types/*.xml 
    < <object name="Boot" meta_type="Dexterity FTI" i18n:domain="collective.foo"
    > <object name="Shoe" meta_type="Dexterity FTI" i18n:domain="collective.foo"
    <   <property name="title" i18n:translate="">Boot</property>
    >   <property name="title" i18n:translate="">Shoe</property>
    <   <property name="factory">Boot</property>
    <   <property name="add_view_expr">string:${folder_url}/++add++Boot</property>
    >   <property name="factory">Shoe</property>
    >   <property name="add_view_expr">string:${folder_url}/++add++Shoe</property>
    <   <property name="schema">collective.foo.interfaces.IBoot</property>
    >   <property name="schema">collective.foo.interfaces.IShoe</property>

Which shows you the fields that are essential to change between different types.
Does that help?

1 Like

Could you also answer why you think you need a new content type and why the online content types in site setup aren't good enough for your needs?