API: PHP: Decorators

Description

The MWF provides a set of PHP decorators for developers who use PHP. These decorators aid in producing HTML markup programmatically with PHP code. They assist specifically in creating MWF applications because they provide an easy way to create the markup for several framework entities.

Intent

To facilitate the rapid production of HTML markup and specifically that required for MWF entities by offering a set of classes that represent different HTML markup entities. Use of the PHP decorators limits the necessity to intersperse HTML code within PHP files, instead allowing the developer to produce and echo all necessary HTML markup from within PHP code.

Implementation

The Decorators offered by the framework are split into two types: HTML decorators that produce generic HTML markup, and Site decorators that produce markup for the framework entities specifically. All decorators are produced through factory classes with static methods to build the desired decorators.

Basic Usage

All decorators are typically produced by calling a static method of one of the factory classes (HTML_Decorator or Site_Decorator). The static method calls match the class names of the various decorators, minus the '_HTML_Decorator' or '_Site_Decorator' postfixes. For instance, an instance of Tag_Close_HTML_Decorator can be created as follows:

$close_p_tag = HTML_Decorator::tag_close('p');

It is also of note that to output the markup generated by a decorator, the public render() method must be called. However, the __toString() magic method has been used to alias the render() function, so that any time a decorator object is echoed, it will automatically render the correct markup. *Note: This functionality is less forgiving for PHP versions prior to 5.2. From the PHP Documentation:

It is worth noting that before PHP 5.2.0 the __toString() method was only called when it was directly combined with echo() or print(). Since PHP 5.2.0, it is called in any string context

HTML Decorators

The HTML Decorators (and most all of the decorators for that matter) leverage one of three base classes: Tag_Open_HTML_Decorator, Tag_Close_HTML_Decorator, and Tag_HTML_Decorator. These classes can be used as follows:

Tag_Open_HTML_Decorator**

This decorator simply produces an opening HTML tag. The type of tag must be specified as the first argument to the constructor, and an array of parameters for the tag can optionally be specified as the second parameter. An example usage is as follows:

//echoes an opening div tag with a class of blue
echo HTML_Decorator::tag_open('div', array('class'=>'blue'));

This class has the following public methods:

• set_param($key, $val) - Adds/sets a parameter of type $key to $val
• set_params($params) - Adds/sets a set of parameters based on an associative array keyed by parameter name
• add_class($class) - Adds the given class to the tag
• remove_class($class) - Removes the given class from the tag

Tag_Close_HTML_Decorator

This decorator is even simpler than the tag open decorator. It will create a closing HTML tag based on the single required parameter passed to the constructor. An example usage is as follows:

//echoes a closing div tag
echo HTML_Decorator::tag_close('div');

Tag_HTML_Decorator

This is a more robust generic HTML Tag decorator that can be used to create a complete HTML element, with opening and closing tag, (optional) parameters, and inner contenet. Example Usage is as follows:

//echoes a div with the specified content and a class of 'red'
echo HTML_Decorator::tag('div', 'This is where inner content goes...', array('class'=>'red'));

If you would like to use the Tag decorator to create a null tag (such as an <img> or <br>), this can be achieved by specifying false for the second parameter (where the inner content would normally go). However, if any of the add_inner methods are called on the decorator (see below) then the corresponding set of tags will be produced instead of a single null tag. It is also of note that the second parameter to the Tag decorator constructor must be explicitly set to false, as it defaults to an empty string ('') which will in fact produce a closing tag.

This class has the following public methods:

• set_param($key, $val) - Adds/sets a parameter of type $key to $val
• set_params($params) - Adds/sets a set of parameters based on an associative array keyed by parameter name
• add_class($class) - Adds the given class to the tag
• remove_class($class) - Removes the given class from the tag
• add_inner_tag($tag, $inner, $params) - Adds another tag to the inner content of the tag. This uses the same prototype as the constructor for the Tag_HTML_Decorator class itself, and basically uses the arguments to spawn another instance of the class and add it to the inner content.
• add_inner_tag_front($tag, $inner, $params) - Identical to previous method, but adds the new tag to the beginning of the containing element.
• `add_inner($content) - Adds the given content to the inner content of the element. Note: The $content parameter may be an array of content items(strings).
• add_inner_front($content) - Identical to previous method, but adds the new content to the beginning of the containing element.
• flush_inner() - Clears all of the element's inner content.

Other HTML Decorators

There exist four additional HTML Decorators to simplify the semantic laying out of HTML pages. These are primarily aliases for the open and close tag decorators, but give the decorator code more semantic meaning.

• HTML_Start_HTML_Decorator - produces an HTML5 doctype and opening html tag for the page
• HTML_End_HTML_Decorator - produces the closing html tag for the page
• Body_Start_HTML_Decorator - produces the opening body tag for the page. Can be passed parameters for the tag
• Body_End_HTML_Decorator - produces the closing body tag for the page

Site Decorators

The set of Site decorators serve to aid in generating markup specific to MWF entities. There are Site decorators for each of the primary elements used in the framework, as well as a decorator for the head section of the HTML on a MWF page.

Head_Site_Decorator

The Head decorator is probably the most complex of the decorators. It includes by default the CSS and JS handlers for the MWF based on the instance's configuration files, and also adds the viewport meta tag by default. In addition to including required MWF head entities by default, the Head decorator allows for inclusion of several additional javascript files and stylesheets, and customization of handlers/attributes by way of public methods. The public methods offered by this class include the following:

• set_title($title) - Set the page title to the given string.
• set_css_handler($path) - Set the CSS handler to the given URL
• set_css_handler_params($params) - Set the GET parameters used on the CSS handler. The argument passed to this function should be an associative array of parameter values keyed by parameter name. This is useful for setting all additional CSS handler parameters in one call.
• add_css_handler_library($type, $library) - Add a library to the CSS handler as a GET parameter. This is useful for importing custom CSS for minification using the classification level as the first parameter($type) and the urlencoded path as the second parameter($library).
• set_js_handler($path) - Set the JS handler to the given URL
• set_js_handler_params($params) - Identical to set_css_handler_params() above, but for the JS handler
• add_js_handler_library($type, $library) - Identical to add_css_handler_library() above, but for the JS handler
• add_stylesheet($href, $media) - Add a custom stylesheet to the head with the URL specified by the first parameter($href). The second parameter($media) sets the media type of the stylesheet, and defaults to 'screen' if not specified.
• add_javascript($src) - Add a custom javascript script with the given source.

Example Usage

//Basic site head with default framework handlers, viewport meta tag, and specified title.
$basic_head = Site_Decorator::head()->set_title('Test Page Title');

//Customized site head with custom screen and print stylesheets added and a javascript file.
$custom_assets_head = Site_Decorator::head()
->set_title('Test Page with Custom Assets')
->add_stylesheet('main.css', 'screen')
->add_stylesheet('print.css', 'print')
->add_javascript('script.js');

Note: All public methods on decorators return a reference to the decorator object, so that method chaining(as displayed above) is allowed.

Header_Site_Decorator

This decorator is used to create a Header entity. It will render an H1 tag with an image (home button) and an optional title. If no image is specified through the public methods available in the class, the MWF instance configuration settings will be used. The following public methods are available to this class:

• set_title($title) - Set the title text for the header
• set_title_path($path) - Set the URL for the title text (if not specified, the title text will not be a link)
• set_image($image, $alt) - Set the header image URL ($image) and alt text ($alt)

Example Usage

echo Site_Decorator::header()
->set_title('Test Page Title');

Footer_Site_Decorator

This decorator is used to create a Footer entity. It renders a MWF footer with copyright text specified by the MWF instance configuration, and optional "full site" and "help" links. It will also render the "Powered by UCLA MWF" text by default. The following public methods are available in the class:

• set_copyright_text($text) - Sets the copyright text for the footer to the given string($text)
• set_help_site($title, $url) - Sets the text for the help site link based on the first parameter($title) and the URL for the link based on the second parameter($url)
• set_full_site($title, $url) - Same as the set_help_site() function but for the "view full site" link in the footer
• show_powered_by($val) - Toggles whether or not to show the "Powered by UCLA MWF" text in the footer. The first parameter should be true/false based on if the text should be enabled/disabled. Defaults to true.

Example Usage

//Creates a basic footer with specified copyright text, help link, and full site link
echo Site_Decorator::footer()
->set_copyright_text('© 2011 Somebody')
->set_help_site('Help', 'help.php')
->set_full_site('View Full Site', 'http://{FULL_SITE_URL}');

Default_Footer_Site_Decorator

This decorator is an extension of the Footer_Site_Decorator class that simply specifies the values for the full site and help links based on the MWF instance configuration. For creating core pages for an instance of the MWF, this is an easy way to provide consistency across all page footers.

Content_Full_Site_Decorator

This decorator is used to create a full width Content entity. The constructor accepts two arguments: the first specifies any inner content for the content area and the second accepts an associative array that delimits parameters that should be added to the content div (these parameters are synonymous with the second and third paramters of Tag_HTML_Decorator). Allows configuration and population of the content area by way of public methods. The following methods are offered by the class:

• set_padded($val) - Used to specify whether the .content-padded should be used. The parameter should be true/false specifying whether the content area should be padded or not. Defaults to true.
• add_header($inner, $params) - Adds a header to the content area. Content for the header is specified by the first argument($inner). The second argument($params) should be an associative array of parameters for the header, but will default to an empty array if not specified.
• add_header_light($inner, $params) - Same as previous method, but uses the .light class for the header text
• add_subheader($inner, $params) - Adds a subheader (h4 tag) to the content area. Usage is identical to add_header()
• add_paragraph($inner, $params) - Adds a paragraph to the content area. The two parameters are the same as the second and third parameters provided to the Tag_HTML_Decorator class, specifying the inner content and element parameters, respectively.
• add_section($inner, $params) - Adds a div element to the content area. Parameters again specify the inner content and element parameters for the div, identical to the previous method.

Example Usage

$content = '<p>Some textual content in a paragraph</p>';
$paragraph_text = 'Some text for a paragraph';
$image = '<img src="imageURL.jpg">';

//Creates a full width content area with a class and some content
echo Site_Decorator::content_full($paragraph, array('class'=>'someClass'));

//Creates a padded content area with a header, paragraph, and image div.
echo Site_Decorator::content_full()
->add_header('Second Content Area')
->add_paragraph($paragraph_text)
->add_section($image, array('class'=>'image_div')
->set_padded();

Menu_Full_Site_Decorator

This decorator is used to create a full width Menu entity. The constructor takes two arguments, the first specifies the title for the menu (defaults to false, which specifies no title), and the second is an associative array specifying the parameters for the menu div. The Menu Full decorator allows items and text to be added by calls to the public methods add_item() and add_text() respectively. The public methods offered by this class include:

• set_padded($val) - Sets whether or not the menu should be padded (adds class .menu-padded). The first parameter($val) should be true or false, depending on whether the menu should be padded or not.
• set_detailed($val) - Sets whether or not the menu should be a detailed menu (adds class .menu-detailed)
• set_title($inner, $params) - Sets the title for the menu to the string specified by $inner. The second argument($params) can be used to specify a set of parameters for the h1 menu element. Call the method with false as the first parameter to disable a title for the menu.
• set_title_light($inner, $params) - Same as above method, but uses the class .light on the title
• add_item($name, $url, $li_params, $a_params) - Adds a link item to the menu. The first argument($name) specifies the text for the menu item, and the second argument($url) specifies the link. The third and fourth (optional) arguments can be used to specify a set of parameters for the <li> element and <a> element respectively.
• add_text($text, $li_params, $a_params) - Adds a textual item to the menu (without a link). The first argument specifies the content for the textual item, and the second and third parameters are used to specify parameters for the <li> element and <a> element, just like add_item().

Example Usage

$link1 = 'Google';
$link2 = 'Yahoo';
$url1 = 'http://google.com';
$url2 = 'http://yahoo.com';

//Creates a simple menu with a title and two links
echo Site_Decorator::menu_full('Search Engines')
->add_item($link1, $url1)
->add_item($link2, $url2);

//Creates a padded menu with a light title and a text item, in addition to two links
echo Site_Decorator::menu_full()
->set_title_light('Search Engines')
->set_padded()
->add_text('This is a list of some common search engines for your use')
->add_item($link1, $url1)
->add_item($link2, $url2);

Button_Full_Site_Decorator

This decorator is used to create a full width Button entity.