Criando um tipo de conteúdo Plone para desenvolvedores

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 will just let it be “dvd”. 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. 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. PyPi 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 does not matter what you put here.

11. URL and home page can be anything. Normally one just links to the subversion repository for the code of our content-type. Especially if it’s going to be published, but you may 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

Mmaglis notes: When one issues the command: ../../bin/paster addcontent -l and it returns: Command 'addcontent' not known (you may need to run setup.py egg_info). You should then run the following command: ../../../Python-2.4/bin/python2.4 setup.py egg_info to correct this

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. “contenttype: 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 ‘DVD’ sounded like a good content type name

2. The description of the DVD; we could have said “Digital Video Disc” unfortunately I did not think about it at the time.

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 with 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, and/or the spelling of name. All this takes place 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 interested 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 this case here are a couple of the attributes we will 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 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 will 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. 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 
) 


The Publisher attribute has the following representation in our DVDSchema and it is pretty straight forward. The name of the field is dvdPublisher and it is 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 its 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. 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 us begin modification. You will 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 is the name of our content type that we are developing, it is also 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. However instead of the just the name of the egg we specify the directory or path 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 comes 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 read our updated configuration file 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 Site setup for Adding and Removing Products. 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. It should then show up under the installed products section.

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

Great, 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.

Now that you are finished here, you may want to theme or add a different 'view' to your content-type. Please see the documentation on Creating a custom template for a Plone content type.

Should you have any questions about this tutorial. You can contact me on irc on freenode. My username is 'cwarner'.