Flourish PHP Unframework

fTemplating

class, v1.0.0b23

Allows for quick and flexible HTML templating

Changes:
1.0.0b23Added a default $name for retrieve() to mirror attach() 8/31/11
1.0.0b22Backwards Compatibility Break - removed the static method create(), added the static method attach() to fill its place 8/31/11
1.0.0b21Fixed a bug in enableMinification() where the minification cache directory was sometimes not properly converted to a web path 8/31/11
1.0.0b20Fixed a bug in CSS minification that would reduce multiple zeros that are part of a hex color code, fixed minification of + ++ and similar constructs in JS 8/31/11
1.0.0b19Corrected a bug in enablePHPShortTags() that would prevent proper translation inside of HTML tag attributes 1/9/11
1.0.0b18Fixed a bug with CSS minification and black hex codes 10/10/10
1.0.0b17Backwards Compatibility Break - delete() now returns the values of the element or elements that were deleted instead of returning the fTemplating instance 9/19/10
1.0.0b16Fixed another bug with minifying JS regex literals 9/13/10
1.0.0b15Fixed a bug with minifying JS regex literals that occur after a reserved word 9/12/10
1.0.0b14Added documentation about [sub-key] syntax 9/12/10
1.0.0b13Backwards Compatibility Break - add(), delete(), get() and set() now interpret [ and ] as array shorthand and thus they can not be used in element names, renamed remove() to filter() - added $beginning parameter to add() and added remove() method 9/12/10
1.0.0b12Added enableMinification(), enablePHPShortTags(), the ability to be able to place child fTemplating objects via a new magic element __main__ and the $main_element parameter for __construct() 8/31/10
1.0.0b11Fixed a bug with the elements not being initialized to a blank array 8/12/10
1.0.0b10Updated place() to ignore URL query strings when detecting an element type 7/26/10
1.0.0b9Added the methods delete() and remove() 7/15/10
1.0.0b8Fixed a bug with placing absolute file paths on Windows 7/9/10
1.0.0b7Removed e flag from preg_replace() calls 6/8/10
1.0.0b6Changed set() and add() to return the object for method chaining, changed set() and get() to accept arrays of elements 6/2/10
1.0.0b5Added encode() 5/20/10
1.0.0b4Added create() and retrieve() for named fTemplating instances 5/11/10
1.0.0b3Fixed an issue with placing relative file path 4/23/10
1.0.0b2Added the inject() method 1/9/09
1.0.0bThe initial implementation 6/14/07

Static Variables

::$instances

Named fTemplating instances

Type

array

Variables

->root protected

The directory to look for files

Type

string

Static Methods

::attach() public

Attaches a named template that can be accessed from any scope via retrieve()

Signature

void attach( fTemplating $templating, string $name='default' )

Parameters

fTemplating $templating The fTemplating object to attach
string $name The name for this templating instance

::reset() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Resets the configuration of the class

Signature

void reset( )

::retrieve() public

Retrieves a named template

Signature

fTemplating retrieve( string $name='default' )

Parameters

string $name The name of the template to retrieve

Returns

The specified fTemplating instance

Methods

->__construct() public

Initializes this templating engine

Signature

fTemplating __construct( string $root=NULL, string $main_element=NULL )

Parameters

string $root The filesystem path to use when accessing relative files, defaults to $_SERVER['DOCUMENT_ROOT']
string $main_element The value for the __main__ element - this is used when calling place() without an element, or when placing fTemplating objects as children

->__destruct() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Finishing placing elements if buffering was used

Signature

void __destruct( )

->__get() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

All requests that hit this method should be requests for callbacks

Signature

callback __get( string $method )

Parameters

string $method The method to create a callback for

Returns

The callback for the method requested

->add() public

Adds a value to an array element

Signature

fTemplating add( string $element, mixed $value, boolean $beginning=FALSE )

Parameters

string $element The element to add to - array elements can be modified via [sub-key] syntax, and thus [ and ] can not be used in element names
mixed $value The value to add
boolean $beginning If the value should be added to the beginning of the element

Returns

The template object, to allow for method chaining

->buffer() public

Enables buffered output, allowing set() and add() to happen after a place() but act as if they were done before

Please note that using buffered output will affect the order in which code is executed since the elements are not actually place()'ed until the destructor is called.

If the non-template code depends on template code being executed sequentially before it, you may not want to use output buffering.

Signature

