What is ArchGenXML

With ArchGenXML you can create working python code without writing one single line of python. It is a command-line utility that generates fully functional Zope Products, based on the Archetypes framework, from UML models using XMI (.xmi, .zargo, .zuml) files. The most common use-case is to generate a set of custom content types and folders, possibly with a few tools, a member type and some workflows thrown in.

In practice, you draw your UML diagrams in a tool like ArgoUML or Poseidon which has the ability to generate XMI files. Once you are ready to test your product, you run ArchGenXML on the XMI file, which will generate the product directory. After generation, you will be able to install your product in Plone and have your new content types, tools and workflows available.

At present, round-trip support is not implemented: custom code can't be converted back into XMI (and thus diagrams). However, you can re-generate your product over existing code; method bodies and certain "protected" code sections will be preserved. This means that you can evolve your product's public interfaces, its methods and its attributes in the UML model, without fear of losing your hand-written code.

ArchGenXML is hosted at svn.plone.org as a subproject of the Archetypes project. It is released under GNU General Public Licence 2 or later.

Why should I use ArchGenXML?

Major reasons:

• You want to save time
• You are a lazy programmer
• You don't like to reinvent the wheel
• You don't like copying and pasting code (and bugs)
• You make heavy use of references and interfaces
• You have big projects with many different custom types
• You want or need a well-documented interface to your product
• You like structured model- and pattern-driven software development
• You want to maintain your project in future without getting a headache

and many other good and odd reasons.

Contributors

The project was initially started by Phil Auersperg. Thanks to his laziness :-)

Authors

Phil Auersperg (Project Leader)

BlueDynamics Alliance, Auersperg-Castell KEG, phil@bluedynamics.com,

Jens Klein (Release Manager, Developer and Doc-Writer)

BlueDynamics Alliance, Klein & Partner KEG, jens@bluedynamics.com,

Reinout van Rees (Co-Release Manager, Developer and Doc-Writer)

ZestSoftware

Fabiano Weimar dos Santos (Ideas, Testing, Bugfixing, Workflow)

Weimar Desenvolvimento e Consultoria em Informatica Ltda., xiru@xiru.org,

Martin Aspeli (Improvements, bug fixes and documentation)

Martin Aspeli

Robert Niederreiter (Lots of base work on AGX 2.0)

Robert Niederreiter

and others

thanks to everybody who contributed with testing, doc-writing or code-pieces!

Sponsors

• Xiru.org, Brazil (Fabiano Weimar dos Santos) sponsors a valuable amount of money into workflow support (State diagrams -> DCWorkflow, will go into release 1.2),
• PilotSystems, Paris, France (David Sapiro),
• OpenSource.ag, Innsbruck, Austria (Georg Pleger).

If you want to contribute ArchGenXML by improving the code, helping with documentation or sponsoring money to make us improve it, please contact one of us.

Preconditions

• You need a working Python interpreter, version 2.4+.
• You need Plone 2.5.3+ or Plone 3.0.1+ installed (choose the latest stable release) and its dependencies to see your generated code in action. Plone 3 is supported by the subversion-trunk.
• You need the libraries of Zope 2.10 (or Zope 3.3) available in your system. ArchGenXML needs them to run, not the generated code.
• We also recommend upgrading Archetypes to the latest stable release, preferably latest 1.4.x, 1.5.x or later.

Download & Installation

The trunk is planned to be always stable, because development is done on branches.

using easy_install

with easy_install configured, you can download and install ArchGenXML using the Python Cheeseshop.

Just type easy_install archgenxml.

ArchGenXML will be installed in your Pythons library directory, a symlink to the executable will be placed into the directory your system normally would expect user executable binaries.

from the tarball (*.tgz) or subversion

You need to download the release tarball of ArchGenXML from plone.org's products section. Choose the most recent version or use the bleeding edge development version - best choice with latest Plone Versions - from the Subversion repository.

• untar tar xzf ArchGenXML-2.xy.tgz to a directory of your choice.
• change into the directory cd ArchGenXML
• start python setup.py install or
• on Debian based systems you can build your debian package with fakeroot debian/rules binary and install the package with for example dpkg -i archgenxml_2.0_i386.deb - and remove it later - without any garbage left or
• ArchGenXML will be installed in your Pythons library directory, a symlink to the executable will be placed into the directory your system normally would expect user executable binaries.

on Debian based systems such as Debian or Ubuntu

• add XX TODO to your package sources, for example edit /etc/apt/sources
• apt-get update
• apt-get install archgenxml
• you can use for above tasks the package-manager of your choice (such as Synaptic).

after installation configuration

You need to tell ArchGenXML where to find Zope 3.3 or Zope 2.10 (which includes Zope 3.3.). You can include the path to your Zope into the PYTHONPATH. This has one major disadvantage: A Zope instance running on your system might get confused by it, which might result in fancy behaviour of Zope.

A better solution is to provide a file .agx_zope_path in your users HOME-directory. Put one single line with the full /PATH/TO/zope2.10/lib/python in here. ArchGenXML will add it to its internal python library search path and will find the zope modules.

Additional software

To get all the features of ArchGenXML, you may need some of the following.

For code generation:

i18ndude

Without this, the generation of translatable user interface strings is disabled. Instructions/ download

Stripogram

Some UML tools produce HTML in the documentation elements in XMI. Stripogram converts them into plain text. Without having Stripogram installed this feature is disabled. Download and install stripogram from the squishdot project on sourceforge.net.

For running the generated code (optional)

ATVocabularyManager

Enables usage of custom dynamic vocabularies. Download and install the product

Relations

enables complex references. Download and install the product

CompoundField

enables usage of multiplicity on fields an definition of fields as a compound of other fields. Download and install the product

Remember

enables contentish custom member objects. Download and install the product

UML Tools

ArchGenXML processes models stored in XMI. This XML format isn't intended to be written in a plain text editor nor in a tree based XML editor, so you will almost certainly use a UML design tool. Below is a more or less complete list of such tools. If you know about any others tools missing from this list, have more detailed information or have experience with a tool in combination with ArchGenXML, please write the author a short e-mail.

ArgoUML

Website and download: argouml.tigris.org

Read Using ArgoUML with ArchGenXML.

• Free software
• Written in Java
• Runs on most platforms
• Stores the model natively as XMI + diagram information in .xmi, .uml. or .zargo files (ziped .uml files).
• No undo (planned for future)
• Some known, but non-critical bugs

Poseidon (by Gentleware)

Website and download,

• Commercial software - so called Community Edition for low-cost license available, supports XMI version 1.2
• Written in Java, runs on most platforms
• commercial fork of ArgoUML (theres no synchronisation between projects)
• Stores the model natively as XMI + diagram information in .zuml files (zip files)
• Is very slow and needs lots of memory and a fast CPU

ObjectDomain

Website and download: objectdomain.com

• Commercial, free time-limited demo for <= 30 classes
• Written in Java
• Runs on most platforms
• Need to export model from proprietary .odm format to .xmi

Powerdesigner (by Sybase)

Website and download: sybase.com

• XMI version 1.1
• Need to export model to xmi

Umbrello (KDE)

Website and download: uml.sourceforge.net

• Free software
• Runs under Linux/KDE
• Stores the model natively as XMI
• At the time of testing (somewhere in the first half of 2004), Umbrello wasn't complete and the XMI not 100% standards compliant. Umbrello promises to support XMI correctly on version 1.4, which will be shipped with KDE 3.4. (please report your experience).

An almost complete list of UML tools can be found at www.jeckle.de/umltools.htm.

UML - the Unified Modeling Language - is a graphical language designed to describe software through diagrams. There are several different types of diagrams available, but the ones most relevant to ArchGenXML are:

• The class diagram
• The state diagram

Class diagrams are used to draw interfaces, content types (represented as classes) and tools (represented as classes with the portal_tool stereotype), as well as the attributes and public operations on these. In addition, associations in the diagram show how objects are aggregated within or referenced from one another.

The goal of model-driven development is to create the "blueprints" for your software in a well-defined, easily-communicated format: the UML model and diagram thereof. You can design your model using visual tools until you have a structure which adequately represents your needs, and ArchGenXML will generate the necessary code.

