fTemplatingclassv1.0.0b12
Allows for quick and flexible HTML templating
| 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 |
Variables
->rootprotected
The directory to look for files
Type
string
Static Methods
::create() public
Creates a named template that can be accessed from any scope via retrieve()
Signature
fTemplating create( string $name, string $root=NULL )
Parameters
| string | $name | The name for this template instance |
| string | $root | The filesystem path to use when accessing relative files, defaults to $_SERVER['DOCUMENT_ROOT'] |
Returns
The new fTemplating 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 )
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 )
Parameters
| string | $element | The element to add to |
| mixed | $value | The value to add |
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
fTemplating delete( string $element )
fTemplating delete( array $elements )
Parameters
| string | $element | The element to delete |
| array | $elements | The elements to delete |
Returns
The template object, to allow for method chaining
->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 |
| 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
->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 |
| 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 |
| 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 a value from an array element
Signature
fTemplating remove( string $element, mixed $value )
Parameters
| string | $element | The element to remove from |
| 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
->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 |
| 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
