quintagroup.themetemplate 0.11

qplone3 theme template

quintagroup.themetemplate is an enhanced “Plone 3 Theme” template from Zopeskel, that includes addcontent local command, which allows you to extend base Plone theme by additional elements, such as: skin layers, portlets, viewlets, css and js resources, and objects in zexp files. This package is an analogue of Archetype template in terms of its functionality.

quintagroup.themetemplate package is used for development of all Quintagroup themes for Plone 3 (http://skins.quintagroup.com).

Overview

This theme template allows you to create initial theme package skeleton, i.e. create plone3 theme python package with nested namespace (this is different from deafult plone3_theme template in Zopeskel)

After that you can extend theme package by the following elements:

• skin-layer(s)

• portlet(s)

• viewlet(s)

• css, js resource(s)

• objects in zexp files

Creation of a package is performed with paster create PasteScript command. Theme extending with other resources can be done with paster addcontent local ZopeSkel command (extended in this product).

Creating theme package

Let’s create plone-3 theme python package. Use paster create command for that:

>>> paster('create -t qplone3_theme plone.example --no-interactive --overwrite')
paster create -t qplone3_theme plone.example --no-interactive
...

You got standard python package content with

• quintagroup upper level namespace.

• plone.example-configure.zcml - zcml file for adding into package-includes directory

Check that:

>>> package_dir = 'plone.example'
>>> objects = ('setup.py', 'quintagroup', 'plone.example-configure.zcml')
>>> [True for o in objects if o in os.listdir(package_dir)]
[True, True, True]

qplone3_theme template - creates theme with nested namespace.

By default - theme is placed in

quintagroup.theme.<package name without dot> namespace

in our case - quintagroup.theme.ploneexample

So check namespaces:

>>> theme_namespace = os.path.join(package_dir,'quintagroup','theme','ploneexample')
>>> os.path.isdir(theme_namespace)
True

Theme holds 3 subdirectories (browser, profiles, skins):

>>> cd(theme_namespace)
>>> dirs = ('skins', 'browser', 'profiles')
>>> [True for d in dirs if d in os.listdir('.')]
[True, True, True]

And initialization files (__init__.py, configure.zcml)

>>> files = ('__init__.py', 'configure.zcml')
>>> [True for d in files if d in os.listdir('.')]
[True, True]

Extending theme

One of the best features, which ZopeSkel package brings, is localcommand.

This part shows how you can extend a theme (generated with qplone3_theme ZopeSkel template) with additional useful stuff:

• skin layers

• views

• viewlets

• portlets

• css

• javascripts

• objects in zexp files

So, in qplone3_theme generated package you can use addcontent ZopeSkel local command.

IMPORTANT TO NOTE: localcommand (addcontent in our case) should be called in any subdirectory of the generated theme package. And it won’t work outside this package..

>>> paster('addcontent -a')
paster addcontent -a
  ...
    css_resource:    A Plone 3 CSS resource template
  ...
    import_zexps:    A template for importing zexp-objects into portal on installation
    js_resource:     A Plone 3 JS resource template
  N portlet:         A Plone 3 portlet
  ...
    skin_layer:      A Plone 3 Skin Layer
  ...
  N view:            A browser view skeleton
    viewlet_hidden:  A Plone 3 Hidden Viewlet template
    viewlet_order:   A Plone 3 Order Viewlet template
  ...

We can see a list of extention subtemplates, which can be used for our theme. ‘N’ character tells us that these subtemplates are registered for other (archetype) template, but it does not matter - they can correctly extend our theme.

Adding SKIN LAYER

For that case use skin_layer subtemplate with addcontent local command

>>> paster('addcontent --no-interactive skin_layer')
paster addcontent --no-interactive skin_layer
Recursing into profiles
...

This command adds NEW ‘skin_layer’ (default name) directory to _skins_ directory, with only CONTENT.txt file inside.

>>> 'skin_layer' in os.listdir('skins')
True
>>> ls('skins/skin_layer')
CONTENT.txt

skins.xml profile is also updated:

>>> cat('profiles/default/skins.xml')
<?xml version="1.0"?>
<object name="portal_skins" allow_any="False" cookie_persistence="False"
   default_skin="My Theme Name">
...
 <object name="skin_layer"
    meta_type="Filesystem Directory View"
    directory="quintagroup.theme.ploneexample:skins/skin_layer"/>
<BLANKLINE>
 <skin-path name="My Theme Name" based-on="Plone Default">
...
  <layer name="skin_layer"
     insert-after="custom"/>
<BLANKLINE>
 </skin-path>
...

We can see, that:

• skin_layer directory was registered as Filesystem Directory View

• skin_layer Filesystem Directory View was added to our theme layers list

Adding PORTLET

Only initialization files are available in portlets directory before adding new portlet.

>>> ls('portlets')
__init__.py
configure.zcml

Add portlet with portlet subtemplate.

>>> paster('addcontent --no-interactive portlet')
paster addcontent --no-interactive portlet
Recursing into portlets
...

After executing this local command …

configure.zcml file in the theme root directory - includes portlets registry:

>>> cat('configure.zcml')
<configure
...
<include package=".portlets" />
...

exampleportlet.pt template and exampleportlet.py script added to portlets directory.

>>> files = ('exampleportlet.pt', 'exampleportlet.py')
>>> [True for d in files if d in os.listdir('portlets')]
[True, True]

And portlets/configure.zcml - register new portlet

>>> cat('portlets/configure.zcml')
<configure
...
     <plone:portlet
         name="quintagroup.theme.ploneexample.portlets.ExamplePortlet"
         interface=".exampleportlet.IExamplePortlet"
         assignment=".exampleportlet.Assignment"
         view_permission="zope2.View"
         edit_permission="cmf.ManagePortal"
         renderer=".exampleportlet.Renderer"
         addview=".exampleportlet.AddForm"
         editview=".exampleportlet.EditForm"
         />
...

Finally, new portlet type is registered in portlets.xml profile

>>> cat('profiles/default/portlets.xml')
<?xml version="1.0"?>
...
   <portlet
     addview="quintagroup.theme.ploneexample.portlets.ExamplePortlet"
     title="Example portlet"
     description=""
   />
...

Thanks to ZopeSkel developers for this subtempalte ;)