void buffer( )

->delete() public

Deletes an element from the template

Signatures

mixed delete( string $element, mixed $default_value=NULL )

mixed delete( array $elements )

Parameters

string $element The element to delete - array elements can be modified via [sub-key] syntax, and thus [ and ] can not be used in element names
mixed $default_value The value to return if the $element is not set
array $elements The elements to delete - an array of element names or an associative array of keys being element names and the values being the default values

Returns

The value of the $element that was deleted - an associative array of deleted elements will be returned if an array of $elements was specified

->destroy() public

Erases all output since the invocation of the template - only works if buffering is on

Signature

void destroy( )

->enableMinification() public

Enables minified output for CSS and JS elements

For CSS and JS, compilation means that the file will be minified and cached. The filename will change whenever the content change, allowing for far-futures expire headers.

Please note that this option requires that all CSS and JS paths be relative to the $_SERVER['DOCUMENT_ROOT'] and start with a /. Also this class will not clean up old cached files out of the cache directory.

This functionality will be inherited by all child fTemplating objects that do not have their own explicit minification settings.

Signature

void enableMinification( string $mode, fDirectory|string $cache_directory, fDirectory|string $path_prefix=NULL )

Parameters

string $mode The compilation mode - 'development' means that file modification times will be checked on each load, 'production' means that the cache files will only be regenerated when missing
fDirectory|string $cache_directory The directory to cache the compiled files into - this needs to be inside the document root or a path added to fFilesystem::addWebPathTranslation()
fDirectory|string $path_prefix The directory to prepend to all CSS and JS paths to load the files from the filesystem - this defaults to $_SERVER['DOCUMENT_ROOT']

->enablePHPShortTags() public

Converts PHP short tags to long tags when short tags are turned off

Please note that this only affects PHP files that are directly evaluated with place() or inject(). It will not affect PHP files that have been evaluated via include or require statements inside of the directly evaluated PHP files.

This functionality will be inherited by all child fTemplating objects that do not have their own explicit short tag settings.

Signature

void enablePHPShortTags( string $mode, fDirectory|string $cache_directory )

Parameters

string $mode The compilation mode - 'development' means that file modification times will be checked on each load, 'production' means that the cache files will only be regenerated when missing
fDirectory|string $cache_directory The directory to cache the compiled files into - this directory should not be accessible from the web

->encode() public

Gets the value of an element and runs it through fHTML::encode()

Signature

mixed encode( string $element, mixed $default_value=NULL )

Parameters

string $element The element to get - array elements can be accessed via [sub-key] syntax, and thus [ and ] can not be used in element names
mixed $default_value The value to return if the element has not been set

Returns

The value of the element specified run through fHTML::encode(), or the default value if it has not been set

->filter() public

Removes a value from an array element

Signature

fTemplating filter( string $element, mixed $value )

Parameters

string $element The element to remove from - array elements can be modified via [sub-key] syntax, and thus [ and ] can not be used in element names
mixed $value The value to remove - compared in a non-strict manner, such that removing 0 will remove a blank string and false also

Returns

The template object, to allow for method chaining

->get() public

Gets the value of an element

Signatures

mixed get( string $element, mixed $default_value=NULL )

mixed get( array $elements )

Parameters

string $element The element to get - array elements can be accessed via [sub-key] syntax, and thus [ and ] can not be used in element names
mixed $default_value The value to return if the element has not been set
array $elements An array of elements to get, or an associative array where a string key is the element to get and the value is the default value

Returns

The value of the element(s) specified, or the default value(s) if it has not been set

->handleMinified() protected

Combines an array of CSS or JS files and places them as a single file

Signature

void handleMinified( string $type, string $element, array $values )

Parameters

string $type The type of compilation, 'css' or 'js'
string $element The element name
array $values An array of file paths

->inject() public

Includes the file specified - this is identical to place() except a filename is specified instead of an element

Please see the place() method for more details about functionality.

Signature

void inject( string $file_path, string $file_type=NULL )

Parameters

string $file_path The file to place
string $file_type Will force the file to be placed as this type of file instead of auto-detecting the file type. Valid types include: 'css', 'js', 'php' and 'rss'.

->minify() protected

Minifies JS or CSS

For JS, this function is based on the JSMin algorithm (not the code) from http://www.crockford.com/javascript/jsmin with the addition of preserving /*! comment blocks for things like licenses. Some other versions of JSMin change the contents of special comment blocks, but this version does not.

