quintagroup.themetemplate 0.25

Quintagroup theme template for Plone 3 with nested namespace

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 at http://skins.quintagroup.com.

Contents
--------
1. Overview
2. Creating theme package
3. Extending theme
4. Release notes

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 quintagroup.theme.example --no-interactive --overwrite')
paster create -t qplone3_theme quintagroup.theme.example --no-interactive
...

You got standard python package content with

- *quintagroup* upper level namespace.
- *quintagroup.theme.example-configure.zcml* - zcml file for adding into package-includes directory

Check that::

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


*qplone3_theme* template - creates theme with nested namespace.

By default - theme is placed in *quintagroup.theme.<3rd part of dotted package name> namespace*

in our case - quintagroup.theme.example

So check namespaces::

>>> theme_namespace = os.path.join(package_dir,'quintagroup','theme','example')
>>> 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]


*browser* directory
-------------------

Browser directory contains:

- 'templates' resource directory
- interfaces.py module with IThemeSpecific marker interface
- configure.zcml, with registered theme marker interface::

>>> ls('browser')
__init__.py
configure.zcml
interfaces.py
templates

>>> cat('browser/interfaces.py')
from plone.theme.interfaces import IDefaultPloneLayer

class IThemeSpecific(IDefaultPloneLayer):
...

>>> cat('browser/configure.zcml')

...

As we see, default theme name is 'Custom Theme', but on theme
creation you can point out your own name. Check this ...

First create configuration file with different skin name::

>>> conf_data = """
... [pastescript]
... skinname=My Theme Name
... """
>>> file('theme_config.conf','w').write(conf_data)

Create the same theme with your own skin name and check this::

>>> paster('create -t qplone3_theme quintagroup.theme.example --no-interactive --overwrite --config=theme_config.conf')
paster create ...
>>> cd(package_dir)
>>> cat('quintagroup/theme/example/browser/configure.zcml')

...


*skins* directory
-----------------

It contains only README.txt file and NO SKIN LAYERS YET.
This is a job for localcommand ;)

But check whether I am right ...::

>>> cd('quintagroup/theme/example')
>>> ls('skins')
README.txt


*profiles* directory
--------------------

There is 'default' and uninstall profiles inside::

>>> 'default' in os.listdir('profiles')
True
>>> 'uninstall' in os.listdir('profiles')
True

There are the following items in default profile:

- import_steps.xml - for any reason.
- skins.xml - for registering skins directory::

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

*skins.xml* profile makes your theme default on installation
and uses layers list from 'Plone Default' for our theme,
without any new layers (yet)::

>>> cat('skins.xml')

...