Adding CSS resource

Use css_resource subtemplate.

>>> paster("addcontent --no-interactive css_resource")
paster addcontent --no-interactive css_resource
Recursing into browser
...
Recursing into profiles
...

This template adds (if does not exist yet) _stylesheets_ directory in _browser_ directory

>>> 'stylesheets' in os.listdir('browser')
True

In _stylesheets_ resource directory empty main.css stylesheet resource added

>>> 'main.css' in os.listdir('browser/stylesheets')
True
>>> cat('browser/stylesheets/main.css')
<BLANKLINE>

New resource directory was registered in configure.zcml

>>> cat('browser/configure.zcml')
<configure
...
    <browser:resourceDirectory
        name="quintagroup.theme.ploneexample.stylesheets"
        directory="stylesheets"
        layer=".interfaces.IThemeSpecific"
        />
...

And cssregistry.xml profile was added into profiles/default directory with registered main.css stylesheet

>>> 'cssregistry.xml' in os.listdir('profiles/default')
True
>>> cat('profiles/default/cssregistry.xml')
<?xml version="1.0"?>
<object name="portal_css">
<BLANKLINE>
 <stylesheet title=""
    id="++resource++quintagroup.theme.ploneexample.stylesheets/main.css"
    media="screen" rel="stylesheet" rendering="inline"
    cacheable="True" compression="safe" cookable="True"
    enabled="1" expression=""/>
...

Test viewlets subtemplates

There are 2 types of viewlet subtemplates:

• viewlet_order

• viewlet_hidden

The first one is used for adding new viewlets and setting viewlets order for the ViewletManager, the second one only hides viewlet in pointed ViewletManager.

Adding ZEXPs importing

Imagine situation, when you develop a theme, which uses some extra portal objects (documents with text for some potlets) Then customer of your theme can edit these objects according to his need.

For this situation import_zexps subtemplate exists.

import_zexps subtemplate extends your theme with mechanism for importing list of zexp formated files into portal root on theme instllation.

>>> paster('addcontent --no-interactive import_zexps')
paster addcontent --no-interactive import_zexps
...
Recursing into import
...
Recursing into profiles
...
Inserting from setuphandlers.py_insert into ...
...

As we see from the upper log:

• ‘import’ directory was added into root of the theme

• profiles stuff was updated

• some stuff into setuphandlers.py module was inserted

1. There was empty ‘import’ directory added, where you will put zexp objects for install into portal root.

   >>> ls('import')
   CONTENT.txt
   

2. import_steps.xml was added in profiles/default directory (if does not exist yet), which contains additional quintagroup.theme.ploneexample.import_zexps step.

   >>> 'import_steps.xml' in os.listdir('profiles/default')
   True
   

   >>> cat('profiles/default/import_steps.xml')
   <?xml version="1.0"?>
   <import-steps>
   ...
     <import-step id="quintagroup.theme.ploneexample.import_zexps"
                  version="..."
                  handler="quintagroup.theme.ploneexample.setuphandlers.importZEXPs"
                  title="My Theme Name: Import zexps objects">
       <dependency step="skins" />
       Import zexp objects into portal on My Theme Name theme installation
     </import-step>
   <BLANKLINE>
   </import-steps>
   

3. Check setuphandlers.py module - there must be importZEXPs function defined

   >>> cat('setuphandlers.py')
   def setupVarious(context):
   ...
   def importZEXPs(context):
   ...
   

Then simply prepare zexp objects and copy them to import directory.

RELEASE NOTES !

Before releasing theme - I suggest to clean up setup.py script:

• remove theme_vars argument (its value is useful only for theme development)

• remove entry_points argument (same reason). It’s useless in plone for now.

• And remove paster_plugins argument too (it has sence in conjunction with entry_points during theme developing)

Steps mentioned above prevent possible problems with theme distribution/deployment.

Changelog