Innovative Computer Solutions,
Development & Technical Support

07975 997026 • enquiries[delete-me]@[delete-me]harpanet.com

User Tools

Site Tools


programming:php:codeigniter:hats:hats-functions

hArpanet Template System (hATS) for CodeIgniter

v2.1.1

hATS FUNCTION REFERENCE

A Templating system implements two closely related elements of functionality, therefore hATS is both an Asset manager and a Partials (Parts) system in one. The majority of helper functions are for Asset management, with only the 'Parts' section dealing with the collation of page content.

STYLESHEET HANDLING

hATS stylesheet functions provide a simple, consistent way to generate standard HTML stylesheet link tags from template paths.

In all cases, the .css extension will be added to the file if it is not specified.

tplStylesheet ( file [, in_theme] )

This function call would normally be placed within a Part file as it returns a HTML element.

Use this function if you always want a particular stylesheet loaded by your Part file.

tplStylesheet( file )

Return a fully qualified stylesheet 'link' tag from the current theme.

    // always load the common stylesheet
    <?php echo tplStylesheet('common'); ?>
 
    // assuming the 'christmas' theme is set, the above call would return...
 
    <link rel="stylesheet" href="http://mywebsite.com/hAts/theme/christmas/css/common.css" type="text/css" />

NOTE: It is possible to feed a variable through as the name of the stylesheet file, but this is not the correct way to use the tplStylesheet() function. Instead, use the tplAddStylesheet() function from your Controller.

    // do NOT do this...
 
    <?php echo tplStylesheet( tplGet('main_stylesheet') ); ?>

tplStylesheet( file, in_theme )

Return a fully qualified stylesheet 'link' tag from outside the current theme.

The optional in_theme parameter may be set to FALSE if file contains the full path to a stylesheet that resides outside the current theme. This is equivalent to using the link_tag() function from the CodeIgniter html_helper.

If file does not begin with http then the current CodeIgniter base_url config setting is prepended to file:

    <?php echo tplStylesheet('assets/css/global.css', FALSE); ?>
 
    // path does NOT contain 'http', so use current base_url...
 
    <link rel="stylesheet" href="http://mywebsite.com/assets/css/common.css" type="text/css" />

If file does begin with http then the path is left as specified:

    <?php echo tplStylesheet('http://remotesite.com/public/css/funky.css', FALSE); ?>
 
    // path contains 'http'...
 
    <link rel="stylesheet" href="http://remotesite.com/public/css/funky.css" type="text/css" />

tplAddStylesheet ( file [, in_theme] )

This function call would normally be placed within a Controller. On its own, this function does nothing, other than add a stylesheet to the stylesheet stack. After stacking, use tplStylesheets() to generate the relevant link tags.

Use this function to add additional stylesheet files as required by particular controllers.

tplAddStylesheet( file )

Add a stylesheet to the stylesheet stack.

See tplStylesheet() for a description of file.

    public function login() {
        // add login_page stylesheet
        tplAddStylesheet('login_page');
    }

tplAddStylesheet( file, in_theme )

Add a stylesheet located outside the current theme to the stylesheet stack.

See tplStylesheet() for a description of optional parameter in_theme.

    public function login() {
        // add forms stylesheet from outside theme
        tplAddStylesheet('/assets/css/forms', FALSE);
    }

tplStylesheets ()

This function call would normally be placed within a Part file as it returns HTML element(s). This function accepts no parameters.

tplStylesheets()

Generate HTML <link> tags for all stacked stylesheets.

    <?php echo tplStylesheets(); ?>
 
    // after the two tplAddStylesheet() calls above, this would generate...
 
    <link rel="stylesheet" href="http://mywebsite.com/hAts/theme/christmas/login_page.css" type="text/css" />
    <link rel="stylesheet" href="http://mywebsite.com/assets/css/forms.css" type="text/css" />

JAVASCRIPT HANDLING

hATS javascript functions provide a simple, consistent way to generate standard HTML javascript script tags from template paths.

