= ZMSThemes =

== Document Identification / Contact ==

'''Proposal for enhanced Usage of Themes and Templatesets in ZMS'''

Created: 2008/11/18[[BR]]
Last update: 2008/11/27

Christian Meier, post@christianmeier.info[[BR]]
Mike Hallbauer, mikehallbauer@web.de

== Background / Overview / Problems ==

In ZMS können das Theme bzw. Templateset nur beim initalen Setup der ZMS-Instanz ausgewählt werden. Dabei wird ein vorkonfiguriertes 
{{{.zexp}}} importiert (z.B. {{{/zms/import/myZMStheme32.zexp}}}). Die darin enthaltenen DTML-Methods werden im ZMS-Root platziert. Die Bearbeitung der Templates kann webbasiert (ZMI) oder mit einem externen Editor (FTP) erfolgen.

Ein nachträglicher Wechsel des kompletten Themes bzw. Templatesets ist nur durch einen manuellen Prozess (editieren, bearbeiten, löschen) möglich. Um dies halbautomatisch durchführen zu können, wurde die Erweiterung ZMSThemeChanger (siehe ![1]) entwickelt.

Die Platzierung aller Content-Object-Templates ({{{bodyContentZMSCustom_*}}}) im ZMS-Root seit ZMS-2.11. macht es schwierig, den Überblick über Theme-relevatente DTML-Methods zu behalten. Dieser Überblick wird bei komplexen Content-Objects (mit vielen DTML-Methods, Python-Scripts, etc.) noch mehr erschwert, da diese ebenfalls im ZMS-Root liegen.

== Objectives / Benefit Statement / Motivation ==

Für Web-Designer, Agenturen etc. wäre eine bessere Kapselung der Theme-relevanten DTML-Methods sinnvoll. Wenn diese Theme-spezifisch in Unterordern (statt zentral in ZMS-Root) platziert werden, wäre ein Wechsel des Templatesets on-the-fly realisierbar, da mehrere Themes parallel vorgehalten werden können. Die Auswahl könnte entsprechend bestimmter Konfigurationsparameter (z.B. Metaattribut, URL-Bestandteile, etc.) erfolgen. Ein Beispiel wäre die Auslieferung für mobile Endgeräte (siehe ![2]). Außerdem könnten so Techniken wie Zope Page Templates für bestimmte Templatesets genutzt werden (siehe ![5]).

Durch eine Platzierung der Themes bzw. Templatesets in einem Unterorder ({{{/common}}}) macht es außerdem möglich, Web-Designer nur Manager-Rechten für die jeweiligen Unterordner zum Editieren der HTML/CSS einzuräumen - ohne dies für ZMS-Root insgesamt freischalten zu müssen.

Darüberhinaus kann die Entwicklung von komplexen Templatesets effektiver Filesystem-basiert erfolgen (siehe ![3]). So wird es möglich, externe Werkzeuge (z.B. Eclipse) und insbesondere Versionsverwaltungssysteme (z.B. SVN) einzusetzen. Vor allem treten diese Anforderungen auf, wenn mehrere Personen (Web-Designer, Web-Developer, etc.) verschiedene Varianten von HTML/CSS-Konstrukten entwickeln müssen. 

Die Umsetzung von Themes bzw. Templatesets unter Nutzung externer CSS- bzw. Javascript-Bibliotheken (siehe z.B. ![6] und ![7]) kann so transparenter erfolgen. Mit Angeboten von frei nutzbaren HTML/CSS-Konstrukten (siehe z.B. ![8]) können mit überschaubaren Aufwand die mitgelieferten ZMS-Themes ergänzt werden.

== Scope / Proposed Solution / Deliverables ==

'''(A) Theme-spezifische Folder'''

 1. in {{{/common}}} Theme-spezifische Unterzeichnisse anlegen (z.B. {{{/common/theme1, /common/theme1/css, /common/theme1/img}}}, etc.)
 1. Theme-relevante Templates in diese Unterordner verschieben
 1. folgende Standard-Templates, welche implizit aufgerufen werden, auch in ZMS-Root platzieren
  * {{{standard_html_request}}}
  * {{{standard_html_header}}}
  * {{{standard_html_footer}}}
  * {{{standard_error_message}}}
  * {{{pageregionBefore / bodyContent_PagePre}}}
  * {{{pageregionAfter / bodyContent_PagePost}}}
  * {{{headCSS}}}
  * {{{headScript}}}
  * {{{headTitle}}}
  * ggf. weitere head-Methods
 1. diese Standard-Templates ihre Entsprechungen im Theme-Folder aufrufen lassen, z.B. durch folgenden Code-Snippet (im Beispiel erfolgt die Auswahl anhand eines Metaattributs des Root-Knotens - dies könnte auch anhand anderer Parameter erfolgen, z.B. URL-Subdomain-Bestandteile etc.)
{{{
[standard_html_header]

<dtml-try>
  <dtml-with "_['common'][content.getObjProperty('attr_theme',REQUEST).lower()]">
    <dtml-var standard_html_header>
  </dtml-with>
<dtml-except>
  <head></head>
  <body>
</dtml-try>

[standard_html_footer]

<dtml-try>
  <dtml-with "_['common'][content.getObjProperty('attr_theme',REQUEST).lower()]">
    <dtml-var standard_html_footer>
  </dtml-with>
<dtml-except>
  </body>
</dtml-try>
}}}
 1. die Templates im Theme-Folder dahingehend erweitern, dass ZMS-API-Funktionen für das jeweilige Content-Objekt aufgerufen werden, z.B. {{{thisObj.getNavElements(REQUEST), thisObj.getLevel()}}}, etc.


