One of the best features of the Plone Content Management System (CMS) is the fact that you can define content types easily by using the Archetypes schema language. With Archetypes, you list the attributes of a content type and it takes care of all the details of persisting objects to Plone’s object database, displaying objects in a web page, and providing edit forms and validation for users to create and update objects. When such objects reflect the entities of a business process, you create a new web application using only the schema language. For more information on working with the Plone Content Management System see the first article in this series The Plone Content Management System
But, you can simplify things one step further by drawing a class diagram instead of using the schema language. You’ll have a nearly full-fledged web application—writing zero lines of code.
In the dark ages of object-oriented programming, developers could not communicate with each other because they were cursed and all spoke a different language—a different modeling language, that is. But, thanks to the Unified Modeling Language (UML), developers finally got a common diagramming lingua franca that enables them to share object oriented designs. Today, numerous tools let you draw UML diagrams and export those diagrams to code generation systems, metadata repositories, and more.
If you don’t yet have a UML drawing tool, go ahead and download version 0.24 of ArgoUML. ArgoUML is free and open source software that works on Windows, Mac OS X, Linux, and a variety of other Java-capable platforms. The screen shots in this article all come from ArgoUML, so even you have another UML tool, you might want to use ArgoUML just to follow along.
You’ll need one other tool: ArchGenXML. ArchGenXML is what bridges the UML model with Archetypes. For this article, you’ll use version 1.5.2. Go ahead and install it, but keep that tool off to the side for right now. The first thing you need to do is prepare your class diagram. You’re about to re-create the DVD catalog application from the last article, but this time by painting it instead of coding it.
Preparing Your Tool
When you first start ArgoUML, you’ll be presented with a empty model with two diagrams ready to use: a class diagram and a use case diagram:
Ignore the use case diagram; you won’t be using it. For now, click on the name of the model (untitledModel) on the left side and give it a proper name down in the “name” box in the “Properties” section that appears after you click it: DVDCollection.
Next, you’ll need to set up definitions for tagged values. Tagged values are annotations you can apply to parts of your model. ArchGenXML looks for annotations that tell it how to generate certain parts of the Archetypes schema and class definitions. If you do a lot of modeling for Archetypes/Plone, you might even find it useful to create an otherwise empty model that has all the possible tagged value definitions already set up—thereby avoiding this tedious step in the future.
To add a new tag definition, make sure your model DVDCollection is selected in the left side, and the “Properties” section is showing at the bottom of the window. Click the “New Tag Definition” button, and then fill in its name. Click the “New Tag Definition” button again to create another one, and fill in its name. Repeat until you’ve entered tag definitions for all of the following tag names:
In the last article, you defined—in code—a DVD class that represented a single DVD in your collection. Now, you’ll paint that class. Click “Class Diagram 1” in the left-side of the window to make your one (and only) class diagram active. Now, click the “New Class” button in the toolbar:
Click anywhere on the canvas to place your new class. Down in the Properties section of the window, enter the name for the class: DVD. Provide some documentation that tells what the class represents, and then annotate that class with some tagged values.
Click the “Documentation” section. Here, you can fill in class-level details about the author and version number of the class (you can do this for the whole model as well). For now, just fill in a comment in the “Documentation” block, something like “A DVD represents a single DVD video in the collection.” This text will appear in the tool-tip help when you finally generate the web application, so watch out for typos!
Next, click on the “Tagged Values” section. You’ll now annotate the class using the some of the tag definitions you set up earlier. If you’re using ArgoUML, the documentation you just entered has automatically appeared as one of your tagged values. You just need to add three more: content_icon to tell what icon to use on-screen to represent objects of the DVD type, archetype_name to specify the user-friendly name of the type, and typeDescription to provide an on-screen description of the type (similar to way the documentation is used to show a tool-tip for the type, and, in fact, should almost always be the same text).
To add a tagged value, click in the blank area under the “Tag” column. A menu will appear with your tag definitions; click to select one. Then, click to the right of that tag and enter the value as text. The following screen shot shows how the tagged values for the DVD class should be set up:
The DVD class certainly doesn’t have much character about it, does it? You’ll make it much more interesting by adding attributes to the class that capture the characteristics of a DVD. Just like in the last article, the attributes will include a DVD number (so you can find it on the shelf), a running time (in minutes), a rating (so you can keep your kids from seeing Grindhouse until they’re 17, for example), and a selection of genres to which the movie belongs.
To add an attribute, click the Properties section at the bottom of the window and then click the “New Attribute” button, as shown below:
For the first attribute, enter the name dvdNumber and leave the data type as int. Then, click the Tagged Values section and annotate this attribute with the values shown below:
Your DVD class now has a place to store the number of the DVD. Now, return to the Properties section of the dvdNumber attribute and click the “Go Up” button as shown below:
This button navigates you up out of the attribute and back into the DVD class where you can then add more attributes with the “New Attribute” button. Add three more attributes as outlined below:
- Add runningTime as an int with the following tagged values:
- Add rating as a String with the following tagged values:
- Add genre as a String with the following tagged values:
|widget:description||Length of the movie in minutes|
|vocabulary||['G', 'PG', 'PG-13', 'R', 'NC-17']|
|widget:description||MPAA rating assigned to the movie|
|vocabulary||['Action/Adventure', 'Comedy', 'Drama', 'Family', 'Romance', 'Spaghetti Western']|
|widget:description||Artistic style of the movie|
You’re done with the DVD class! In your UML tool, you should have a single class that looks something like this:
Wait! There’s no “title” attribute! Where do you place the name of the movie? As with the last article, the title attribute comes automatically. You don’t have to put one in manually. Just about every object in Plone has a title of some sort.
Generating the Code
Now that you’ve painted your DVD class, you’re ready to generate the code that implements the DVD Collection product. First, you need to export your model into a format that the ArchGenXML tool can read. The standard format for the interchange of models is called XMI, which stands for XML Metadata Interchange. Most UML tools have a menu item that let you export your model as XMI. With ArgoUML, it’s on the “File” menu. Export the model to a file called dvd.xmi and save it in a convenient directory.
If you recall from the last article, a Plone product is a directory under the Products directory in which the server is installed. In that article, you created a directory called DVDCollection and populated it with files and subdirectories by hand. This time, you’ll let the ArchGenXML tool do it for you. So, if you still have the old DVDCollection directory, you need to get rid of it:
- Start your Plone server.
- Log in as your administrative user.
- Click “site setup” and then click “Add/Remove Products.”
- Check the box next to your old “DVDCollection” product and click Uninstall.
- Stop your Plone server.
- Delete the DVDCollection directory under the Products directory.
This will make Plone and the Products directory ready to accept your new, automatically-generated DVDCollection.
Now, open a command prompt or terminal window (depending on your operating system) and navigate to the Products directory. Once there, run ArchGenXML on the dvd.xmi file. Windows users would do something like the following:
C:>cd "c:Program FilesPlone 2DataProducts" C:Program FilesPlone 2DataProducts>ArchGenXML.py c:dvd.xmi
Mac OS X, Linux, and other Unix users would do something similar to below:
% cd/Applications/Plone-2.5.2/Instance/Products % ArchGenXML.py ~/dvd.xmi
ArchGenXML reads the XMI file and determines what classes and schema to generate, creating them and all of the boilerplate necessary for a new Plone product. (You can re-run ArchGenXML as often as you like with newer versions of the XMI file; it will update the files as necessary to keep the product up-to-date.)
As when you hand-made the product (in the last article), ArchGenXML creates a specific set of files and subdirectories that Plone (and its underlying application server) expect. There is just one small thing you need to do by hand: place the icon for the DVD class, dvd.gif, into the DVDCollection/skins/DVDCollection subdirectory. If you don’t have a copy of it from the last article, help yourself to this one: .
You’re in the home-stretch now! All that remains is to try it out!
Trying It Out
Restart your Plone server now and log in as an administrator. Click “site setup” and then click “Add/Remove Products.” The automatically generated DVDCollection product should appear in the list of products available for installation. Check the box next to it and click the “Install” button.
Now, head over to your home folder by clicking “my folder” in the blue personal bar. Then, click the green “add item” menu and choose to add a new DVD. Fill in the form and click Save. For example, here I’m entering the details for DVD #41 on my shelf:
That’s it! You’ve now created a new product with a single content type and made it a web application without even firing up your favorite text editor. As before with the hand-made version, you can search for this DVD using Plone’s LiveSearch or advanced search, see it in folder listings, and update its attributes. All the features such as template generation, form generation, validation, and so forth are still there.
Was this really less work? Maybe not in the case of a product with just a single content type. But, painting your web applications and generating the code with ArchGenXML really pays off when you start subclassing content types, add aggregation relationships, add composition, take advantage of references, and use workflow. Painting all of these things is a lot easier and less error-prone than typing it all in. Including these object-oriented concepts will turn this “toy” DVD collection application into a real heavy duty web application. But, that will have to wait until next month!
For more information on ArchGenXML, do check out the following links:
- Tagged Value Overview lists the currently supported tag values and what parts of a model you apply them to.
- ArchGenXML—Getting Started is a tutorial that explores more deeply what you can do with a UML tool and ArchGenXML.
- Getting Your Feet Wet with Plone is an online movie I’ve made that demonstrates using ArgoUML and ArchGenXML, albeit with older versions of each.
About the Author
Sean Kelly routinely fools his clients in the media, medical, and aerospace industries into believing he’s an insanely efficient web application developer—when all he really does is paint out the web applications, add a few icons, and take an early lunch prominently featuring martinis. He’s available for hire, if the preceding statement hasn’t scared anyone off.
He lives in a house that he also paints (but with actual brushes and pigments) with his wife and daughter, who are genuinely concerned about his practice of doing touch-up around the place after a martini-heavy lunch.