
Allows for quick and flexible HTML templating
1.0.0b23 | Added a default $name for retrieve() to mirror attach() 8/31/11 |
---|---|
1.0.0b22 | Backwards Compatibility Break - removed the static method create(), added the static method attach() to fill its place 8/31/11 |
1.0.0b21 | Fixed a bug in enableMinification() where the minification cache directory was sometimes not properly converted to a web path 8/31/11 |
1.0.0b20 | Fixed 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.0b19 | Corrected a bug in enablePHPShortTags() that would prevent proper translation inside of HTML tag attributes 1/9/11 |
1.0.0b18 | Fixed a bug with CSS minification and black hex codes 10/10/10 |
1.0.0b17 | Backwards 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.0b16 | Fixed another bug with minifying JS regex literals 9/13/10 |
1.0.0b15 | Fixed a bug with minifying JS regex literals that occur after a reserved word 9/12/10 |
1.0.0b14 | Added documentation about [sub-key] syntax 9/12/10 |
1.0.0b13 | Backwards 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.0b12 | Added 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.0b11 | Fixed a bug with the elements not being initialized to a blank array 8/12/10 |
1.0.0b10 | Updated place() to ignore URL query strings when detecting an element type 7/26/10 |
1.0.0b9 | Added the methods delete() and remove() 7/15/10 |
1.0.0b8 | Fixed a bug with placing absolute file paths on Windows 7/9/10 |
1.0.0b7 | Removed e flag from preg_replace() calls 6/8/10 |
1.0.0b6 | Changed set() and add() to return the object for method chaining, changed set() and get() to accept arrays of elements 6/2/10 |
1.0.0b5 | Added encode() 5/20/10 |
1.0.0b4 | Added create() and retrieve() for named fTemplating instances 5/11/10 |
1.0.0b3 | Fixed an issue with placing relative file path 4/23/10 |
1.0.0b2 | Added the inject() method 1/9/09 |
1.0.0b | The initial implementation 6/14/07 |
The directory to look for files
string
Attaches a named template that can be accessed from any scope via retrieve()
void attach( fTemplating $templating, string $name='default' )
fTemplating | $templating | The fTemplating object to attach |
string | $name | The name for this templating instance |
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
void reset( )
Retrieves a named template
fTemplating retrieve( string $name='default' )
string | $name | The name of the template to retrieve |
The specified fTemplating instance
Initializes this templating engine
fTemplating __construct( string $root=NULL, string $main_element=NULL )
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 |
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
void __destruct( )
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
callback __get( string $method )
string | $method | The method to create a callback for |
The callback for the method requested
Adds a value to an array element
fTemplating add( string $element, mixed $value, boolean $beginning=FALSE )
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 |
The template object, to allow for method chaining
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.
void buffer( )
Deletes an element from the template
mixed delete( string $element, mixed $default_value=NULL )
mixed delete( array $elements )
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 |
The value of the $element that was deleted - an associative array of deleted elements will be returned if an array of $elements was specified
Erases all output since the invocation of the template - only works if buffering is on
void destroy( )
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.
void enableMinification( string $mode, fDirectory|string $cache_directory, fDirectory|string $path_prefix=NULL )
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'] |
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.
void enablePHPShortTags( string $mode, fDirectory|string $cache_directory )
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 |
Gets the value of an element and runs it through fHTML::encode()
mixed encode( string $element, mixed $default_value=NULL )
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 |
The value of the element specified run through fHTML::encode(), or the default value if it has not been set
Removes a value from an array element
fTemplating filter( string $element, mixed $value )
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 |
The template object, to allow for method chaining
Gets the value of an element
mixed get( string $element, mixed $default_value=NULL )
mixed get( array $elements )
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 |
The value of the element(s) specified, or the default value(s) if it has not been set
Combines an array of CSS or JS files and places them as a single file
void handleMinified( string $type, string $element, array $values )
string | $type | The type of compilation, 'css' or 'js' |
string | $element | The element name |
array | $values | An array of file paths |
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.
void inject( string $file_path, string $file_type=NULL )
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'. |
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.
string minify( string $code, string $type )
string | $code | The code to minify |
string | $type | The type of code, 'css' or 'js' |
The minified code
Takes a block of CSS or JS and reduces the number of characters
void minifyCode( string &$part, string &$buffer, &$stack, mixed $type='js', array $stack )
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 |
Takes a literal and either discards or keeps it
void minifyLiteral( mixed &$part, mixed &$buffer, string $type )
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' |
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}
);
void place( string $element='__main__', string $file_type=NULL )
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'. |
Prints a CSS link HTML tag to the output
void placeCSS( mixed $info )
mixed | $info | The path or array containing the 'path' to the CSS file. Array can also contain a key 'media'. |
Performs the action of actually placing an element
void placeElement( string $element, string $file_type )
string | $element | The element that is being placed |
string | $file_type | The file type to treat all values as |
Prints a javascript HTML tag to the output
void placeJS( mixed $info )
mixed | $info | The path or array containing the 'path' to the javascript file |
Includes a PHP file
void placePHP( string $element, string $path )
string | $element | The element being placed |
string | $path | The path to the PHP file |
Prints an RSS link HTML tag to the output
void placeRSS( mixed $info )
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. |
Gets the value of an element and runs it through fHTML::prepare()
mixed prepare( string $element, mixed $default_value=NULL )
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 |
The value of the element specified run through fHTML::prepare(), or the default value if it has not been set
Removes and returns the value from the end of an array element
mixed remove( string $element, boolean $beginning=FALSE )
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 |
The value that was removed
Sets the value for an element
fTemplating set( string $element, mixed $value )
fTemplating set( array $elements )
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 |
The template object, to allow for method chaining
Ensures the value is valid
string verifyValue( string $element, mixed $value, string $file_type=NULL )
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 |
The file type of the value being placed