MidCOM style engine
- How Style requests are processed
- Using the MidCOM style engine
- Runtime Substyle selection
- Site-wide default styles
MidCOM provides an enhanced Layout Engine which replaces the <[...]> syntax for style elements by a custom function and thus enables the framework to provide a much greater flexibility compared to out-of-the-box template engine of Midgard.
How Style requests are processed
The MidCOM Framework provides the superglobal variable $_MIDCOM->style, which has one public method, called show. This method has a parameter called $path, which is either the name of a style element in the current style or an absolute path to an element in a different style.
There is a public wrapper for this method, called midcom_show_style(). It has the same parameters as $_MIDCOM->style and does exactly the same thing. You should always use this wrapper, so you do not have to import the global variable $midcom.
User Defined Style
The User Defined Style is set in parameter midcom/style of the topic of the component. It represents the path to the Style that is to be used to output the topic in question. It must contain all the elements that are required by the component in question.
Read more in Modifying MidCOM component output.
Calling conventions of midcom_show_style()
There are two ways to call midcom_show_style():
<?php
midcom\_show\_style('element1');
?>
element1 is searched in the User Defined Style tree (if there is one). If it is not found here (or if the component has no user defined style), the element1 snippet in the _style snippetdir of the current component is evaluated.
<?php
midcom\_show\_style('/MyStyle/mySubStyle/element2');
?>
element2 is searched in the style tree /MyStyle/mySubStyle. If there is no element2 in this style tree, the element2 snippet in the style directory of the current component is evaluated.
Magic Style Elements
Since there is no ROOT element which always gets processed like in standard Midgard Styles, there are two magic style elements that allow you to output Data before and after component output: the framework automatically calls the elements style-init and style-finish from the selected style during the output phase of the Framework. These calls are immediately before and after the call to the OUTPUT concept of the component.
Inheritance
Inheritance of style elements is taken into account everywhere as it would be normally.
Using the MidCOM style engine
If you want to use a custom style for a specific component, you can create a new style (sub-)tree, use style elements and create subtrees that inherit elements from their parents.
To tell the component which style to use, just use Folder -> Edit Folder from the toolbar or set the midcom/style parameter in the topic to the style you want to use, e.g. /MyStyle/subStyle1.
Any <(...)> tags have to be changed to the following syntax:
Where the three dots stand for the style element name in the current style, or even an element in a different style: /MyStyle/element1.
Accessing style elements from component functions works in a similar way, you just have to call midcom_show_style('elementname').
Example
/myStyle/element1
...
Hi, I'm /myStyle/element1!
...
/myStyle/element2
...
Hi, I'm /mystyle/element2!
...
/yourStyle/element2
...
Hi, I'm /yourStyle/element2!
...
/yourStyle/element1
...
Hi I'm /yourStyle/element1!
&(view.data);
...
Output of midcom_show_style('/mystyle/element1')
Hi, I'm /myStyle/element1!
Hi, I'm /mystyle/element2!
Hi, I'm /yourStyle/element2!
Hi, I'm /yourStyle/element2!
Hi, I'm /yourStyle/element1! (Content of `$view->data`)
Notes
The new syntax will not work properly in style elements which are called by the
<(...)>syntax. So never use them in component styles!If you want to pass variables to the style element (and you do want!), you have to declare these variables as global in the style element as well as in the component function that displays this element.
Runtime Substyle selection
Often, especially with dynamically loaded components, you will run into the problem that you need a way to specify some sort of substyle of the component. The problem here is that you need a way of switching the used style without the component needing to know about it - components should stay independent of the context in which they are used. This goes as far as that you have to be able to access different variants of a style from the same topic.
The solution for this is a mechanism called Substyle selection. Using a parameter encoded into the beginning of the URL you can select a substyle of the style which is selected by the parameter midcom/style. Consider this:
The Topic named topic://roottopic/search is associated to the component de.linkm.fulltextsearch. You want to implement a simple and a complex interface. The complex interface is the default implemented by the Style style://mystyles/search. This style is selected through the regular style switching mechanism as a parameter to the topic search (midcom/style = '/mystyles/search').
Now you want include the search system with a single input field on every page of your website. You do this by dynamically loading the URL /search and including the result in your layout. But since this would display the fully featured search interface, you use the substyle selection to switch to the style style://mystyles/search/simple.
This is done through prepending it as a parameter at the beginning of the URL. It will define the key substyle in the MidCOM Domain midcom with the name of the substyle as a paramater. In our example this would lead to the URL /midcom-substyle-simple/search. The MidCOM Framework will fetch this information prior to regular URL Parsing and will reconfigure the Style Engine accordingly.
Site-wide default styles
This feature is available in CVS as of 2006-04-11 and will be part of the upcoming 2.5.4 and 2.6.0 releases.
Using the global MidCOM configuration you have the ability to set site wide default styles for your components. The configuration key styleengine_default_styles is used for this. It should be set before MidCOM startup, as usual with MidCOM configuration directives. This style is used in all cases where no style has been set instead of the component-delivered default style.
Configuration example
In your code-global element put something like this:
<?php
$config = Array();
// ...
$config['styleengine_default_styles'] = Array
(
'net.nehmer.static' => '/mystyle/net.nehmer.static',
'net.nehmer.blog' => '/mystyle/net.nehmer.blog',
);
// ...
require('midcom.php');
?>