Christopher Warner "So, it's not like the code is my brain; keep it"

Creating a Content Type for Plone 3.x

So you have installed Plone now you want to get to the business of filling it with all of your content. You start by searching on the Plone website for a way to create your own custom content type so you can begin management of the data. However, it’s all a confusing mess to you; you’re a halfway decent programmer, but you’re not a brain surgeon and you want to go to lunch today.

Here is a straight-forward and quick way to do this with a Plone 3.x installation.

1. Go to your Plone installation directory.
2. Change directory to your zinstance/src directory so for example /home/cwarner/Plone/zinstance/src
3. Run the command ../bin/paster create –list-template

We have many templates to select from here but in our case we just want to create a simple content type based on Archetypes (a discussion on this later). So we’ll use the archetype template.

1. Run the command ../bin/paster create -t archetype

We are going to create a DVD content type to hold all of the information for our DVD’s. So we answer all the following questions:

1. The title of our Project in this case I chose “DVD Content” because I was excited.2. The Namespace package question revolves around the namespace you want your content type to belong to. This is more programmer related and involves a discussions on namespaces but suffice to say that you don’t need to be too concerned at this point. You can safely leave it at the default of plone.

3. The package contained in the namespace you chose above. So for example if you chose “cool” for question two. In question three your choice would be appended to “cool”. So if we choose “ness” or “beans” for our answer here the final result will be “cool.ness” or “cool.beans”. Again this involves a discussion about Namespaces but for our example we just let it be “dvd”. So our final result would be “plone.dvd”

4. We are always creating a Zope 2 Product because Plone is still a Zope 2 application for all intents and purposes. There are things Plone can do that rely on Zope 3 but for compatibility purposes it’s currently Zope 2. So this question will mostly always be True at least for Plone 3.x

5. Version of the product; You can choose any version number you’d like!

6. Description of the product in one line; a short description is good here.

7. A longer description of the product. Notice the in reST in parenthesis; this just takes the longer description of your product and converts it into HTML so that it can be used to publish your package in a public repository.

8. The author’s name of the package; That’s me with a couple of typos

9. My email address which at this point all the spambots have chewed threw numerous times over

10. Keywords or Tags will help others find our project should we decide to publish it on PyPi which is the Python Packaging Index allowing other developers a chance to find our content-type. In this case because it’s just a one off content-type and an example we won’t be publishing for the masses so it doesn’t matter what you put here.

11. URL and home page can be anything. Normally people just put a link to the subversion repository for the code of our content-type; especially if it’s going to be published but you can put any valid URL here.

12. License of the content, whether it’s opensource or not. GPL, BSD, MIT, etc

13. Zip safe; This question for the most part dealing with Plone 3.x will always be False. This goes back to a time where packages/content types were distributed in zip form and in our case that will never be true.

Great, now that we’ve created the base skeleton for what is to be our new content type we can list the files on the filesystem which reveals our newly created “dvd” directory.

We can now change directory into our dvd directory and list the filesystem. There are many files in here but for right now let us just run the following command.

../../bin/paster addcontent -l

This gives us a handy list of all the available templates we can use to create our content type and not surprisingly the one we need is right there. “contenttye: A content type skeleton”. So let’s do it.

1. Enter the contenttype_name; It’s a DVD, and this is what we are managing information about so we ‘DVD’ sounded like a good content type name2. The description of the DVD; we could of said “Digital Video Disc” but I didn’t think about it when I just typed that.

3. Is the content type folderish? This means that should we be able to create or add other content types into our DVD. For example this would come in handy lets say if we had a content type called Movies and in that content type we wanted to add other content types like a DVD or VHS. So we could have a Movie named “Cast Away” and if it was folderish add the DVD copy of the movie or the VHS copy of the movie, or whatever other content types we created that could be attributed to the parent Movie content type. In this case we don’t want to add anything else to our DVD content type so we answer False

4. Global_allow is a flag that allows us to add our DVD content type to anywhere in the hierarchy of our site.

5. Allow_discussion this allows commentary on the content type. This doesn’t mean commentary in the way most people think about it; at least not for our uses. Let us say one of our employees at TimexWarner (our fictional company) added a DVD to our database and we as the editors of this DVD collection came across an error. This would allow us to comment on the error and have that employee fix it. Or we could have a discussion about the validity of a piece of information attributed to a DVD, or the spelling of name all in private without affecting the piece of content on our public facing website or intranet.

Once these questions are answered the skeleton of our content type has been created and we are almost halfway there.

Now remember the brief namespace non-explanation earlier? Here is where it comes into play we are going to change directories into plone and then into dvd. Remember (plone.dvd) if you chose something else as in (cool.beans) you’d be changing directories into cool/beans.

Once we are in the dvd directory we see the “content” directory. This is the meat of the whole content-type so we change directory again and cd content and list the filesystem, we see three files. Great.. The one we are inerested in right now is the dvd.py file.