In all cases, the .js extension will be added to the file if it is not specified.

tplJavascript ( file [, in_theme] )

This function call would normally be placed within a Part file as it returns a HTML element.

Use this function if you always want a particular javascript loaded by your Part file.

tplJavascript( file )

Return a fully qualified 'script' tag from the current theme.

    // always load the menu javascript
    <?php echo tplJavascript('menu'); ?>
 
    // assuming the 'christmas' theme is set, the above call would return...
 
    <script type='text/javascript' src='http://mywebsite.com/hAts/theme/christmas/js/menu.js'></script>

NOTE: It is possible to feed a variable through as the name of the javascript file, but this is not the correct way to use the tplJavascript() function. Instead, use the tplAddJavascript() function from your Controller.

    // do NOT do this...
 
    <?php echo tplJavascript( tplGet('main_javascript') ); ?>

tplJavascript( file, in_theme )

Return a fully qualified javascript 'script' tag from outside the current theme.

The optional in_theme parameter may be set to FALSE if file contains the full path to a javascript that resides outside the current theme. Most useful for loading common javascript libraries such as jQuery which are not theme specific.

If file does not begin with http then the current CodeIgniter base_url config setting is prepended to file:

    <?php echo tplJavascript('assets/jQuery/1.11.1/jquery.min.js', FALSE); ?>
 
    // path does NOT contain 'http', so use current base_url...
 
    <script type='text/javascript' src='http://mywebsite.com/assets/jQuery/1.11.1/jquery.min.js'></script>

If file does begin with http then the path is left as specified:

    <?php echo tplJavascript('http://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js', FALSE); ?>
 
    // path contains 'http'...
 
    <script type='text/javascript' src='http://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js'></script>

tplJavascriptParsed ( file [, in_theme] )

This function call would normally be placed within a Part file as it returns a HTML element.

Use this function if you always want a particular javascript included in your Part file.

The difference from tplJavascript() is that tplJavascriptParsed() allows PHP to be included within the specified javascript file. (You could use this for passing PHP variables into javascript files.)

This function uses PHP's eval() function on the javascript file.

Be aware of the security implications of using eval()!!

tplJavascriptParsed( file )

Return a HTML 'script' tag from the current theme.

    // always load the menu javascript, but parse it for PHP tags
    <?php echo tplJavascriptParsed('menu'); ?>
 
    // the above call may return something like...
 
    <script type='text/javascript'>
        function menu() {
            // value 'foobar' was provided by PHP script
            var menu_item = 'foobar'
            $(this).find(menu_item).css('visibility', 'visible');
        };
    </script>

tplJavascriptParsed( file, in_theme )

Return a HTML 'script' tag from outside the current theme.

The optional in_theme parameter may be set to FALSE if file contains the full path to a javascript that resides outside the current theme. Most useful for loading common javascript libraries which are not theme specific.

tplJavascriptParsed() uses PHP's file_get_contents() to load the javascript file before passing it to PHP's eval() function.

As per the file_get_contents() documentation (see php.net) …

A URL can be used as a filename with this function if the fopen wrappers have been enabled.

Therefore, it would be pretty stupid to use tplJavascriptParsed() with an external file and in_theme set to FALSE as it would allow anyone with control over the external file to run any PHP on your server!!

tplAddJavascript ( file [, in_theme] )

This function call would normally be placed within a Controller. On its own, this function does nothing, other than add a javascript to the javascript stack. After stacking, use tplJavascripts() to generate the relevant script tags.

Use this function to add additional javascript files as required by particular controllers.

tplAddJavascript( file )

Add a javascript to the javascript stack.

See tplJavascript() for a description of file.

    public function login() {
        // add login_page javascript
        tplAddJavascript('login_page');
    }

tplAddJavascript( file, in_theme )

Add a javascript located outside the current theme to the javascript stack.

See tplJavascript() for a description of optional parameter in_theme.

    public function login() {
        // add forms javascript from outside theme
        tplAddJavascript('/assets/js/forms', FALSE);
    }

