MWT supports the creation of multiple themes. Each theme can define CSS styles, structure and configuration of pages (the page internal list of widgets and their configuration) and can contain a set of new widgets.
All themes inherit from the default theme and can extend and/or overwrite its characteristics. When writing a theme you normally start from an empty one. Thanks to inheritance an empty theme is basically just a copy of the default one, so you just have to define the differences.
Themes can be configured in MWT Themes editor. This is where you also set the current theme to be used for rendering pages.
Themes are placed in the themes directory of MWT plugin. Each theme has its own directory whose name is the theme name and a configuration file called theme.xml that must be placed in it. The page structure is defined in theme.xml. The syntax of the XML file is the following:
Example 1.3. An example theme configuration XML
<configuration> <layouts> <layout name="page1_name"> <widget name="widget1.php"/> <widget name="widget2.php"/> <widget name="widget3.php"/> </layout> <layout name="page2_name"> <widget name="widget1.php"/> <widget name="widget2.php"/> </layout> <layouts> <css> <option name="css_option1_name" values="" type="option1_type">option1_value</option> <option name="css_option2_name" values="" type="option2_type">option2_value</option> </css> </configuration>
For now let's focus on the content of the layouts tag. This is where the page structure is defined: by using the layout tag we can specify the list of internal widwets for each page. The CSS part of theme.xml is described in Styles paragraph.
A theme can also have a CSS style template: the file must be called template.css and placed in the theme directory. The CSS template, if present, is used to dynamically generate the actual CSS style sheet that will be included in the rendered pages. Read the next paragraph to know more about this process.
Additionally, themes can also have a images directory inside the main directory. These is where images used by the theme's widgets are put.
In its template.css file a theme can provide the CSS style sheet to be included in pages. When writing the template file it is possible to use the values of a set of parameters that can be configured in MWT Themes editor. Parameters are referenced in the template by means of an expression language that is part of the taglib engine (described in chapter 2). In the process of page generation, the expression language from the template file is expanded to generate the final style sheet. To know more about how to script your CSS template read paragraph Scripting the CSS template with the expression language. While the expression language and how to reference style parameters in the template will be described in the next chapter, in this paragraph it is explained how to define parameters.
Let's go back to the syntax of the theme.xml file shown in the previous paragraph, focusing this time on the content of the css tag. This is where style parameters can be defined. Each parameter must have a name, while type will default to text, values and the parameter value will default to an empty string. Type value will determine the form element that will be used to set a value for the parameter in the editor. It can be one of the following:
*Only for the select type it makes sense to specify a comma-separated list of values.
Filepolicy enables CSS template inheritance and effects the merging of the template style sheets while option policy enables inheritance of style parameters and determines how doubly-defined parameters are handled.
For every page a theme can inherit its structure from the default theme or it can define a new structure.
When MWT is about to create a page object to serve content, it first checks whether the page structure is defined in the current theme otherwise it looks for it in the default theme.
A theme can contain a new set of widgets (widgets files must be placed in a directory called widgets inside the main directory of the theme) or use widgets from the default theme.
When a page renders itself, it consecutively evaluates the code of its inner widgets. Before rendering a widget, the system first checks the existance of the widget file in the widgets directory of the current theme and if the widget is not found then it searched in the widgets directory of the default theme.
To further enhance reusability of widgets MWT makes it possible to define an initial configuration for a widget when it is used in a page of a specific theme. Let's say you are using widget1 in page1 of theme themeA, in page2 of theme themeA and in page3 of theme themeB.
For page1 the widget default configuration is suitable, for page2 and page3 instead you would like to provide a different initial configuration for the widget (initial means at the time the theme is deployed, it is in fact always possible to configure a widget subsequently from MWT Editor). What you can do is define the widget initial configuration in the theme configuration file:
theme.xml from themeA:
Example 1.4. Preconfiguring widgets in themes
<layout name="page1"> <widget name="widget1.php"/> <widget name="...."/> </layout> <layout name="page2"> <widget name="widget1.php"> <param name="param1_name" value="param2_value"/> <param name="param2_name" value="param2_value"/> </widget> <widget name="...."/> </layout>
theme.xml from themeB:
<layout name="page3"> <widget name="widget1.php"> <param name="param1_name" value="param2_value"/> <param name="param2_name" value="param2_value"/> </widget> <widget name="...."/> </layout>