Innovative Computer Solutions,
Development & Technical Support

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

User Tools

Site Tools


programming:php:codeigniter:hats:example

hArpanet Template System (hATS) for CodeIgniter

v2.1.1

New SINCE hATS v2.0 is an example Controller which generates an example page showing most of the features of hATS. The example Controller should give you the quickest introduction to hATS without the need for lots of descriptive commentary.

Throughout, we shall refer to the hATS example as HE.

hATS EXAMPLE PAGE

After installing hATS (copying the folders from the .zip file), you should be able to run the example Controller without any further setup by entering the URL http://yourwebsite.net/hats_example into your browser. (Obviously, yourwebsite.net should be replaced by the URL of the website you are testing hATS on.)

You will see the following page content displayed:

 The hATS example page

Text surrounded with [square brackets] in the HE page denotes actual variable names of content.

The styling of the HE page is handled by the stylesheet at /hAts/theme/hAts_default/css/style.css
as well as some hard-coding within the HE Controller.

The HE Parts are located at: /hAts/parts/hAts_default/*.phtml with sub-parts at /hAts/parts/hAts_default/test/*.phtml

hATS EXAMPLE CONTROLLER

The HE is located in /application/controllers/hats_example.php.

Rather than duplicate the entire Controller code here, we will just pull out relevant sections. The Controller itself is heavily commented.

Constructor Best Practice

    class Hats_example extends CI_Controller {
 
        public function __construct() {
            parent::__construct();
 
            // load hATS helper (best add it to autoload.php)
            $this->load->helper('hats');
 
            /* set hATS parts folder to name of current class
             * (if not set, 'hAts_default' is assumed
             *  which is good for this example but not for your site!)
             *  You SHOULD add this to your controllers!
             */
            // tplSet('parts', strtolower(get_class($this)));
        }

As the constructor mentions, you should normally be loading hAts helper from your autoload.phpconfig file.

The second comment also tells you that you SHOULD uncomment the line (in your own application) that sets the parts path to the same name as the controller currently running. It can go anywhere, but best set this in the constructor for consistency.

  • This has the effect of telling hATS that all 'parts' files (by default) for this controller are located in a folder within /hAts/parts/ with the same name as the controller being executed (eg. /hAts/parts/hats_example).
  • Even if you do set the parts path automatically here, you can easily override it for specific purposes later in your methods.