tplJavascripts()

This function call would normally be placed within a Part file as it returns HTML element(s). This function accepts no parameters.

tplJavascripts()

Generate HTML <script> tags for all stacked javascripts.

    <?php echo tplJavascripts(); ?>
 
    // after the two tplAddJavascript() calls above, this would generate...
 
    <script type='text/javascript' src='http://mywebsite.com/hAts/theme/christmas/js/login_page.js'></script>
    <script type='text/javascript' src='http://mywebsite.com/assets/js/forms.js'></script>

IMAGE HANDLING

tplImage ( file [, in_theme] )

This function is called from a Controller OR within a Part file as it returns a URI to an image. It does not generate the necessary <img src=' ' /> wrapper.

NOTE: The image file extension (.jpg, .png, etc.) must be specified in file.

tplImage( file )

Return a full URI to the specified image file.

    // using HTML in a Part file, show 'logo' from current theme's img folder...
    <img src="<?= tplImage('logo.jpg') ?>" />
 
    // in a Controller, generate an image tag...
    public function index() {
        $imgpath = tplImage('logo');
 
        $tplSet('logo_img', "<img src='{$imgpath}' />");
 
        $this->load->view('hats_default');
    }

tplImage( file, in_theme )

Return a full URI to the specified image file located outside current theme.

The optional in_theme parameter may be set to FALSE if file contains the full path to an image that resides outside the current theme.

    // using HTML in a Part file, show 'logo' from current theme's img folder...
    <img src="<?= tplImage('assets/images/logo.jpg', FALSE) ?>" />
 
    // in a Controller, generate an image tag...
    public function index() {
        $imgpath = tplImage('assets/images/logo.jpg', FALSE);
 
        $tplSet('logo_img', "<img src='{$imgpath}' />");
 
        $this->load->view('hats_default');
    }

VARIABLE HANDLING

hATS provides a number of variable handling functions to manage values to display in your Part file.

tplSet ( name, value [, element] )

Create or overwrite the value of the specified variable.

tplSet( name, value )

Set a variable named name with the value value.

  tplSet( 'username', $this->db->username );

tplSet( name, value, element )

Set specific elements of an array using the optional element parameter.

If a previous value contained an array instead of a simple value, it is possible to set specific elements of that array using the optional element name.

  // build a basic array
  $arry = array('id' => 42, 'name' => 'H. Hiker');
 
  // put array into template variable named 'user'
  tplSet( 'user', $arry );
 
  // change the 'name' element of 'user'
  tplSet( 'user', 'Fred Bloggs', 'name' );

tplAdd ( name, value )

Add content to an existing variable.

NOTE: You do not need to use tplSet() before you can use tplAdd().

tplAdd( name, value )

Adds (appends) value to end of any value already stored in variable name.

  tplSet( 'name', 'Fred' );
  tplAdd( 'name', ' Bloggs' );    // 'name' now contains 'Fred Bloggs'

If variable name already contains an array(), using tplAdd() will add value as a new indexed (numerical) array element within name.

  tplSet('name', array('forename'));
  tplAdd('name', 'surname');
 
  // variable 'name' now contains...
  // array(
  //          [0]=>'forename',
  //          [1]=>'surname'
  //       )

tplGet ( name [, element] )

Retrieve values from variables.

tplGet( name )

Get the value from a variable named name.

  // in an HTML Part file...
  <?php echo tplGet('username'); ?>
 
  // in your Controller...
  $name = tplGet('forename') . tplGet('surname');

tplGet( name, element )

Get element value from array name.

If the variable name contains an array instead of a simple value, specifying the optional element parameter to retrieve a specific element of that array.

  tplSet( 'user', array('name'=>'Fred', 'id'=>42));
 
  tplGet( 'user', 'name' );
  tplGet( 'user', 'id' );

tplGetOr ( name [, or] )

Retrieve values from variables OR return default value.

or is optional, but if you don't need a default value then use tplGet() instead.