You probably have to customise that code somewhat, filling in method bodies, creating new page templates etc., but ArchGenXML takes care of all the boilerplate for you. With tagged values and stereotypes you can customise the generated code with a surprising degree of flexibility and control, and when you need to hand-code something, ArchGenXML won't overwrite your changes (provided you stick to the protected code sections, clearly marked in the source code).

This manual does not aim to teach you UML and object-oriented, model-driven software development. There are several other fine manuals about that on the web. A very good starting point is the OMG UML Resource Page including its web-links to tutorials.

For a quick-start read Practical-UML chapters class-diagram and state-chart-diagram.

Open the UML tool of your choice. Make a new UML model and give it a name HelloWorld. Then add a class diagram (most UML tools do this automatically).

Choose the tool for class creation and add a class to the diagram. Give it a name such as "HelloType" and add an attribute HelloText with type String. The helloworld3.zargo (Plone 3.0) / helloworld25.zargo (Plone 2.5) was created with ArgoUML and contains the type as described above.

Generating the product

Save/export your model as an XMI file with the name MyFirstExample.xmi (or in an XMI-container format like .uml, .zargo or .zuml). Then go to the command line and execute:

  $ archgenxml helloworld.zargo

ArchGenXML will begin code generation. When it completes, you will have a new folder HelloWorld on your file system. Its contents looks like:

  HelloWorld/
  |-- Extensions
  |   |-- Install.py
  |   `-- __init__.py
  |-- __init__.py
  |-- config.py
  |-- configure.zcml
  |-- hellotype.py
  |-- interfaces.py
  |-- profiles
  |       |-- cssregistry.xml
  |       |-- factorytool.xml
  |       |-- import_steps.xml
  |       |-- jsregistry.xml
  |       |-- skins.xml
  |       |-- types
  |       |   `-- HelloType.xml
  |       `-- types.xml
  |-- profiles.zcml
  |-- refresh.txt
  |-- setuphandlers.py
  |-- skins
  |   |-- helloworld_images
  |   |-- helloworld_styles
  |   `-- helloworld_templates
  `-- version.txt

Installing and using the generated product

Move the whole folder HelloWorld to your Zope/Plone 3 instance's Products folder. Restart Zope, open Plone in a browser and log in as Manager. Choose Plone Setup from the personal bar and choose Add/Remove Products. A new product HelloWorld should now appear in the list of products available for install. Choose it and click install. Go to your personal folder. In the list of addable items you'll find the new product as an addable content type. Add a test instance to see if it works.

Thats the trick. By the way: the title is always part of the schema. But you can hide it or recycle it later, don't worry

Overview

By default, when you create a class in your class diagram, it represents an Archetypes content type. You can add operations in your model to generate methods on the class, and attributes to generate fields in the schema. The quick reference at the end of this tutorial will tell you which field types you can use. You should also browse the Archetypes quick reference documentation to see what properties are available for each field and widget type. You may set these using tagged values (see below).

There are three basic ways in which you can alter the way your content types are generated:

• You may set one or more stereotypes on your class, which alters the "type" of class. A stereotype <<portal_tool>>, for example means you are generating a portal tool rather than just a simple content type.
• You can use tagged values in your model to configure many aspects of your classes, their attributes and their methods. A list of recognised tagged values acting on classes, fields and methods are found in the quick reference at the end of this tutorial.

  When reading tagged values, ArchGenXML will generally treat them as strings, with a few exceptions where only non-string values are permitted, such as the required tagged value. If you do not wish your value to be quoted as a string, prefix it with python:. For example, if you set the tagged value default to python:["high", "low"] on a lines attribute, you will get default=["high", "low"] in a LinesField in your schema.

• ArchGenXML is clever about aggregation and composition. If your class aggregates other classes, it will be automatically made into a folder with those classes as the allowed content types. If you use composition (signified by a filled diamond in the diagram) rather than aggregation, the contained class will only be addable inside the container, otherwise it will be addable globally in your portal by default.

Variants of Content Types

Simple Classes

A simple class is what we had in HelloWorld in the previous chapter. A simple class is based on BaseContent and BrowserDefault'. This is the default if no other options override.

Folderish Classes

The easiest way to make a content type folderish is to introduce composition or aggregation in your model - the parent class will become folderish and will be permitted to hold objects of the child classes. You can also make a class folderish just by giving it the <<folder>> stereotype. Both of these approaches will result in an object derived from BaseFolder.

You can also give a class the <<ordered>> stereotype (possibly in addition to <<folder>>) in order to make it derive from OrderedBaseFolder and thus have ordering support. Alternatively, you can set the base_class tagged value on the class to OrderedBaseFolder. This is a general technique which you can use to override the base folder should you need to. As an aside, the additional_parents tagged value permits you to derive from multiple parents.

Another option is to derive from ATFolder (from ATContentTypes) by giving the class the stereotype <<atfolder>>.

Other tagged values which may be useful when generating folders are:

filter_content_types

Set this to 0 or 1 to turn on/off filtering of content types. If content types are not filtered, the class will act as a general folder for all globally addable content.

allowed_content_types

To explicitly set the allowable content types, for example to only allow images and documents, set this to: Image, Document. Note that if you use aggregation or composition to create folderish types as described above, setting the allowed content types manually is not necessary.

Portal tools

A portal tool is a unique singleton which other objects may find via getToolByName and utilise. There are many tools which ship with Plone, such as portal_actions or portal_skins. To create a portal tool instead of a regular content type, give your class the <<portal_tool>> stereotype. Tools can hold attributes and provide methods just like a regular content type. Typically, these hold configuration data and utility methods for the rest of your product to use. Tools may also have configlets - configuration pages in the Plone control panel. See the quick reference at the end of this document for details on the tagged values you must set to generate configlets.

Abstract mixin classes

By marking your class as abstract in your model (usually a separate tick-box), you are signifying that it will not be added as a content type. Such classes are useful as mixin parents and as abstract base classes for more complex content types, and will not have the standard Archetypes registration machinery, factory type information or derive from BaseClass.

Stub classes

By giving your class the <<stub>> stereotype, you can prevent it from being generated at all. This is useful if you wish to show content types which are logically part of your model, but which do not belong to your product. For instance, you could create a stub for Plone's standard Image type if you wish to include this as an aggregated object inside your content type - that is, your content type will become folderish, with Image as an allowable contained type.

Deriving/Subclassing Classes

Deriving or subclassing a class is used to extend existing classes, or change their behavior. Using generalisation arrows in your model, you can inherit the methods and schema from another content type or mixin class in your class.

Simple Derivation

All content types in Archetypes are derived from one of the base classes - BaseContent, BaseFolder, OrderedBaseFolder and so on. If you wish to turn this off, for example because the base class is being inherited from a parent class, you can set the base_class tagged value to 0.

Multiple Derivation

You can of course use multiple inheritance via multiple generalisation arrows in your model. However, if you need to use a base class that is not on your model, you can set the additional_parents tagged value on your class to a comma-separated list of parent classes.

Deriving from other Products

If you want to derive from a class of an other product create a stub class with a tagged value 'import_from': This will generate a import line from VALUE import CLASSNAME in classes derived from this class.

Deriving form ATContentTypes

To derive from ATDocument just use a stereotype <<atdocument>>. Also possible with <<atfile>>, <<atevent>> and <<atfolder>>.

Packages - bring order to your code

Packages are both a UML concept and a Python concept. In Python, packages are directories under your product containing a set of modules (.py files). In UML, a package is a logical grouping of classes, drawn as a large "folder" with classes inside it. To modularise complex products, you should use packages to group classes together.

Archetypes are using schemas (also called schemata) with fields to define the form-fields on your content. The schema and its fields of your content types is generated from the attributes of your classes in your model and their tagged values. Each field has a type and a widget.

The Archetypes documentation and the quick reference at the end of this document describes which fields are available and what parameters they take as configuration.

Usage of tagged values

If you set a tagged value on an attribute of your class, in general that tagged value will be passed through as a parameter to the generated Archetypes field. Hence, if you set a tagged value enforceVocabulary to the value 1 on an attribute, you will get enforceVocabulary=1 for that field in the generated schema. Similarly, you can set a field's widget properties by prefixing the tagged value with widget:. widget:label sets the label of a widget, for instance.

Non-string tagged values

As before, when reading tagged values, ArchGenXML will generally treat them as strings, with a few exceptions where only non-string values are permitted, such as the required tagged value. If you do not wish your value to be quoted as a string, prefix it with python:. For example, if you set the tagged value default to python:["high", "low"] on a lines attribute, you will get default=["high", "low"] in a LinesField in your schema.

field recycling - copy from parents schema or another source schema and modify

This feature alows you to copy a field from another source schema and rename the field.

Rather than subclass an entire class then delete unwanted fields, you can explicitly copy just the fields you need. You can keep the copied field "as-is" or modify it by overriding properties with tag values as needed.

For example you may need a Description field that is usually defined in your parent classes (BaseContent, BaseFolder) Schema. You would create a new attribute in your class named description with a type of copy. If you want it to appear in your base_edit form rather then the default of properties/metadata page you just need to change one property of the field by adding the tag schemata = "default".

You may also copy from any other schema or from within the same schema. You need to specify the source schema using the tag copy_from and if you need to rename the field use the source_name tag to indicate the source field Id, otherwise the Id of the field in you schema is used.

Index and metadata in catalogs and Collection

ArchgenXML can create configuration files to create an index and/or metadata entries in the catalog such as portal_catalog.

Available are the following tagged values:

catalog:index

add the field to the index. Boolean, 1 or 0. Default is 0. If set, you may need to provide index:* tagged values too.

catalog:metadata

add the field to the metadata record on the query result? Boolean, 1 or 0. If you do not provide index:attributes, the name of the accessor of the field is the default. If catalog:metadata_accessor is given it will be used instead.

catalog:metadata_accessor

the accessor used for the metadata (string).

catalog:name

sometimes you need to add an index to a other catalog than portal_catalog and its XML-File catalog.xml. Provide a tuple of comma separated strings, id of the catalog and the filename of its configuration file. default is "portal_catalog, Plone Catalog Tool'.

index:type

the type of index used as (string), for example FieldIndex, KeywordIndex, DateIndex or any available index in your portal. For known types a default is guessed, such as FieldIndex for StringFields or DateIndex for DateFields. If no guess is possible, we assume a FieldIndex.

index:attributes

the attributes to use for index (string or comma separated list of strings). This are the methods called at indexing time. Normally it is enough to provide one index method, but for some specific use cases you might need to provide alternatives. If you do not provide this tagged value, the name of the accessor of the field is the default.

index:name

the name of the index used (string). Use this name in your queries. If you do not provide a name, the name of the accessor of the field is the default.

index:extras

some indexes are using so called extras on installation as configuration. If the index need extras you'll need to declare them here. provide a comma separated list.

index:properties

some indexes are using properties on installation as configuration. If the index need properties you'll need to declare them here. Provide a comma separated list.

collection:criteria

add the index to the Collection (aka Smart Folder) Indexes available for defining Criteria. Provide a comma seprated list of criteria that will be available by default. Available criterias are: ATBooleanCriterion, ATDateCriteria, ATDateRangeCriterion, ATListCriterion, ATPortalTypeCriterion, ATReferenceCriterion, ATSelectionCriterion, ATSimpleIntCriterion, ATSimpleStringCriterion, ATSortCriterion, ATCurrentAuthorCriterion, ATPathCriterion, ATRelativePathCriterion. You must provide an index:type as well.

collection:criteria_label

the display name of the collection:criteria, called friendly name (string). Its added to the generated.pot as a literal. If not given the widget:label is taken if provided.

collection:criteria_description

a help text (string), used for collection:criteria. Its added to the generated.pot as a literal. if not provided the widget:description is used.

collection:metadata

register the catalog:metadata as an available column in a Collection. Can be used as an alternative for catalog:metadata. catalog:metadata_accessor is used if given.

collection:metadata_label

the display name of the collection:metadata, called friendly name (string), used for index:criteria. Its added to the generated.pot as a literal. If not given the widget:label is taken if provided.

collection:metadata_description

a help text (string), used for collection:criteria. Its added to the generated.pot as a literal. If not provided the collection:criteria_help or - if not provided - widget:description is used.

DEPRECATED For backward compatibility reasons we support a sub part of the old style in ArchGenxML Version 1.6 and earlier using the tagged value index. This is deprecated and will be removed in one of the next version of ArchGenXML. A tagged value index with value like index:type above creates an index with the accessor. To include the index in catalog metadata (and have the attribute ready to use in the brain objects), append :brains (same as older :schema), (e.g. FieldIndex:brains). ArchGenXML does longer provides the ability to define multiple indexes using the old declaration style.

ArchGenXML will pick a default widget for your fields and fill in default labels and descriptions. For example, a string field gets a StringWidget by default, but a selection field type gets SelectionWidget on a StringField! You can override this in two ways. So ArchGenXML mixes up fields and widgets slightly for convinience reasons. Anyway, you can override all predefined definitions using widget options.

Widget options are specified with the prefix widget:. As with normal field tagged values, unrecognised options will be passed straight through to the widget definition.

The most common widget options are:

widget:type

sets the widget type used. Its the name of the widget class. You can use all widgets shipped within the Archetypes-Framework by just providing this tagged value. To use 3rd-Party widgets you additionally need to import the class using the imports tagged value on class level.

widget:label

sets the widget's label

widget:description

sets the widget's description

widget:label_msgid

overrides the default label message id (i18n)

widget:description_msgid

overrides the default description message id (i18n)

widget:i18n_domain

sets the i18n domain (defaults to the product name)

You may also use widget-specific options, such as widget:size where they apply. Look up possible widget-specific options at the documentation of the widget you want to use.

Changing the default widgets

To change the widget used for one field-type for a whole model, a product, a package or just for all fields in one class you can set on the product, package or class level the tagged value default:widget:FIELDNAMEABBREVIATION to WIDGETNAME. For example use the tagged value default:widget:Reference set it to ReferenceBrowserWidget to use the ReferenceBrowserWidget instead of the ReferenceWidget. You might also want to also use the imports tagged value and set it to from ATReferenceBrowserWidget.ATReferenceBrowserWidget import ReferenceBrowserWidget on your class to ensure that you get the widget definition imported into your class.

Creating new widgets

To define a new widget add a class to your model with the <<widget>> stereotype.

To create a method in your class, add a method to the UML diagram, with the desired parameters. The types of the parameters and the type of the return value are ignored, since Python does not support this.

Methods can different access specifiers (also called visibilities) These are:

public (shown by a + before the method name)

The method is part of the class' public interface. It will be declared public (accessible from unsafe/through-the-web code) by default. If you add a tagged value permission (see below), it will be declared as protected by this permission.

protected (#)

The method is not part of the class' public interface, but is meant for use by sub-classes. It will be declared private to prevent unsafe code from accessing it.

private (-)

The method is internal to the class. It will be declared private to prevent unsafe code from accessing it.

package (~)

The method is intended to be accessed by other code in the same module as the class. It will not gain any Zope security assertions, relying instead on the class/module defaults.

There are a few tagged values you can use to alter how the code is generated:

code

Sets the python code body of the method. Only use this for short one-liners. If you fill in code manually in the generated files, method bodies will be preserved when you re-generate the product from the UML model.

documentation

Content of the python doc-string of the method. You can also use the documentation feature of most UML modellers to set documentation strings.

permission

Applies to methods with public visiblity only. If you set the permission tagged value to My custom permission results in security.declareProtected("""My custom permission""",methodname) - that is, access to your method is protected by the permission with the name My custom permission.

If you want to use the CMF core permissions, add an imports tagged value to the method's class containing from Products.CMFCore import permissions, and then set the permission tagged value of your method to python:permissions.View, python:permissions.ModifyPortalContent or any other core permission. You can also use the common paradigm of defining permissions in config.py as constants with names like EDIT_PERMISSION. A config.py is automatically generated and its contents imported, so you can just set the permission tagged value to, for example, python:EDIT_PERMISSION.

Archetypes uses actions for generating custom tabs to access some view of an Archetype object. ArchGenXML can generate actions for you: Just define a method without any parameters and set its stereotype to <<action>>.

Once again tagged values can be set on the sterotyped methods in order to set some properties of the action:

action

The TAL expression representing the action to be executed when the user invokes the action. Defaults to the methodname.

category

The category of an action, view or form. Defaults to object.

id

The id of an action, view or form. Defaults to the methodname.

label

The label of an action, view or form. Defaults to the methodname.

permission

permission=My permission results in 'permissions': ('''My Permission''',). See the description of the general permission tagged value above for more.

condition

A TALES expression giving a condition to control when the action is to be made available.

You can override the default Archetypes actions by using special names for the id. These are:

view

for overriding the default view action.

edit

for overriding the default edit action.

contents

for overriding the default contents action.

With aggregations, compositions and associations you define where your new type will show up, what it might contain and to which content it can point to.

There is virtually no limit on how many aggregations, compositions and associations you can attach to a class.

Aggregations: Global Containment

Aggregation means: This content can exist global and in this container. The container class that gets the empty rhomb (diamond) attached is derived from BaseFolder and it's allowed_content_types is set to the class that is attached to it.If more than class is attached to one class by aggregations the allowed_content_types is extended accordingly. The attached class keeps the default ``global_allow=1``.

Compositions: Strict Containment

Compositions are used to model parts that exist or live and die with their associated owner. So the code generated is similair to the one generated by aggregations, but with one major difference: The attached classes are only allowed to be generated in the folderish type of the class they're attached to (this is done by setting ``global_allow=0`` in the factory type information of the class).

Directed Associations: References

References are used to store the relation of an object to other objects.

Each content type that derives from ``IReferenceable`` is capable of being referenced. Objects from such a content type have an UID (Unique Identification) that's unique throughout the whole Plone site. Therefore References don't break if you move referenced objects around in the site.

To use ``ReferenceFields`` there are two possible ways. The by models-design clean way is to use directed associations. Another possibility is to define References as class-attributes.

Directed Associations

An directed association between two classes generates a ``ReferenceField`` in the class where the association starts.

The ``relationship`` itself is named after the association's name.

The multiplicity defines if the allows a 1:1 or 1:n relation. Attention: This only results in validation on the field. References at all don't know anything about multiplicity, so this is only a check on userinterface-level.

All other field settings are taken from the association's end, including information how to generate the widget. By default a ReferenceWidget is used. You can use tagged values on the association's end to define label, description, a different widget-type, schemata, etc. like you do it on a field (on a class attribute).

The big drawback of using associations to create ReferenceFields is that they always get attached to the end of the schema and there is no way to change that in the UML diagram. So if you need order in your fields read the next section.

References as class attributes

You can define an attribute with the type reference. Then you can apply any needed tagged values to it.

keys of interest are:

    allowed_types : needs a list of allowed types

    multiValued   : set to 0 to only be able to select one object to reference to

    relationship  : name of the relationship in the reference_catalog

The benefit of using an attribute to define the reference is that you can define the place in the schema where the ReferenceField will show up.

Reference classes (advanced)

Sometimes it's needed to store information not in the origin or destination class, but in the reference itself. UML has a notation to model this: association classes

ArchGenXML support them automatically. When a model includes an association class, two things occur:

a) A new content type is created, named like the association name

b) The generated ReferenceField has a new attribute defined like this: ``referenceClass = ContentReferenceCreator(My_Association_Name)``

This causes that the class of the reference instances is now not "Archetypes.ReferenceEngine.Reference", but "Archetypes.ReferenceEngine.ContentReference", a subclass of it that has a new method: getContentObject(), that return the content inside the reference.

The same effect can be reached without association classes, by defining a content type and then adding the "association_class" tagged value to the association (although I haven't been able to make this work).

To create the reference via code, use a special form of the addReference method:

    origin = <the origin content>
    destination = <the destination content>
    assocName = <the association name>

    origin.addReference(destination,
                        assocName,
                 referenceClass=ContentReferenceCreator(assocName),
                 attr1=value1,
                 attr2=value2...)

    (where attr1, attr2... are the attributes of the association)

To read the data, we can't use the origin.getRefs(assocName) method, as usual, because it returns only the destination objects. One way to read it is by using the reference_catalog tool:

    from Products.CMFCore.utils import getToolByName
    tool = getToolByName(origin, 'reference_catalog')
    refs = tool.getReferences(origin, assocName)
    if not refs:
        return []
    else:
        return [(ref.getContentObject(), ref.getTargetObject()) for ref in refs]

ArchGenXML can use state diagrams to generate workflows for a portal type. Workflows are used to set the various states an object can be in, and the transitions between them.

Importantly, workflows control permissions of objects. By convention, and for convenience and consistency, most content types will use the permissions found in the CMFCorePermissions class in the CMFCore product to control access to their methods. The methods generated by and inherited from the CMF and Archetypes frameworks adhere to this principle. Although many different content types use the same basic permissions to control access, workflows are the means by which you can control permissions for an object in detail. For instance, you may wish to specify that in the testing state, Manager and Reviewer has Modify portal content permissions, and Owner, Manager and Reviewer has View permissions. For the completed state, you could have a different set of permissions. See the DCWorkflow documentation for more details about how to use workflows.

Problems with UML-Software

The workflow implementation of ArchGenXML has to date only been tested with ArgoUML and Poseidon (tested Version is 3.1 and 3.2 CE).

ObjectDomain is known not to work at this time, because it does not appear to correctly export the XMI for state diagrams. If you have different experiences, please add a comment to this document or contact us.

Creating a workflow

In your UML modeller, add a state diagram for the class you wish to create a custom workflow for. If you don't want to assign the workflow to a class use an class with stereotype stub. In Poseidon, this is done by right-clicking on the object in the tree on the left hand side, and selecting to add a new state diagram. The name of the state diagram becomes the name of the workflow.

States

On the state diagram, add a state item (a rounded-corner box) for each state. You must have an initial state of your workflow for it to work correctly. Use a "initial state" symbol (filled cirlce) for the state your object defaults to after creation. Optional you can use a normal state item and set a tagged value initial_state with value 1 to it.

At present, ArchGenXML does not support the "final state" UML symbols to represent final states, so you should stick to the standard state symbols.

The names of your states in UML become the names of the states in your workflow. The user-visible label can be set with the label tagged value; it defaults to the state name.

Transitions

For each possible transition between states, add a transition arrow to your UML model. The name of the transition becomes the name of the workflow action. You can set the label tagged value on the transition to set a custom label to display to the user.

If a transition with the same name/target is used more than one time, you can use the stereotype <<primary>> to define its settings once and use it by name on all similar transitions.

Transition guards

You can add a guard to a transition to restrict to whom and when it is made available. Set the expression field of a transition to a |-separated list of the following pairs:

guard_roles

Set guard_roles:Owner; Manager to restrict the transition to users posessing the Owner or Manager role in the current context.

guard_permissions

Set guard_permissions:My custom permission;View to ensure that only those users with My custom permission or View permissions in the current context are allowed to access the transition.

guard_expr

Set 'guard_expr:expression", where expression is a TALES expression, to have the expression be evaluated in order to determine whether the transition should be made available.

Thus, to restrict access to roles Reviewer and Manager, and only those users with permission My custom permission and View in the current context, you can set the expression of the transition to guard_roles:Reviewer;Manager|guard_permissions:My custom permission, View.

If you are using Poseidon, transition guards are located in the property of the transition arrow with the name [A] Guard. You can add an expression like the one outlined above to this field.

Permissions

ArchGenXML uses tagged values on states in a somewhat unconventional, though convenient, way to control permissions. With the exception of the special-case initial_state and label tagged values, you give the name of the permission as the tagged value key, and a comma-separated list of roles the permission should be enabled for as the value.

There are three shorthand permission names available:

access

referes to the Access contents information permission,

view

refers to the View permission,

modify

refers to the Modify portal content permission,

list

refers to the List folder contents permission.

delete

refers to the Delete objects permission.

Hence, if you want your state to permit anonymous users and members to view your content, only permit managers to modify, and permit both the owner and managers to add new objects controlled by the Add MySubTypes permission, you can add tagged values to the workflow state:

    view           ==> Anonymous, Member
    modify         ==> Manager
    Add MySubTypes ==> Owner, Manager

If you want to aquire the permissions and add new ones you can use the value 'aquire':

    view           ==> acquire, Anonymous, Member

(One special case: if you leave the value empty, no one gets that permission (which is logical), but it also explicitly unsets acquisition of the permission).

Workflow actions

The portal_workflow tool allows a script to be executed before and/or after a transition is completed. ArchGenXML lets you specify the names of these actions, and will generate an external method for you to implement for each uniquely named action in your workflow.

Actions are set using the effect field of a transition. The value given here gives the name of the action method to execute (and thus must be valid python method name). ArchGenXML will create or modify a script containing external methods for each workflow, in Extensions/<WorkflowName>_scripts.py in your product. You must fill in the method bodies for the actions in this script. Method bodies will be preserved upon re-generation of your product from the UML model.

By default, actions specified in this way are post-transition actions, meaning that they are executed after the transition has taken place. If you wish to specify a pre-transition action, executed before the transition takes place, separate action names by semicolons: preActionName;postActionName. If you want only a pre-transition action, use preActionName; to specify that there is an empty post-transition action.

Attach workflow to more than one class

In UML there is no semantic to use a workflow for more than one class. We introduced the tagged value use_workflow for classes. Value is the workflow name.

Worklist support

You can attach objects in a certain state to a worklist. A worklist is something like the "documents to review" list you get when you're a reviewer in a Plone site. This is done by adding a tag worklist to the state with the name of the worklist as value (like review_list).

You can add more than one state to a worklist, just by specifying the same name for the worklist tagged value. Likewise, you can have more than one worklist (just not on the same state). The tagged value worklist:guard_permissions allows you to specify the permission you need to have to view the worklist. The default value is Review portal content.

Overview

We hope there is no need for us to emphasize how important testing is for even the most simple products you may be developing. This makes it especially useful to include the creation of both your testing framework and individual tests within your UML model.

Within a new package with a stereotype of <<tests>> you can create your base test case class with a stereotype of <<plone_testcase>> and a test setup class with a stereotype of <<setup_testcase>>. You can then add additional test classes as needed with a stereotype of either <<testcase> or <<doc_testcase>>.

Base Test Case

Creating a class in your tests package with a stereotype of <<plone_testcase>> generates the needed base test case for all other test cases.

Test Setup

Creating a class in your tests package with a stereotype of <<setup_testcase>> generates a testcase for the setup, with pre-defined common checks.

Test Cases

Test Case

Creating a class in your tests package with a stereotype of <<testcase>> generates a standard test case class.

Doc Tests

Creating a class in your tests package with a stereotype of <<doc_testcase>> generates a doc test file in the doc folder of your product with a name of class + .txt. You can use the tag of doctest_name on your class (excluding any extension as .txt is appended automatically) to indicate a different name for your generated doc test.

Functional Tests

Generate browser functional tests using the <<plonefunctional_testcase> stereotype.

Interface Tests

Generate interface tests using the <<interface_testcase>> stereotype.

It is unverified whether these generated test cases will verify Z3 style interfaces but stay tuned!

ATVM manages dynamic vocabularies. It installs a tool, where a site Manager can add, change and delete vocabularies. These vocabularies can then be used anywhere on the site.

You can download ATVocabularyManager from the Plone.org products area: http://plone.org/products/atvocabularymanager

Using simple flat vocabularies

Adding ATVM-vocabs to your UML model is quite easy.

1. Add a selection or multiselection field to your type.
2. Add a tag vocabulary:name and give it a name, let's say countries
3. Add a tag vocabulary:type with the value ATVocabularyManager

We are now finished with the UML. Save it and let AGX do the work. What still is missing, is to install the countries vocabulary. Therefore:

• Add a function called setupVocabularies to the protected code section in setuphandlers.py in your product and register it as an import step in /profiles/default/import_steps.xml in a code section (make it dependend from you *QI-Dependencies step.
• Add the following code to your setuphandler.yp (this sets up a vocabulary countries with the given values, and registers it with ATVocabularyManager):

     from Products.ATVocabularyManager.config import TOOL_NAME as ATVOCABULARYTOOL
     from Products.CMFCore.utils import getToolByName
     from Products.ATVocabularyManager.utils.vocabs import createSimpleVocabs
  
     def setupVocabularies(context):
       """let's install the countries vocab"""
  
       vocabs = {}
       vocabs['countries'] = (
              ('ice', u'Iceland'),
              ('nor', u'Norway'),
              ('fin', u'Finland'),
              ('tyr', u'Tyrol'),
              ('auf', u'Ausserfern'),
          )
       site = context.getSite()
       atvm = getToolByName(site, ATVOCABULARYTOOL)
       createSimpleVocabs(atvm, vocabs)
  

Using simple tree vocabularies

If youre interested in using and creating hierachical vocab:

• use additional tag vocabulary:vocabulary_type with value TreeVocabulary,
• have a look at the doc-string of Products.ATVocabularyManager.utils.createHierarchicalVocabs.

Using vocabularies based on the IMS Vocabulary Definition Exchange (VDEX) format.

VDEX is a simple XML based format to define flat or hierachical multilingual vocabularies. ATVocabularyManager supports VDEX in most of its dialects.

To tell Archetypes to use them in your UML first take Steps 1 to 3 of the first section and skip the import part. Then add a tag vocabulary:vocabulary_type and give it the value VdexVocabulary.

Now add a folder called data in your products folder. Inside the /data folder create a new file called countries.vdex (example). It will be imported automatically on install or reinstall, but only if a vocabulary named countries does not exist.

Prerequisites

To enable Relations install the Product (code-location).

Basics

As an option on command line, up to a tagged-value on model-level or on a single UML-Association you just define the relation_implementation and set it to relations. A directed Assoziation results in one Relation.

Give the association and its assoziation ends names. They'll be used as the names for the RelationField. If you dont want a field turn it off by setting a tagged value generate_reference_fields on class (or package, model) level to 0.

Inverse Relation

If the association is not directed (navigable on both association ends) an inverse relation will be created.

The tagged-value inverse_relation_name will be used for the back-relation on undirected associations. It defaults to a relation named toend_fromend, where these are the lowercased versions of the association ends. If the two ends are named the same, then the relation will be named association_inv, where association is the name of the association. (Finally, if the option old_inverse_relation_name is set, then it defaults to the association name postfixed by _inverse.)

Cardinality

You can use the Multiplicity on in UML to define the cardinality of an Relation. You can use the minimum and maximun value here using the syntax 1..5 which means at least one relationrelated objects but not more than five.

Constraints

type-constraint

as described above an association between two portal-types will be created.

interface-constraint

an association between an archetypes class and an interface will create an interface-constraint. the relation is allowed to all classes implementing this interface.

Association classes

Association classes can be used to store data on the relation as an object. You can model it using the UML association class or using a tagged value association_class on the association.

Prerequisites

You must install to additional Products:

• membrane
• remember (using Five 1.4.3+)

You should also read the documentation of both and understand how they work!

A Content-Type based on remember

• Create a class in your class diagram and give it a a stereotype <<remember>>
• add the tagged value use_workflow and set it to one of member_approval_workflow or member_auto_workflow. You can create also your own workflow if you know what remember needs (look at the workflows shipped with remember).
• set the active_workflow_states tagged value to the class and declare which states of the used workflow are the ones, where the user can log in with. It expects a list of values, e.g. python:["private", "public"]
• Add attributes (fields) as you need. Attention here, only override fields of remembers BaseMember schema if you know what youre doing.
• Generate & Done

Prerequisites

Install the CompoundField extension into you Products folder.

List of fields - ArrayField

Assume you want to have content type where the user can provide one or more files. Its easy by making the type folderish. But for some use-cases this is to heavy or to difficult, you want the user to use a form for those files.

You could say, ok, up to 5 files is enough and model 5 file fields into your class. Not very elegant, huh?

The easiest way is to to use the UML multiplicity feature on your attribute aka field of the class. If you want to enable unlimited attachments use multiplicity *. Or choose a number like 5, as in our above example.

You can set the initial size of the array by using the tagged value array:size to python:10 for example. Prefixed with array: you can access also the label array:widget:label of it and so on. If you prefer the EnhancedArrayWidget you need to add an tagged value imports from Products.Compoundfield.EnhancedArrayWidget import EnhancedArrayWidget to your class and set on the attribute the tagged value array:widget:type to EnhanceArrayWidget.

Custom Fields compounds - CompoundField

With ArchGenXML you can create compounds of fields from existing fields. Such a set of fields behaves almost like a normal field. To create such a compounded field create a new class and give it the stereotype <<field>&gt

Now add attributes to it like you would do on a content type class. You can use almost every field type, just some special fields, mostyl those acting as a proxy without own storage, wont work (such as ReferenceField or AttachementField).

For example we create a PointField consisting out of two FloatFields by just adding a x and y attribute of type float.

To use the new field create a fresh content class and name it Polygon. Take a dependency arrow pointing from your Polygon class to the field class. This ensures it gets imported!

Next add an attribute points to the class. The type of the new points attribute is PointsField. Now to make it a polygon give it a multiplicity of *and your done: You have a list of Points as one field.

Prerequisites

You must install the Content Flavors product.

Adding a field to an existing content type

1. Let an existing content type, e.g. "ExistingType", be present in your diagram (as a class with stereotypes <<archetype>> and <<stub>>)
2. Create a class, e.g. "MyCoolFlavor", in your diagram and give it the <<flavor>> stereotype
3. Add any field(s), e.g. "MyAdditionalField", to this flavor class
4. Create a realization arrow from "ExistingType" to "MyCoolFlavor"
5. Generate & Done

Now every new instance of ExistingType will have the MyAdditionalField field in its schema, default view and default edit form.

Limits

• Content Flavors also allows custom views to be used by existing types but this feature is not supported by ArchGenXML yet.
• You may not be able to see the additional field(s) if the ExistingType uses some non-default view. You then have to manually manage this by overriding these existing views with some of your own, with or without the help of the Content Flavors product.
• The existing content type may have to be based on ATCT (to be tested)?
  
• Several flavors can be applied to a given type. The order of precedence can be managed through the web if the existing type follows some requirements detailed in the Content Flavors documentation.
• There are possible issues with indexing the additional fields, see CF documentation for details.
• Content Flavors is still somehow experimental and may some day become deprecated in favour of some other schema extension mechanism if proven superior. For instance, you may want to give a try to archetypes.schemaextender.

TODO: UPDATE!

Complete list of the field types including their default settings:

string

StringField

• StringField
• searchable=1

text

TextField

• StringField
• searchable=1
• TextAreaWidget()

richtext

TextField

• TextField
• default_output_type=text/html
• allowed_content_types=(text/plain,text/structured,text/html,application/msword,)

selection

StringField with SelectionWidget

• StringField

multiselection

LinesField with SelctionWidget

• LinesField
• multiValued=1

integer

IntegerField

• IntegerField
• searchable=1

float

Floatfield

• FloatField
• searchable=1
• DecimalWidget()

boolean

BoleanField

• BooleanField
• searchable=1

lines

LinesField

• LinesField
• searchable=1

date

DateTimeField

• DateTimeField
• searchable=1

image

ImageField

• ImageField
• sizes ={'small':(100,100),'medium':(200,200),'large':(600,600)}
• AttributeStorage()

file

FileField

• FileField
• AttributeStorage()
• FileWidget()

lines

LinesField

• LinesField
• searchable=1

fixedpoint

FixedPointField

• FixedPointField

reference

ReferenceField

• ReferenceField

backreference

BackReferenceField

• BackReferenceField

computed

ComputedField

• ComputedField

color

StringField w/Color picker

• StringField

country

StringField

• StringField
• CountryWidget

datagrid

DataGridField

• DataGridField
• DataGridWidget

photo

PhotoField

• PhotoField

Tagged values for fields:

searchable

register and index the field in the catalog,

• 1 .. register and index
• 0 .. don't register and index

storage

AttributeStorage(), SQLStorage(), ....

sizes

defines the sizes of the images in a ImageField example: python:{'small':(80,80),'medium':(200,2000),'large':(600,600)}

default_method

no idea what that does

required

defines whether a field should be rendered required, or not.

• 1 .. field is required
• 0 .. field is not required

accessor

defines the accessor of a field

vocabulary

defines the vocabulary or the method generating a vocabulary

allowed_types

defines the allowed types in a ReferenceField

relationship

defines the relationship, used in a ReferenceField

multiValued

defines whether a SelectionField accepts one or more values,

• 1 .. multivalued
• 0 .. singlevalued

These tagged values are just the ones handy for fields, the full lists of tagged values and stereotypes are shown on the next two pages.

This file was generated 2007-09-14

action/form/view

action

For a stereotype action, this tagged value can be used to overwrite the default URL (..../name_of_method) into ..../tagged_value.

category

The category for the action. Defaults to object.

condition

A TALES expresson defining a condition which will be evaluated to determine whether the action should be displayed.

form

For a stereotype form, this tagged value can be used to overwrite the default URL (..../name_of_method) into ..../tagged_value.

id

The id of the action. Use id,

label

The label of the action - displayed to the user.

view

For a stereotype view, this tagged value can be used to overwrite the default URL (..../name_of_method) into ..../tagged_value.

visible

Sets the visible property, default to True

association

association_class

You can use associations classes to store content on the association itself. The class used is specified by this setting. Don't forget to import the used class properly.

association_vocabulary

Switch, defaults to False. Needs Product ATVocabularyManager. Generates an empty vocabulary with the name of the relation.

back_reference_field

Use a custom field instead of ReferenceField.

field

Synonymous with either reference_field or relation_field, depending on whether you use it on the from end or the to end of a relation. Works only together with Relations Product and relation_implementation set to relations.

inverse_relation_name

Together with Relations Product you have inverse relations. the name default to name_of_your_relation_inverse, but you can overrrule it using this tagged value.

label

Sets the readable name.

reference_field

Use a custom field instead of ReferenceField.

relation_field

Use a custom field instead of RelationField. Works only together with Relations Product and relation_implementation set to relations.

relation_implementation

Sets the type of implementation is used for an association: basic (used as default) for classic style archetypes references or relations for use of the Relations Product.

relationship

Standard relationship for ReferenceField

attribute

accessor

Set the name of the accessor (getter) method. If you are overriding one of the DC metadata fields such as title or description be sure to set the correct accessor names such as Title and 'Description'; by default these accessors would be generated as getTitle() or getDescription().

array:widget

specify which custom ArrayWidget should be used for a field (only applies if the field has cardinality >1.

catalog:attributes

The attributes to use for index or metadata (string or comma separated list of strings). This are the methods called at indexing time. Normally it is enough to provide one index method, but for some specific use cases you might need to provide alternatives. If you don not provide this tagged value, the name of the accessor of the field is the default.

catalog:index

Add the field (or all fields of a class, package, model) to the index. Boolean, 1 or 0. Default is 0. If set, you may need to provide index:* tagged values too.

catalog:metadata

Adds the field to the metadata record on the query result. Boolean, 1 or 0. If you do not provide index:attributes, the name of the accessor of the field is the default. If catalog:attributes is given for each attribute one field at the record will be created.

catalog:name

Sometimes you need to add an index to a other catalog than portal_catalog and its XML-File catalog.xml. Provide a tuple of comma separated strings, id of the catalog and the filename of its configuration file. default is "portal_catalog, Plone Catalog Tool'.

copy_from

To copy an attribute from another schema, give it the type copy. The tagged value copy_from is then used to specify which schema to copy it from (for instance, BaseSchema when copying Description from the base schema). For copying your own schemas, add an imports tagged value to import your class (say MyClass) and then put MyClass.schema in your copy_from value.

default

Set a value to use as the default value of the field.

default_method

Set the name of a method on the object which will be called to determine the default value of the field.

enforceVocabulary

Set to true (1) to ensure that only items from the vocabulary are permitted.

index

DEPRECATED: Add an index to the attribute. Use catalog:index and the index:* tagged value instead.

index:extras

Some indexes are using so called extras on installation as configuration. If the index need extras you'll need to declare them here. Provide a comma separated list.

index:name

the name of the index used (string). Use this name in your queries. If you do not provide a name, the name of the accessor of the field is the default.

index:properties

Some indexes are using properties on installation as configuration. If the index need properties you'll need to declare them here. Provide a comma separated list.

index:type

the type of index used as (string), for example FieldIndex, KeywordIndex, DateIndex or any available index in your portal. For known types a default is guessed, such as FieldIndex for StringFields or DateIndex for DateFields. If no guess is possible, we assume a FieldIndex.

label

Sets the readable name.

multiValued

Certain fields, such as reference fields, can optionally accept more than one value if multiValued is set to true (1)

mutator

Similarly, set the name of the mutator (setter) method.

original_size

Sets the maximum size for the original for an ImageField widget.

read_permission

Defines archetypes fields read-permission. Use it together with workflow to control ability to view fields based on roles/permissions.

required

Set to true (1) to make the field required

schemata

If you want to split your form with many, many attibutes in multiple schemata ("sub-forms"), add a tagged value schemata to the attributes you want in a different schemata with the name of that schemata (for instance "personal data"). The default schemata is called "default", btw.

searchable

Whether or not the field should be searchable when performing a search in the portal.

sizes

Sets the allowed sizes for an ImageField widget.

source_name

With attribute type copy sometimes schema-recycling is fun, together with copy_from you can specify the source name of the field in the schema given by copy_from.

validation_expression

Use an ExpressionValidator and sets the by value given expression.

validation_expression_errormsg

Sets the error message to the ExpressionValidator (use with validation_expression to define the validation expression to which this error message applies).

validators

TODO. Not supported for now.

vocabulary

Set to a python list, a DisplayList or a method name (quoted) which provides the vocabulary for a selection widget.

vocabulary:name

Togther with Products ATVocabularyManager this sets the name of the vocabulary.

vocabulary:term_type

For use with ATVocabularyManager. Defaults to SimplevocabularyTerm. Let you define the portal_type of the vocabularyterm used for the default term that is created in Install.py.

vocabulary:type

Enables support for Products ATVocabularyManager by setting value to ATVocabularyManager.

widget

Allows you to set the widget to be used for this attribute.

widget:description

Set the widget's description.

widget:description_msgid

Set the description i18n message id. Defaults to a name generated from the field name.

widget:i18n_domain

Set the i18n domain. Defaults to the product name.

widget:label

Set the widget's label.

widget:label_msgid

Set the label i18n message id. Defaults to a name generated from the field name.

widget:type

Set the name of the widget to use. Each field has an associated default widget, but if you need a different one (e.g. a SelectionWidget for a string field), use this value to override.

write_permission

Defines archetypes fields write-permission. Use it together with workflow to control ability to write data to a field based on roles/permissions.

class

active_workflow_states

The active workflow states for a remember type. MUST be set on <> types. Format is [state, 'anotherstate'].

additional_parents

A comma-separated list of the names of classes which should be used as additional parents to this class, in addition to the Archetypes BaseContent, BaseFolder or OrderedBaseFolder. Usually used in conjunction with imports to import the class before it is referenced.

allow_discussion

Whether or not the content type should be discussable in the portal by default.

allowable_content_types

A comma-separated list of allowed test format for a textarea widget.

allowed_content_types

A comma-separated list of allowed sub-types for a (folderish) content type. Note that allowed content types are automatically set when using aggregation and composition between classes to specify containment.

archetype_name

The name which will be shown in the "add new item" drop-down and other user-interface elements. Defaults to the class name, but whilst the class name must be valid and unique python identifier, the archetype_name can be any string.

author

You can set the author project-wide with the --author commandline parameter (or in the config file). This TGV allows you to use/ overwrite it on a class level.

base_actions

Sets the base actions in the class's factory type information (FTI).

base_class

Explicitly set the base class of a content type, overriding the automatic selection of BaseContent, BaseFolder or OrderedBaseFolder as well as any parent classes in the model. What you specify here ends up as the first item (or items: comma-separate them) in the classes it inherits from. So this is also a handy way to place one class explicitly in front of the other. See also additional_parents.

base_schema

Explicitly set the base schema for a content type, overriding the automatic selection of the parent's schema or BaseSchema, BaseFolderSchema or OrderedBaseFolderSchema.

catalog:index

Add the field (or all fields of a class, package, model) to the index. Boolean, 1 or 0. Default is 0. If set, you may need to provide index:* tagged values too.

catalog:metadata

Adds the field to the metadata record on the query result. Boolean, 1 or 0. If you do not provide index:attributes, the name of the accessor of the field is the default. If catalog:attributes is given for each attribute one field at the record will be created.

catalog:name

Sometimes you need to add an index to a other catalog than portal_catalog and its XML-File catalog.xml. Provide a tuple of comma separated strings, id of the catalog and the filename of its configuration file. default is "portal_catalog, Plone Catalog Tool'.

catalogmultiplex:black

Remove an archetypes class (identified by meta_type) from one or more catalogs to be cataloged in. Comma- separated list of catalogs. Example-value: portal_catalog, another_catalog. Explaination: Instances of the class wont be catalogged in portal_catalog anymore.

catalogmultiplex:white

Add an archetypes class (identified by meta_type) to one or more catalogs to be cataloged in. Comma- separated list of catalogs. Example-value: myfancy_catalog, another_catalog. Explaination: Additionally to the default portal_catalog the instances of this class will be catalogged in the two given catalogs.

content_icon

The name of an image file, which must be found in the skins directory of the product. This will be used to represent the content type in the user interface.

copyright

You can set the copyright project-wide with the -- copyright commandline parameter (or in the config file). This TGV allows you to use/ overwrite it on a class level.

creation_permission

Sets the creation permission for the class. Example: Add portal content.

creation_roles

You can set an own role who should be able to add a type. Use an Tuple of Strings. Default and example for this value: ("Manager", "Owner", "Member").

default_interface_type

default type of interfaces (z2 or z3).

default_view

The TemplateMixin class in Archetypes allows your class to present several alternative view templates for a content type. The default_view value sets the default one. Defaults to base_view. Only relevant if you use TemplateMixin.

description

A description of the type, a sentence or two in length. Used to describe the type to the user.

detailed_creation_permissions

Give the content-type (types in the package, model) own creation permissions, named automagically ProductName: Add ClassName.

disable_polymorphing

Normally, archgenxml looks at the parents of the current class for content types that are allowed as items in a folderish class. So: parent's allowed content is also allowed in the child. Likewise, subclasses of classes allowed as content are also allowed on this class. Classic polymorphing. In case this isn't desired, set the tagged value disable_polymorphing to 1.

display_in_navigation

Setting this boolean value adds the type to Displayed content types in the portals navigation settings. Default is True

doctest_name

In a tests package, setting the stereotype <<doc_testcase>> on a class turns it into a doctest. The doctest itself is placed in the doc/ subdirectory. The doctest_name tagged value overwrites the default name for the file (which is the name of the doctestcase class + .txt). ArchGenXML appends the .txt extension automatically, so you don't need to specify it.

email

You can set the email project-wide with the --email commandline parameter (or in the config file). This TGV allows you to use/ overwrite it on a class level.

filter_content_types

If set to true (1), explicitly turn on the filter_content_types factory type information value. If this is off, all globally addable content types will be addable inside a (folderish) type; if it is on, only those values in the allowed_content_types list will be enabled. Note that when aggregation or composition is used to define containment, filtered_content_types will be automatically turned on.

folder_base_class

Useful when using the <<folder>> stereotype in order to set the folderish base class.

generate_reference_fields

Per default (True) navigable reference (or relation) ends are resulting in a ReferenceField (or RelationField). Setting this value to False results in not generating ReferenceFields automagically.

global_allow

Overwrite the AGX-calculated global_allow setting of class. Setting it to 1 makes your content type addable everywhere (in principle), setting it to 0 limits it to places where it's explicitly allowed as content.

hide_actions

A comma- or newline-separated list of action ids to hide on the class. For example, set to metadata, sharing to turn off the metadata (properties) and sharing tabs.

hide_folder_tabs

When you want to hide the folder tabs (mostly the "contents" tab, just set this tagged value to 1.

immediate_view

Set the immediate_view factory type information value. This should be the name of a page template, and defaults to base_view. Note that Plone at this time does not make use of immediate_view, which in CMF core allows you to specify a different template to be used when an object is first created from when it is subsequently accessed.

import_from

If you wish to include a class in your model (as a base class or aggregated class, for example) which is actually defined in another product, add the class to your model and set the import_from tagged value to the class that should be imported in its place. You probably don't want the class to be generated, so add a stereotype <<stub>> as well.

imports

A list of python import statements which will be placed at the top of the generated file. Use this to make new field and widget types available, for example. Note that in the generated code you will be able to enter additional import statements in a preserved code section near the top of the file. Prefer using the imports tagged value when it imports something that is directly used by another element in your model. You can have several import statements, one per line, or by adding several tagged values with the name imports.

index:type

the type of index used as (string), for example FieldIndex, KeywordIndex, DateIndex or any available index in your portal. For known types a default is guessed, such as FieldIndex for StringFields or DateIndex for DateFields. If no guess is possible, we assume a FieldIndex.

inherit_allowed_types

By default, a child type will inherit the allowable content types from its parents. Set this property to false (0) to turn this off.

label

Sets the readable name.

license

You can set the license project-wide with the --license commandline parameter (or in the config file). This TGV allows you to use/ overwrite it on a class level.

marshaller

Specify a marshaller to use for the class' schema.

module

Like module_name, it overwrites the name of the directory it'd be normally placed in.

parentclass_first

if this tgv is set to true generalization parents are used before the standard base classes (e.g. BaseContent) this option is sometimes necessary when inheriting from some special parents (e.g. CMFMember or ReMember style classes).

parentclasses_first

if this tgv is set to true generalization parents are used before the standard base classes (e.g. BaseContent) this option is sometimes necessary when inheriting from some special parents (e.g. CMFMember or ReMember style classes).

portal_type

Sets the CMF portal-type this class will be registered with, defaults to the class-name.

read_permission

Defines archetypes fields read-permission. Use it together with workflow to control ability to view fields based on roles/permissions.

register

CMFMember related. Set as default member type.

searchable

Per default a fields searchable property is set to False. Sometimes you want it for all fields True. This TGV let you define the default for a class, package or model.

searchable_type

Setting this boolean value adds the type to types to be searched in the portals search settings. Default is True

strict

On a class with the <> stereotype: check for inherited interfaces as well.

suppl_views

The TemplateMixin class in Archetypes allows your class to present several alternative view templates for a content type. The suppl_views value sets the available views. Example: ("my_view", "myother_view"). Defaults to (). Only relevant if you use TemplateMixin.

typeDescription

DEPRECATED. Use description instead.

use_dynamic_view

Controles wether CMFDynamicViewFTI is used for a type/class. Boolean, default is True.

use_portal_factory

This boolean value controls the registration of the type for use with portal_factory. Default: True.

use_workflow

Tie the class to the named workflow. A state diagram (=workflow) attached to a class in the UML diagram is automatically used as that class's workflow; this tagged value allows you to tie the workflow to other classes.

version_info

Add ArchGenXML version information to the generated file (default is 1).

vocabulary:type

Enables support for Products ATVocabularyManager by setting value to ATVocabularyManager.

vocabulary:vocabulary_type

For use with ATVocabularyManager. Defaults to Simplevocabulary. Let you define the portal_type of the vocabulary used as initial vocabulary at Product install time. If VdexVocabulary is used, the install-script tries to install a vocabulary from a vdex file names Products/PRODUCTNAME/data/VOCABULARYNAME.vdex.

write_permission

Defines archetypes fields write-permission. Use it together with workflow to control ability to write data to a field based on roles/permissions.

field

description

Sets a description for this field. It's used for field documentation while registering inside Archetypes.

label

Sets the readable name.

validation_expression

Use an ExpressionValidator and sets the by value given expression.

validation_expression_errormsg

Sets the error message to the ExpressionValidator (use with validation_expression to define the validation expression to which this error message applies).

method

code

The actual python code of the method. Only use this for simple one-liners. Code filled into the generated file will be preserved when the model is re-generated.

documentation

You can add documention via this tag; it's better to use your UML tool's documentation field.

label

Sets the readable name.

permission

For method with public visibility only, if a permission is set, declare the method to be protected by this permission. Methods with private or protected visiblity are always declared private since they are not intended for through-the-web unsafe code to access. Methods with package visibility use the class default security and do not get security declarations at all.

model

association_class

You can use associations classes to store content on the association itself. The class used is specified by this setting. Don't forget to import the used class properly.

association_vocabulary

Switch, defaults to False. Needs Product ATVocabularyManager. Generates an empty vocabulary with the name of the relation.

author

You can set the author project-wide with the --author commandline parameter (or in the config file). This TGV allows you to use/ overwrite it on a model level.

catalog:index

Add the field (or all fields of a class, package, model) to the index. Boolean, 1 or 0. Default is 0. If set, you may need to provide index:* tagged values too.

catalog:metadata

Adds the field to the metadata record on the query result. Boolean, 1 or 0. If you do not provide index:attributes, the name of the accessor of the field is the default. If catalog:attributes is given for each attribute one field at the record will be created.

catalog:name

Sometimes you need to add an index to a other catalog than portal_catalog and its XML-File catalog.xml. Provide a tuple of comma separated strings, id of the catalog and the filename of its configuration file. default is "portal_catalog, Plone Catalog Tool'.

catalogmultiplex:black

Remove an archetypes class (identified by meta_type) from one or more catalogs to be cataloged in. Comma- separated list of catalogs. Example-value: portal_catalog, another_catalog. Explaination: Instances of the class wont be catalogged in portal_catalog anymore.

catalogmultiplex:white

Add an archetypes class (identified by meta_type) to one or more catalogs to be cataloged in. Comma- separated list of catalogs. Example-value: myfancy_catalog, another_catalog. Explaination: Additionally to the default portal_catalog the instances of this class will be catalogged in the two given catalogs.

copyright

You can set the copyright project-wide with the -- copyright commandline parameter (or in the config file). This TGV allows you to use/ overwrite it on a model level.

creation_permission

Sets the creation permission for the class. Example: Add portal content.

creation_roles

You can set an own role who should be able to add a type. Use an Tuple of Strings. Default and example for this value: ("Manager", "Owner", "Member").

default_interface_type

default type of interfaces (z2 or z3).

dependend_profiles

GenericSetup profiles your product depends on. A list of profile names separated by commas.

detailed_creation_permissions

Give the content-type (types in the package, model) own creation permissions, named automagically ProductName: Add ClassName.

display_in_navigation

Setting this boolean value adds the type to Displayed content types in the portals navigation settings. Default is True

email

You can set the email project-wide with the --email commandline parameter (or in the config file). This TGV allows you to use/ overwrite it on a model level.

generate_reference_fields

Per default (True) navigable reference (or relation) ends are resulting in a ReferenceField (or RelationField). Setting this value to False results in not generating ReferenceFields automagically.

global_allow

Overwrite the AGX-calculated global_allow setting of class. Setting it to 1 makes your content type addable everywhere (in principle), setting it to 0 limits it to places where it's explicitly allowed as content.

imports

A list of python import statements which will be placed at the top of the generated file. Use this to make new field and widget types available, for example. Note that in the generated code you will be able to enter additional import statements in a preserved code section near the top of the file. Prefer using the imports tagged value when it imports something that is directly used by another element in your model. You can have several import statements, one per line, or by adding several tagged values with the name imports.

index:type

the type of index used as (string), for example FieldIndex, KeywordIndex, DateIndex or any available index in your portal. For known types a default is guessed, such as FieldIndex for StringFields or DateIndex for DateFields. If no guess is possible, we assume a FieldIndex.

label

Sets the readable name.

license

You can set the license project-wide with the --license commandline parameter (or in the config file). This TGV allows you to use/ overwrite it on a model level.

module

Like module_name, it overwrites the name of the directory it'd be normally placed in.

plone_target_version

The target version of Plone. Defaults to 3.0 Possible values are 2.5 and 3.0

read_permission

Defines archetypes fields read-permission. Use it together with workflow to control ability to view fields based on roles/permissions.

relation_implementation

Sets the type of implementation is used for an association: basic (used as default) for classic style archetypes references or relations for use of the Relations Product.

searchable

Per default a fields searchable property is set to False. Sometimes you want it for all fields True. This TGV let you define the default for a class, package or model.

searchable_type

Setting this boolean value adds the type to types to be searched in the portals search settings. Default is True

skin_directories

A comma seperated list of subdirectories to be generated inside the products skins directory. each of this directories is prefixed with productname in lowercase. the default value is the productname as is without a prefix.

use_dynamic_view

Controles wether CMFDynamicViewFTI is used for a type/class. Boolean, default is True.

use_portal_factory

This boolean value controls the registration of the type for use with portal_factory. Default: True.

use_workflow

Tie the class to the named workflow. A state diagram (=workflow) attached to a class in the UML diagram is automatically used as that class's workflow; this tagged value allows you to tie the workflow to other classes.

version_info

Add ArchGenXML version information to the generated file (default is 1).

vocabulary:type

Enables support for Products ATVocabularyManager by setting value to ATVocabularyManager.

vocabulary:vocabulary_type

For use with ATVocabularyManager. Defaults to Simplevocabulary. Let you define the portal_type of the vocabulary used as initial vocabulary at Product install time. If VdexVocabulary is