Debugging

    public function index()
    {
        /* You can enable debug to see where hATS is looking for its files. */
        tplSet('debug', true);

Most of the problems I have encountered on various servers is to do with file paths. If you have difficulty getting the HE to work, or you have difficulties getting your own Parts to display, you will want to enable hATS debugging in your controller, by adding a line as shown in the HE snippet above.

NOTE: Images (displayed using tplImage() within the .phtml file) will NOT be displayed when debug is enabled as the tplImage() will return lots of debug information instead of just the image path.

Parts & Theme Paths

The HE is not setting a partsPath, therefore the default location of /hAts/parts is used.

Because the inclusion of each Part file is accomplished by using the PHP require directive (allowing PHP within the Part to be executed), the Parts files do not have to be stored in /hAts/parts.

   /* As Parts files are 'Required' they don't need to be in the public web space
    * so you could copy the entire parts folder into your CI Views folder.
    * You would then need to set the parts path to the new location.
    */
    tplSet('partsPath', 'application/views/parts');

The uncommented setting of partsPath above shows an example where the Parts have been relocated into a sub-directory of the CI View folder.

Note: the parts setting (folder name) is automatically appended to partsPath.

You can also set the themePath in a similar way (the default being /hAts/theme), but the themePath must be in a web-accessible location in order for browsers to access the CSS, Image, Javascript and other linked Files used within your Parts.

Note: It only makes sense to set the themePath once for your website (unless you want different themes in different sections). This makes it easier to change the entire theme for your site by simply changing one path setting.

View Files or Layout Files

    // load hATS default layout (View file)
    $this->load->view('hats_default');

Located in the usual CI location of application/views/. The hats_default view file consists of:

hats_default.php
    <?php // alternative format... ?>
    <?php // require tplGetPath('head'); ?>
    <?php tplGetPart('head'); ?>
    <?php tplGetPart('body_open'); ?>
    <?php tplGetPart('body_content'); ?>
    <?php tplGetPart('body_footer'); ?>
    <?php tplGetPart('body_close'); ?>

The commented lines show an alternative method for including Part files, but you'll rarely (if ever) want to use that method, so we will ignore it.

We can see from the hats_default view file that we are simply calling tplGetPart() with the name of the Part file wherever we want it to be displayed. As such, you can think of these View files as layouts when using hATS, because they are simply creating the layout of parts within the View.

You can obviously put other HTML/PHP in these View files, but it doesn't make sense to do so as that other HTML/PHP should now be moved into one of the Part files instead.

You would create additional layout files if, for example, you wanted a 3-column layout, a frameset-layout (see the hats_frameset.php example file), or any other fixed layouts that Part files need to fit within.

Passing Data/Variables to the Parts

Note: You can still pass in a $data array and use it as normal - it is only a View file after all!

You will see in the load→view('hats_default') code above that we are not passing in an array of $data as is normal for CI View files.

Instead, hATS uses its own get, set, and add functions to handle the passing of data to the template Parts.

    // note that we are 'set'ting body content then 'add'ing it. Setting a variable
    // overwrites anything previously stored within it.
    tplSet('bodyContent',  '<h2>This is the [bodyContent]</h2>');
    tplAdd('bodyContent',  '<p>Some content for the hATS example controller.</p>');
 
    // Note: in a Part file, use the following line to display this variable's content...
    // echo tplGet('bodyContent');

Adding Parts to the Page

    // we can add other parts here (no file extension required - .phtml assumed)
    // NOTE: testpart.phtml includes a sub-part named subpart.phtml
    tplAddPart('test/testpart');

By default, hATS will look for Part files with a .phtml extension, therefore we simply pass the name (and sub-path if neccessary) of the part using tplAddPart(). Parts are displayed on the page in the order they are added.

Note: the file extension of Parts files can be changed by setting the hAts_partstype variable:
eg. tplSet('hAts_partstype', 'php'); would tell hATS to look for Parts with a .php extension.

To actually display the Parts being added, you need a call to tplGetParts() somewhere in one of your Parts files. In the hAts_example page, this call is included in the Part named body_content.phtml

body_content.phtml
    <?php
    /* tplGetParts() displays ALL parts that have been added using tplAddPart() function
     * within our Controller. Displayed in same order as added.
     */
    ?>
    <?php tplGetParts(); ?>

Flagging Responses

“Oh! my responses are flagging today, missus! ;-)

[This feature isn't specifically relevant to a Templating system, but it's included because I needed a consistent way to send responses to users.]

hATS includes a function named tplResponse_message( $name, $css ) which generates some HTML to display messages to users. These messages are, by default, either 'success' or 'fail' messages (you can see examples displayed at the top of the hats_example page).

To send messages for display by tplResponse_message, you simply set or add them to the hATS variables named success or fail as used in hats_example.php

hats_example.php
    // flag some responses (note: the hAts default Parts already contains a call to tplResponse_message() in body_open.phtml)
    $this->flagResponse(true, ':-) THIS SUCCESS MESSAGE is from the flagResponse() method.');
 
    tplAdd('success', ':-) THIS IS A SUCCESS MESSAGE - click me to go away, or I\'ll auto fade if jQuery exists!');
    tplAdd('fail',    ':-( THIS IS A FAIL MESSAGE    - click me to go away, or I\'ll auto fade if jQuery exists!');

Note: In the first line of the above code, I am also using a Method (located within the hats_example.php Controller) to make the setting of success/fail messages even easier.

flagResponse() is not part of hATS itself, I just use it to set the appropriate responses - mainly after DB operations that return a true/false result. If no message is passed, it uses default ones I have configured within my CI config.php file.

For the response messages to actually be displayed on screen, you need to include a call to tplResponse_message() somewhere in one of your Part files. In the example page, this is included in body_open

body_open.phtml
    <body>
        <?php tplResponse_message(); ?>

END == NIGH

That's it for this breakdown of the hATS example page. Take a look through the hats_example.php Controller and the hAts_default Part files to see how things work, or post comments if you need any further info.

Comments



E​ B T᠎ B​ P G Y D D Y J U
programming/php/codeigniter/hats/example.txt · Last modified: 14/07/2014 20:45 by harpanet