As tplGet() will always return an empty string if the variable name doesn't exist, you can retrieve FALSE or NULL instead by using tplGetOr().

tplGetOr( name, or )

Get the value from a variable named name. If variable is empty, return or value instead.

  // in an HTML Part file...
  <?php echo tplGetOr('username', 'Guest'); ?>
 
  // in your Controller...
  $name = tplGetOr('forename', 'Jon') . tplGetOr('surname', 'Doe');
 
  // is user logged in...
  $user_ok = tplGetOr('logged_in', FALSE);

PARTS HANDLING

Partial (Parts) handling functions allow the construction of pages from multiple smaller blocks of PHTML (PHP with HTML).

hATS allows Parts files to include calls to other (child) Parts files, making reuseable elements much easier.

tplGetPart ( part )

This function call must be placed within a Part file (or any CodeIgniter View file) as it requires (inserts) the specified part file.

The hats_default.php View file in /application/views uses tplGetPart() to construct the default layout.

Use a similar approach when creating your own layout files.

tplGetPart( part )

Output the contents of the specified part file.

    // in an HTML Part file (or any View file), notice the lack of ECHO...
    <? tplGetPart('header'); ?>

tplAddPart ( part [, data] )

Add a Part file to the parts stack. Use this when constructing a page from multiple Parts.

This function call would normally be placed within a Controller. On its own, this function does nothing, other than add a part to the parts stack. After stacking, use tplGetParts() to display all stacked parts.

tplAddPart( part )

Add part to the Parts stack for later display.

    public function login() {
        // switch to login parts folder (see alterative example below)
        tplSet('parts', 'login');
 
        // add the login_form from the login parts folder
        // ie. /hAts/parts/login/login_form.phtml
        tplAddPart('login_form');
 
        $this->load->view('hats_default');
    }

An alternative way to reference parts is by specifying the path directly in the tplAddPart() call:

    public function login() {
        // don't switch to login parts folder
        // tplSet('parts', 'login');
 
        // or, to ensure that 'parts' hasn't been set in another controller
        tplSet('parts', '');
 
        // add the login_form from the login parts folder
        // ie. /hAts/parts/login/login_form.phtml
        tplAddPart('login/login_form');
 
        $this->load->view('hats_default');
    }

In practice, you would only use tplSet('parts', 'folder') when you are adding lots of parts with tplAddPart(). By setting the parts folder saves you specifying the folder name in each tplAddPart() call - and makes it easier to relocate the parts at a later date.

tplAddPart( part, data )

