Package: tau.selectorstrings
Tau SelectorStringsIntroductionThe purpose of this component distribution is two-fold; to provide a useful
way of configuring clusters of strings to be presented in a dropdown list, and
to teach others how to create new ZCML directives.  The code has been
carefully documented to make it clear how it works.My need for selectorstrings comes from another component I’m designing for
presenting collections of various files as a Zope folder.  I wanted to allow
the developer who adds an instance of this document folder, using the ZMI
(Zope Management Interface), to pick from a list of directories.  I did not
want them to be able to enter arbitrary directories, partly as a security
precaution and partly to prevent typing errors.This resulted in the following ZCML directive:<selectorstring cluster="sitedocs"
    label="Public Documents"
    value="/usr/share/public/"
    />

<selectorstring cluster="sitedocs"
    label="Family Photos"
    value="/home/jeff/photos/"
    />And you can add more, using the same or difference cluster name and the
strings will be available as a Zope vocabulary under that cluster name.One drawback is that each such simple directive repeats the cluster name
repeatedly.  So next I created a complex (nested) directive to factor out the
cluster name:<selectorcluster name="sitedocs">

    <selectorstring
        label="Public Documents"
        value="/usr/share/public/"
        />

    <selectorstring
        label="Family Photos"
        value="/home/jeff/photos/"
        />

</selectorcluster>Obtaining Development VersionsIn addition to the PyPI downloads, the development version of this
component is available via itsproject on Github.Steps to Creating a New ZCML DirectiveZCML directives come in two flavors, simple and complex.  A simple directive
stands alone but a complex one supports grouping by containing one or more
other ZCML directives.A new ZCML directive, either simple or complex, is described by four
pieces:its namethe namespace it belongs tothe schemaits directive handlerThe piece that ties these all together is the declaration of the (simple-kind
of) directive in themeta.zcmlfile:<meta:directive
    name="selectorstring"
    schema=".interfaces.ISelectorStringDirective"
    handler=".zcml_directives.selectorstring_SimpleDirectiveHandler"
    />That takes care of declaring the name of the new directive and placing that
name into the “zope” namespace.  It could have placed it into the “browser”
namespace or some other space that would make organizational sense.To declare a complex-kind of directive:<meta:complexDirective
    name="selectorcluster"
    schema=".interfaces.ISelectorClusterDirective"
    handler=".zcml_directives.selectorcluster_ComplexDirectiveHandler"
    >

    <meta:subdirective
        name="selectorstring"
        schema=".interfaces.ISelectorStringSubdirective"
        />

</meta:complexDirective>Using Your ZCML DirectiveLike any ZCML directive, you place it into a configure.zcml file or some other
file included your the top-levelsite.zcmlconfiguration file:<configure
    xmlns="http://namespaces.zope.org/zope">

    <selectorstring cluster="sitedocs"
        label="Public Documents"
        value="/usr/share/public/"
        />

</configure>Wiring Your New Directives into Zope2Before the directive is recognized youmustbe sure that its definition
in itsmeta.zcmlgets included into the top-levelsite.zcmlfile.
This is done by placing into yourbuildout.cfgfile for yourZope2_instancepart the following:zcml += tau.selectorstrings-metaThis causes theplone.recipe.zope2instancerecipe to create a ‘slug’ file
under yourparts/Zope2_instance/etc/package-includes/that does nothing
but include yourtau/selectorstrings/meta.zcmlfile.  This inclusion
happens because of the following directive automatically placed into youretc/site.zcmlfile by the recipe:<include files="package-includes/*-meta.zcml" />CHANGESVersion 0.1dev (2010-12-21)Initial Release