'''(B) Erweiterung Filesystem-basierte Theme bzw. Templatesets'''

 1. Nutzung des Filesystem Views durch {{{CMFCore.DirectoryView}}} (![4] installieren)
 1. Anlegen eines Verzeichnisses {{{/Products/zms/skins}}}
 1. Anlegen von Theme-spezifischen Unterverzeichnissen in {{{skins}}} (z.B. {{{/theme1, /theme1/css, /theme1/img, etc.}}}
 1. diese Verzeichnisse in {{{/Products/zms/configure.zcml}}} registrieren mittels
{{{
<configure xmlns="http://namespaces.zope.org/zope"
           xmlns:browser="http://namespaces.zope.org/browser"
           xmlns:five="http://namespaces.zope.org/five"
	   xmlns:cmf="http://namespaces.zope.org/cmf">
	<cmf:registerDirectory name="theme1"/>
	<cmf:registerDirectory name="theme1/css"/>
	<cmf:registerDirectory name="theme1/img"/>
</configure>
}}}
 1. im ZMI in {{{/common}}} das theme1-Verzeichnis im Filesystem mounten (Add "Filesystem Directory View")
 1. weiter mit (A) 3.

In beiden Varianten (A) und (B) kann das vorhanden CSS-Handling von ZMS (Platzierung in {{{/common/css}}} bzw. {{{/instance/css}}}) durch Editing via Configuration > Stylesheet beibehalten werden. Darüber können effektiv Varianten und Überschreibungen der Theme-spezifischen CSS (z.B. aus {{{/common/theme1/css}}}) erfolgen, wenn die entsprechende {{{style.css}}} (und ggf. weitere) in headCSS nach der Theme-spezifischen CSS eingebunden werden. Für on-the-fly Theme-Changing müssen lediglich entsprechende Weichen vorgesehen werden, damit die jeweils relavanten CSS geladen werden.

'''Hinweis:''' Um während des Entwicklungsprozesses Änderungen an den Templates im Filesystem unmittelbar verfolgen können, muss ZOPE im Debug-Modus laufen ({{{/etc/zope.conf}}}). Ansonsten werden Veränderungen werden erst nach ZOPE-Neustart sichtbar.

'''Beispiel:''' Unter http://141.30.37.184:8080/test/confs/common/content/e134/index_ger.html befindet sich der Arbeitsstand zur Umsetzung des TUD-Themes für ZMS-2.11. am Beispiel von ZMSEventPublisher. Die Templates liegen im Filesystem (siehe http://141.30.37.184:8080/test/confs/common/tud/manage bzw. {{{/Zope-Instance/zope-2.11.1-1/Products/zms/skins/tud/}}} [Under Construction!].

== Assumptions and constraints / Risk Factors ==

 * Initialiserung einer ZMS-Instanz muss angepasst werden (lediglich Standard-Templates in ZMS-Root importieren, standardmäßig Meta-Attribut für Theme-Auswahl vorsehen, Themes in /common importieren bzw. registrieren - wenn Filesystem-based)

 * {{{CMFCore}}} muss parallel zu ZMS auf ZOPE-Ebene in {{{/Products}}} installiert werden (siehe ![4])
 * Filesystem DTML Method > Customize (Select a destination folder and press the button to make a copy of this method that can be customized.) funktioniert nicht out-of-the-box (!AttributeError: portal_skins)

Zu prüfen:
 * ggf. ist es möglich, dass benötigte Modul {{{CMFCore.DirectoryView}}} zu adaptieren und in dem in ZMS-Core aufzunehmen

== Estimates / Cost ==

''N/A''

== References ==

![1] [http://www.zms-publishing.com/support/content/e724/e727/e2869/index_ger.html ZMSThemeChanger][[BR]]
![2] [http://tech.groups.yahoo.com/group/zms-developers/message/3200 Discussion at zms-developers][[BR]]
![3] [https://mail.dzug.org/pipermail/zope/2008-February/005368.html Discussion at dzug-zope][[BR]]
![4] [http://www.zope.org/Products/CMF/ Content Management Framework (CMF)][[BR]]
![5] [http://www.zms-publishing.com/support/content/e732/e736/e1338/e2323/index_ger.html How to use Zope Page Templates in ZMS][[BR]]
![6] [http://www.yaml.de/ YAML][[BR]]
![7] [http://jquery.com/ jQuery][[BR]]
![8] [http://www.freecsstemplates.org/ freecsstemplates.org]

== Status ==

''Approved/Rejected by XYZ on YYYY/MM/DD''

== Actions ==

''TODOs''