Signature

string minify( string $code, string $type )

Parameters

string $code The code to minify
string $type The type of code, 'css' or 'js'

Returns

The minified code

->minifyCode() protected

Takes a block of CSS or JS and reduces the number of characters

Signature

void minifyCode( string &$part, string &$buffer, &$stack, mixed $type='js', array $stack )

Parameters

string &$part The part of code to minify
string &$buffer A buffer containing the last code or literal encountered
array $stack A stack used to keep track of the nesting level of CSS
mixed $type The type of code, 'css' or 'js'
&$stack

->minifyLiteral() protected

Takes a literal and either discards or keeps it

Signature

void minifyLiteral( mixed &$part, mixed &$buffer, string $type )

Parameters

mixed &$part The literal to process
mixed &$buffer The last literal or code processed
string $type The language the literal is in, 'css' or 'js'

->place() public

Includes the element specified - element must be set through set() first

If the element is a file path ending in .css, .js, .rss or .xml an appropriate HTML tag will be printed (files ending in .xml will be treated as an RSS feed). If the element is a file path ending in .inc, .php or .php5 it will be included.

Paths that start with ./ will be loaded relative to the current script. Paths that start with a file or directory name will be loaded relative to the $root passed in the constructor. Paths that start with / will be loaded from the root of the filesystem.

You can pass the media attribute of a CSS file or the title attribute of an RSS feed by adding an associative array with the following formats:

array(
    'path'  => (string) {css file path},
    'media' => (string) {media type}
);
array(
    'path'  => (string) {rss file path},
    'title' => (string) {feed title}
);

Signature

void place( string $element='__main__', string $file_type=NULL )

Parameters

string $element The element to place
string $file_type Will force the element to be placed as this type of file instead of auto-detecting the file type. Valid types include: 'css', 'js', 'php' and 'rss'.

->placeCSS() protected

Prints a CSS link HTML tag to the output

Signature

void placeCSS( mixed $info )

Parameters

mixed $info The path or array containing the 'path' to the CSS file. Array can also contain a key 'media'.

->placeElement() protected

Performs the action of actually placing an element

Signature

void placeElement( string $element, string $file_type )

Parameters

string $element The element that is being placed
string $file_type The file type to treat all values as

->placeJS() protected

Prints a javascript HTML tag to the output

Signature

void placeJS( mixed $info )

Parameters

mixed $info The path or array containing the 'path' to the javascript file

->placePHP() protected

Includes a PHP file

Signature

void placePHP( string $element, string $path )

Parameters

string $element The element being placed
string $path The path to the PHP file

->placeRSS() protected

Prints an RSS link HTML tag to the output

Signature

void placeRSS( mixed $info )

Parameters

mixed $info The path or array containing the 'path' to the RSS xml file. May also contain a 'title' key for the title of the RSS feed.

->prepare() public

Gets the value of an element and runs it through fHTML::prepare()

Signature

mixed prepare( string $element, mixed $default_value=NULL )

Parameters

string $element The element to get - array elements can be access via [sub-key] syntax, and thus [ and ] can not be used in element names
mixed $default_value The value to return if the element has not been set

Returns

The value of the element specified run through fHTML::prepare(), or the default value if it has not been set

->remove() public

Removes and returns the value from the end of an array element

Signature

mixed remove( string $element, boolean $beginning=FALSE )

Parameters

string $element The element to remove from to - array elements can be modified via [sub-key] syntax, and thus [ and ] can not be used in element names
boolean $beginning If the value should be removed from the beginning of the element

Returns

The value that was removed

->set() public

Sets the value for an element

Signatures

fTemplating set( string $element, mixed $value )

fTemplating set( array $elements )

Parameters

string $element The element to set - the magic element __main__ is used for placing the current fTemplating object as a child of another fTemplating object - array elements can be modified via [sub-key] syntax, and thus [ and ] can not be used in element names
mixed $value The value for the element
array $elements An associative array with the key being the $element to set and the value being the $value for that element

Returns

The template object, to allow for method chaining

->verifyValue() protected

Ensures the value is valid

Signature

string verifyValue( string $element, mixed $value, string $file_type=NULL )

Parameters

string $element The element that is being placed
mixed $value A value to be placed
string $file_type The file type that this element will be displayed as - skips checking file extension

Returns

The file type of the value being placed