You can open this file with your favorite text editor. In my case that would usually be Vim but lately i’ve been use something called TextMate and it’s proven to be quite capable.

Here’s where we get to the point where you can begin adding what you consider a DVD to be made of in my case here are the attributes I need for every single DVD in my collection.

1. Publisher
2. Length in running minutes of the DVD
3. The ISBN
4. The MPAA Rating of the DVD
5. The color of the film whether it’s color or black & white.

These are the only 5 attributes that are required of me and so we can begin adding this information to our skeleton Schema called “DVDSchema” on line 14.

We’ll begin at line 16 but first we are going to need two reference sheets and if you are going to be creating Plone Content types of on a regular basis it’ll help to have them printed out. Our Fields reference and our Widget reference.

In the creation of our schema you’ll have a representative field that utilizes a widget. So lets start with each of our attributes.

1. Publisher:
atapi.StringField(
name='dvdPublisher',
widget=atapi.StringWidget(
label=u'DVD Publisher',
label_msgid='PloneDvd_label_dvdPublisher',
il8n_domain='PloneDvd',
maxlength=50,
size=50,
),

required=False,
searchable=True
)


So the Publisher attribute has the following representation in our DVDSchema and it’s pretty straight forward. The name of the field is dvdPublisher and it’s a StringField. It is not required but it is searchable meaning that you can search the database for it. The StringWidget size and maxlength are 50 characters. We aren’t going to discuss the label_msgid and il8n_domain flags because it involves it’s own discussion or post in the future. In any event we will see how this correlates in a final picture but lets continue.

2. Length in minutes
atapi.IntegerField(
name='dvdLength',
widget=atapi.IntegerWidget(
label=u"DVD Length",
label_msgid='PloneDvd_label_dvdLength',
il8n_domain='PloneDvd',
size=3
),
required=False,
searchable=True
),


3. ISBN Number
atapi.StringField(
name='dvdISBN',
widget=atapi.StringWidget(
label=u'DVD ISBN',
label_msgid='PloneDVD_label_dvdISBN',
il8n_domain='PloneDvd',
maxlength=13,
size=13,
),

required=False,
searchable=True
),

4. DVD MPAA Rating
atapi.StringField(
name='dvdRating',
widget=atapi.StringWidget(
label=u'DVD MPAA Rating',
label_msgid='PloneDVD_label_dvdRating',
il8n_domain='PloneDvd'),

vocabulary=["G", "PG", "PG-13", "R", "NC-17"]
required=False,
searchable=False

5. DVD Film Color
atapi.StringField(
name='dvdColor',
widget=atapi.StringWidget(
label=u'DVD Film Color',
label_msgid='PloneDVD_label_dbdColor',
il8n_domain='PloneDvd'),

vocabulary=["Black & White", "Color"],
required=False,
searchable=True
),

The full schema should resemble something like this:

That complete we can save the file and from here the next step is getting our content type safely installed into Plone. This involves modifying our buildout configuration or buildout.cfg file. This file is usually located in your zope instance directory so in our case /home/cwarner/Plone/zinstance/buildout.cfg. Open the file in your favorite text editor and let’s begin modification. You want to search for the “Eggs” heading (an egg is simply a way of distributing a python package similar to a zip file or tarball if you are familiar with that) and add “dvd” into the section. As that’s the name of our content type that we are developing and it’s the name of the egg that will be created.

Next we search for the “Development Eggs” section again; this is a content type that we are developing so we have to add “dvd” into the section as well but in this case we put the actual directory where our content type is located.

Next up we add the ZCML slug for our content type package. So search for the ZCML slug section and recall the namespace non-discussion because it comes into play here. It will come up here again, so we chose plone for our parent namespace and dvd for our sub namespace which made it plone.dvd. If you chose cool then beans then you’d put cool.beans.

Save the file and exit your favorite editor here. At this point we have to run buildout to re-read the configuration file and package and apply our content type so it’s ready for Plone on start/restart.

We will use the command bin/buildout -voN; which basically means run buildout in verbose mode, offline mode (we haven’t done anything that needs to be pulled from online) and in non-newest mode meaning that buildout won’t go out on the internet searching for new distributions of packages for Plone at this time.

Once complete Plone should have our new content type and we should be able to restart Plone and see it in our setup. Navigate your way to the add-on products section in Site Setup and you should see our content type listed there. Proceed to select it and install it and it should show up under the installed products section.

From here we are complete we can now add a piece of dvd content to Plone so let us try it.

And we are done! There is so much more that one can do with your content type. As you become more versed in creating custom content types this will take you all of 10 minutes to do. Next in this series of what I’m calling ‘The Pre-book” we will be displaying your content data on a highly visible website with roughly 1 million unique visitors a day.