Add part to the Parts stack and associate data variables with it.

  • The optional data parameter allows specific values to be associated with this instance of the part being added.
  • The data parameter allows for a Part to be added multiple times (eg. generating a list of people, contact details, videos etc.) but have individual data available to each Part.
  • data must be an associative array of 'variable name'⇒'value' pairs. (ie. data will only normally be passed when a Part is being loaded multiple times.)
  • To display these values within the part, use <?= tplGet('variable name') ?> as normal.
  • This prevents the need for PHP code loops within your Parts. (ie. no need to create an array of values with, for example, tplSet('contacts', $contactsArray) then have foreach(tplGet('contacts') as $contact) { echo $contact['name']; } within your Part. Simply place <?= tplGet('name') ?> in the Part and it will display the 'name' specifically associated with that Part when it was added with tplAddPart().
    public function index{} {
 
        // switch to members parts folder
        tplSet('parts', 'members');
 
        $names = $this->db->get_names();
 
        // construct members page
 
        tplAddPart('members_header');
 
        foreach ($names as $name) {
            tplAddPart('members_row', $name);
        }
 
        tplAddPart('members_footer');
 
        $this->load->view('hats_default');
    }

tplGetParts ()

This function call must be placed within a Part file (or any CodeIgniter View file) as it requires (inserts) each part file. This function accepts no parameters.

The body_content.phtml file in /hAts/parts/hAts_default uses tplGetParts() to output all stacked Part files.

Use a similar approach in your main Part files.

tplGetParts()

Ouput all parts stacked using tplAddPart().

    // in an HTML Part file, notice the lack of ECHO ...
 
    <?php tplGetParts(); ?>

tplGetPartAsHtml ( part )

This function call is most likely to be used in your Controller (there's little sense in using it within your Part files unless you specifically want to prevent PHP from being executed).

You might want to use this function if you need to perform additional processing on the Part contents before sending to browser (maybe replacing placeholders, etc.).

tplGetPartAsHtml( part )

Retrieve the contents of the specified part file as a string.

    public function index() {
 
        // get Parts contents
        $the_part = tplGetPartAsHtml('widget');
 
        // replace something
        $the_part = str_replace('{{placeholder}}', 'some content', $the_part);
 
        // put the entire part into a variable for later use
        tplSet('placeholder_widget', $the_part);
 
        $this->load->view('hats_default');
    }

MISCELLANEOUS

tplResponse_message ( name, css )

This function call would normally be placed within a Part file as it echo's the response message wrapped in an HTML <div> tag.

The body_open.phtml file in /hAts/parts/hAts_default includes this call.

Note that you do not need to use echo to display the message.

See /application/controllers/hats_example.php for an example of using this function.

tplResponse_message( [name] [, css] )

Both parameters are optional…

  • name is a hAts variable name containing the message to display
  • css is the name of a stylesheet class to apply to the name message
  • If name has been specified, tplResponse_message displays the contents of the name variable
    • If css has not been specified, the name message is wrapped in CSS class named response_'name'
    • If css has been specified, the name message is wrapped in CSS class named response_'css'
  • Regardless of whether name is specified, tplResponse_message always attempts to displays the contents of the variables named success and fail
    • success message is wrapped in CSS class named response_success
    • fail message is wrapped in CSS class named response_fail

If jQuery is installed, the messages will auto fade 'slowly'.

hATS RESERVED VARIABLES

When using tplSet() or tplAdd(), the following variable names are reserved to either provide global functionality changes or for use internally.

debug

Type: BOOL Default: FALSE

If you are not getting the result that you are expecting when including Parts and assets with hATS, it is sometimes helpful to enable debug which will show where hATS is looking for its files.

Set to TRUE to force hATS to display debug messages as it processes template requests.

    tplSet('debug', TRUE);

partsPath

Location (folder name) of parts files.

Type: STRING Default: hAts/parts

As Parts files are required (PHP 'require' keyword) they don't need to be in the public web space, so you can move the entire parts folder elsewhere (eg. your CI Views folder) then set this variable to the new location.

    tplSet('partsPath', 'application/views/parts');

themePath

Location (folder name) of theme files

Type: STRING Default: hAts/theme

Theme asset files are linked to using a URI, therefore they must stay in the public web space, but you can change their location to something that meets your own structure; then set this variable to the new location.

    tplSet('themePath', 'assets/themes');

STOP_ON_ERROR

Type: BOOL Default: FALSE

By default, hATS displays a message in place of any missing Part file stating that the Parts file was not found.

Set to TRUE to force hATS to generate an error when a Part file is not found during tplGetPart() or tplGetParts() calls.

    tplSet('STOP_ON_ERROR', TRUE);

The following reserved variables have no direct use to developers, and are used internally.


viewPart

Type: array Default: void

Array containing names of view parts to display - use tplAddPart() & tplGetPart().

css

Type: array Default: void

Array containing names of css files to display - use tplAddStylesheet() and tplStylesheets()

js

Type: array Default: void

Array containing names of js files to output - use tplAddJavascript() and tplJavascripts()

success

Type: array Default: void

If you use tplResponse_message(), it assumes anything in the 'success' var is the message to show.

fail

Type: array Default: void

If you use tplResponse_message(), it assumes anything in the 'fail' var is the message to show.

Comments



A P G O Z P C V᠎ T D F T
programming/php/codeigniter/hats/hats-functions.txt · Last modified: 14/07/2014 20:49 by harpanet