This class is responsible for all style management and replaces the old <[.

..]> syntax. It is instantiated by the MidCOM framework and accessible through the midcom::get('style') object.

The method show ($style) returns the style element $style for the current component:

It checks whether a style path is defined for the current component.

  • If there is a user defined style path, the element named $style in this path is returned,
  • otherwise the element "$style" is taken from the default style of the current component (/path/to/component/_style/$path).

(The default fallback is always the default style, e.g. if $style is not in the user defined style path)

To enable cross-style referencing and provide the opportunity to access any style element (not only the style that is set in the current page), "show" can be called with a full qualified style path (like "/mystyle/element1", while the current page's style may be set to "/yourstyle").

Note: To make sure sub-styles and elements included in styles are handled correctly, the old style tag <[...]> should not be used anymore, but should be replaced by something like this:


Style Inheritance

The basic path the styleloader follows to find a style element is: 1. Topic style -> if the current topic has a style set 2. Inherited topic style -> if the topic inherits a style from another topic. 3. Site-wide per-component default style -> if defined in MidCOM configuration key styleengine_default_styles 4. Midgard style -> the style of the MidCOM component. 5. The file style. This is usually the elements found in the components style directory.

Regarding nr. 4: It is possible to add extra file styles if so is needed for example by a portal component. This is done either using the append/prepend component_style functions or by setting it to another directory by calling (append|prepend)_styledir directly.

NB: This cannot happen after the midcom::get()->content() stage in midcom is called, i.e. you cannot change this in another style element or in a _show() function in a component.

todo Document Style Inheritance
package midcom.helper

 Methods

__construct ()

Simple initialization

add_database_head_elements ()

Include all text/css attachments of current style to MidCOM headers

append_component_styledir (string $component)

append the styledir of a component to the queue of styledirs.

Parameters

$component

stringcomponentname

Exceptions

\midcom exception if directory does not exist.

append_styledir (\dirname $dirname)

Function append styledir

Adds an extra style directory to check for style elements at the end of the styledir queue.

Parameters

$dirname

\dirnamepath of style directory within midcom.

Exceptions

\midcom exception if directory does not exist.

Returns

booleantrue if directory appended

append_substyle (string $newsub)

Appends a substyle after the currently selected component style.

Appends a substyle after the currently selected component style, effectively enabling a depth of more then one style during substyle selection. This is only effective if done during the handle phase of the component and allows the component. The currently selected substyle therefore is now searched one level deeper below "subStyle".

The system must have completed the CAN_HANDLE Phase before this function will be available.

Parameters

$newsub

stringThe substyle to append.

enter_context (int $context)

Switches the context (see dynamic load).

Private variables $_context, $_topic and $_snippetdir are adjusted.

todo check documentation

Parameters

$context

intThe context to enter

Returns

booleanTrue on success, false on failure.

get_style ()

get_style_id_from_path (string $path, int $rootstyle)

Returns the id of the style described by $path.

Note: $path already includes the element name, so $path looks like "/rootstyle/style/style/element".

todo complete documentation

Parameters

$path

stringThe path to retrieve

$rootstyle

int???

Returns

intID of the matching style or false

get_style_path_from_id (int $id)

Returns the path of the style described by $id.

Parameters

$id

intStyle id to look up path for

Returns

stringStyle path

leave_context ()

Switches the context (see dynamic load).

Private variables $_context, $_topic and $_snippetdir are adjusted.

todo check documentation

Returns

booleanTrue on success, false on failure.

prepend_component_styledir (string $component)

prepend the styledir of a component

Parameters

$component

stringcomponent name

prepend_styledir (string $dirname)

Function prepend styledir

Parameters

$dirname

stringpath of styledirectory within midcom.

Exceptions

\midcom_error if directory does not exist.

Returns

booleantrue if directory appended

prepend_substyle (string $newsub)

Prepends a substyle before the currently selected component style.

Prepends a substyle before the currently selected component style, effectively enabling a depth of more then one style during substyle selection. This is only effective if done during the handle phase of the component and allows the component. The currently selected substyle therefore is now searched one level deeper below "subStyle".

The system must have completed the CAN_HANDLE Phase before this function will be available.

Parameters

$newsub

stringThe substyle to prepend.

show (string $path)

Looks for a style element matching $path (either in a user defined style or the default style snippetdir) and displays/evaluates it.

Parameters

$path

stringThe style element to show.

Returns

booleanTrue on success, false otherwise.

show_midcom (string $path)

Looks for a midcom core style element matching $path and displays/evaluates it.

This offers a bit reduced functionality and will only look in the DB root style, the theme directory and midcom's style directory, because it has to work even when midcom is not yet fully initialized

Parameters

$path

stringThe style element to show.

Returns

booleanTrue on success, false otherwise.

_find_element_in_scope ($_element)

Try to find element in current / given scope

Parameters

$_element

_get_component_snippetdir (\MidgardTopic $topic)

Gets the component styledir associated with the topics component.

Parameters

$topic

\MidgardTopicthe current component topic.

Returns

mixedthe path to the components style directory.

_get_component_style (\midcom_db_topic $topic)

Gets the component style.
todo Document

Parameters

$topic

\midcom_db_topicCurrent topic

Returns

intDatabase ID if the style to use in current view or false

_get_element_from_snippet ($_element)

Try to get element from default style snippet

Parameters

$_element

_get_element_in_styletree (int $id, string $name)

Returns a style element that matches $name and is in style $id.

Unlike mgd_get_element_by_name2 it also returns an element if it is not in the given style, but in one of its parent styles.

Parameters

$id

intThe style id to search in.

$name

stringThe element to locate.

Returns

stringValue of the found element, or false on failure.

_merge_styledirs (string $component_style)

This function merges the prepend and append styles with the componentstyle.

This happens when the enter_context function is called. You cannot change the style call stack after that (unless you call enter_context again of course).

Parameters

$component_style

stringcomponent style

_parse_element ($_style, $path)

This is a bit of a hack to allow &(); tags

Parameters

$_style

$path

 Properties

 

array $_filedirs

Path to file styles.
 

mixed $_styledirs

The stack of directories to check for styles.
 

array $data

Data to pass to the style
 

mixed $object

The actual Midgard style object
 

\id $_context

Current context
 

array $_scope

Current style scope
 

string $_snippetdir

Default style path
 

array $_snippets

Default style element cache
todo Is this still in use?
 

array $_styledirs_append

List of styledirs to handle after componentstyle
 

array $_styledirs_prepend

List of styledirs to handle before componentstyle
 

array $_styles

Style element cache
 

\midcom_db_topic $_topic

Current topic