Innovative Computer Solutions,
Development & Technical Support

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

User Tools

Site Tools


programming:php:codeigniter:hats:theme_and_parts

hArpanet Template System (hATS) for CodeIgniter

v2.1.1

hATS PARTS & THEME REQUIREMENTS

Just to recap from the previous section…

hATS (by default) expects the following paths for certain files depending on the function called.

Only the /theme path can be changed, the others are hard-coded. eg. the tplStylesheet() function expects the stylesheet to be found in the css folder of the current theme.

  1. /hAts/theme folder in your webroot (this path can be changed in your controller)
  2. /hAts/theme/[theme_name]/css folder – contains theme specific css files
  3. /hAts/theme/[theme_name]/img folder – contains theme specific images
  4. /hAts/theme/[theme_name]/js folder – contains theme specific javascript files
  5. /hAts/parts folder - contains all view parts (small blocks of pHTML) (this path can be changed in your controller)

CREATING YOUR OWN THEME

I'm not going to go into much details about the theme, I'll leave that up to your imagination and creativity. What we will do here though is create an additional theme based upon the hAts_Default one.

Create the ORANGE THEME

Step 1: is to simply copy the hAts_default theme located in /hAts/theme/

Step 2: rename the copied folder to: /hAts/theme/orange

Now we have a duplicate of hAts_default named orange.

Step 3: Make a change to the new orange css file located in /hAts/theme/orange/css/style.css

Within the CSS file, find the following style:

#main_wrapper {
  margin-left: auto;
  margin-right: auto;
  background-color: white;
  padding: 20px;
}

… and change the background colour to orange:

#main_wrapper {
  margin-left: auto;
  margin-right: auto;
  background-color: orange;
  padding: 20px;
}

Changing the Controller

As well as creating your new theme, you also need to tell your Controllers to use it. For these tests, we are simply going to modify the hats_example controller in /application/controllers/hats_example.php

Open the controller and look for the _construct() method at the top. Now insert the following Method below it:

      public function orange() {
        tplSet('theme', 'orange');
 
        $this->index();
    }

The file should now look something like…

  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)));
    }
 
 
    public function orange() {
        tplSet('theme', 'orange');
 
        $this->index();
    }
 
    public function index()
    {
      etc...

Voila! You have now created a new Theme and told your Controller to use it. To test it, browse to http://myserver.net/hats_example/orange

Have a go yourself - try and create a Black theme similar to the orange one above. When you're feeling creative you can start building your christmas theme then insert appropriate images, javascript or CSS changes as required :-)

You may also wish to keep the hAts_default folder and simply make a copy of it each time you want to create a new theme from the original.

CREATING YOUR OWN PARTS

Parts (or partials) files are small chunks of pHTML (HTML with or without PHP code), that get included in a parent part or are included by the main layout file (e.g. hats_default.php).

Part files can either be bolted together in a Controller/Method or added from another part file:

From a Controller/Method

• Use the tplAddPart('partName') helper function to add a part name to the list of parts to be output.

• Note that the partName specified is the filename minus the .phpextension. i.e. the part named 'welcome.php' would be included using tplAddPart('welcome').

• Then, in any part file, use tplGetParts(); to output all parts added by the Controller:

    <?php
      /* tplGetParts() displays all 'parts' that have been added using tplAddPart() function
       * within our controller. Displayed in same order as added.
       */
    ?>
    <?php tplGetParts(); ?>

From within another part

• If you prefer to leave control over which parts are loaded to the View Parts themselves, you can load one Part file from within another Part file. NOTE: This is precicely what the hats_default layout file does (see below)!

• Simply place a tplGetPart() call within a Part file:

    <?php
      /* by specifying the name of a 'part' directly in the tplGetPart function call,
       * we do not need to have used the tplAddPart() function in our controller first.
       * The part is assumed to reside in the current theme layout folder, but a
       * sub-folder can be specified in the call, eg. tplGetPart('addRecord/formAdd')
       */
    ?>
    <?php tplGetPart('someOtherStuff'); ?>
    <?php tplGetPart('subFolder/evenMoreStuff'); ?>

CONSTRUCT YOUR OWN PARTS

The best way to begin constructing your own Parts, and to ensure your own parts files are not overwritten when hATS is upgraded, is to make a copy of the hAts_default folder and rename it to something relevant to the parts it contains.

The PARTS folder

/hAts/parts/hAts_default

Renaming this folder depends on how you want hATS to handle your Part files.

  1. Using the Class Name

    In the hAts_example Controller, the following line is commented out in the __constructor:

      tplSet('parts', strtolower(get_class($this)));

    If you uncomment the above line, the name of the Parts folders will be set automatically based on the name of the Class (Controller) from which they are used.

    In the hAts_example Controller, you would need to rename your hAts_default folder to hats_example in order for hATS to find the correct Parts.

  2. Using your own Naming Convention

    You are free to use any naming convention (or randomness) that suits you. It is highly recommended that you use a structure that bares some resemblance to the Controller it relates to.

    eg. If we are building a Log_in Controller and associated parts, it is recommended you create a Parts folder like login.

    Then, in your Method that handles display of the user login page, say login_page() you set the Parts folder as:

      tplSet('parts', 'login');

    However, if you wanted different pages for User logins and Admin logins, you could create the following folder structure:

    /hAts/parts/login/
    /hAts/parts/login/admin
    /hAts/parts/login/user
    /hAts/parts/login/reminder

    I've also thrown in a reminder folder for good measure. Now, in each of your Log_in Controller Methods, you would set the appropriate Parts path…

    admin_login()

      tplSet('parts', 'login/admin');

    user_login()

      tplSet('parts', 'login/user');

    pw_reminder()

      tplSet('parts', 'login/reminder');

Parts Traversal

If you have specified a Parts folder, say tplSet('parts', 'login/admin'); then hATS initially looks in the specified path for its Parts files.

If hATS doesn't find the file, it traverses the folder path (ie. looks in the parent folder, grandparent folder, etc.) until it finds the specified Parts file.

So, the following code…

tplSet('parts', 'login/admin');
tplAddPart('body_content');
  • would cause hATS to try and use the file /hAts/parts/login/admin/body_content.phtml
  • If that file did not exist, hATS would next look for /hAts/parts/login/body_content.phtml and so on.

Using override files in this way allows you to only duplicate files when specific changes are required for a particular Controller.

In the Log_in example Methods above, we could instead decide that /hAts/parts/login will have all the Parts necessary to create the login page structure and show the user_login() page (in which case we would dispose of /hAts/parts/login/user entirely).

Then, for the admin_login() page we simply copy /hAts/parts/login/body_content.phtml into /hAts/parts/login/admin/body_content.phtml and make the necessary text/style changes. hATS will automatically find the other Parts for the page (eg. head.phtml, body_open.phtml, etc.) by traversing the parent folders.

(If hATS fails to find a part by the time it reaches the root folder / then a warning will be shown where the part should have been displayed.)

PARTS RECOMMENDATION

Because of the automatic traversal/override of Parts, you should:

  • Copy all .phtml files from /hAts/parts/hAts_default and place them in /hAts/parts

This will ensure that hATS always has a fallback Parts file to find if one doesn't exist in a more specific child folder.

LAYOUT FILES

Default hATS Template Layout

Example file, named /application/views/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'); ?>

This file (and any others created by the application developer) is the true 'layout' controller. It controls the structure of the main parts of the template system. All other files within the /hAts/theme folder can be considered as just template parts. A part is a block of pHTML to be included into a parent part until traversal brings us to the top level file, hats_default.php

From the above code, you can see that a 'layout' file simply contains various tplGetPart() calls specifying the order in which Parts are included. (You can also see a comment in regard to an 'alternate' way of including Part files - using the PHP require directive, but it is highly unlikely that you will need to use this alternative method. The difference being that require runs any PHP code within the included file.)

The layout filename is not fixed, and is specified in the controller method as the name of the CI 'view' being loaded. E.g.

  // show the page
  $this->load->view( "hats_default" );

It is possible to have different 'layout' controllers (it is simply a CI View file), but using the generic one from hATS should give you the granularity required. (Or, you may choose to split 'head' into 'head_open' and 'head_close' parts, or any other combinations.)

The names of the parts specified (i.e. body_open, etc.) can also be named as required and are not fixed to those used initially by hATS.

The intention is to create a layout structure controlled by the application developers, while giving interface designers control over the content of these sections through modification of the theme files.

The benefit of multiple parts over a single part containing all content becomes apparent when 'overrides' are used. If this main layout (hats_default above) only comprised of one part instead of five, that entire part would need to be duplicated in each theme child folder that needed specific content within it. By having multiple parts, the amount of duplication is reduced.

Note: Although this layout (hats_default) is defined by the application developer it cannot be enforced as the content of the parts themselves are created by the interface designer, who could if desired not follow the intended structure at all, but instead create parts as they wish. Eg. The interface designer could put all their HTML into the part named 'head' and leave all the other parts empty. (If you needed to enforce parts being used for their intended purpose, you would need to create additional code to parse the parts – e.g. parse the 'head' part for the presence of the <head> tag, the 'body_open' part for presence of the <body> tag, etc.)

That's It!

Hopefully that covers all aspects of hATS. Good luck with it, I hope it proves useful to you and saves you some time or effort. Comments always welcome.

Comments



I I G D T R J​ X O L X​ S
programming/php/codeigniter/hats/theme_and_parts.txt · Last modified: 14/07/2014 20:47 by harpanet