Templates

Overview

By its very nature, LogiCreate uses templates to render your look and feel for your site. Templates are normally broken up into what we call "header" and "footer" files. This is an industry standard convention when dealing with dynamic web sites. LogiCreate sites can use the pre-template processor to determine which templates should be used at run-time. By default, templates are stored in your document root and have the following file structure: 
	document-root/
		templates/
			default  (name of the template)
				images/   (stored images specific to this template)
				header.html.php   
				footer.html.php
				site.css          (style sheets for this template)
			mytemplate  (name of the template)
				images/   (stored images specific to this template)
				header.html.php   
				footer.html.php
				site.css          (style sheets for this template)
When we think of a HTML page we normally think of it in three sections:

  • Header - the top portion of the site which usually contains logos and some navigation
  • Content Area - the actual section where content for your page is rendered
  • Footer - the closing portion of the site, copyright information, etc
These three different sections when combined make up an entire page. In the LogiCreate system the "content" section can be made of up information from a module, HTML, database, etc. The header and footer simply surrond the content to provide navigation and a consistent look and feel.

Creating your template

Let's take a look at a very simple file which we want to split up to create our header and footer.

    <!-- START OF OUR HEADER -->
    <html>
        <head>
            <title>My Home Page</title>
        </head>

        <body>
        <table width="700">
            <tr>
                <td valign="top" width="150">
                    <table cellspacing="0" border="0" cellpadding="0" cellspacing="0" width="150">
                        <tr><td width="100%">
                            <table cellspacing="1" width="100%">
                                <tr><td width="100%"  class="menu_text" nowrap>
                                <? while ( list($k,$m) = @each($obj->menu) ) print $m->toHTML();?>
                                </td></tr>
                            </table>
                        </td></tr>
                    </table>

                </td>
                <td width="10">&nbsp;</td>
                <td valign="top" align="left">
    <!-- END OF OUR HEADER -->
    
    <!-- THIS IS OUR CONTENT AREA -->
                
                
                This is our content


    <!-- END CONTENT AREA -->

    <!-- START OF FOOTER -->

                </td>
            </tr>
        </table>
        </body>
    </html>
    <!-- END OF FOOTER -->

Saving your files

To use the example above, we need to save the header and the footer sections to the templates directory. If your web server document root is /www/htdocs/, the templates folder would be /www/htdocs/templates/. In the template directory, create a folder called "mytemplate". Next, create a folder called "images" in the "mytemplate" folder. The directory structure should look something like this: 
	/www/htdocs/templates/
					mytemplate/
							images/
Using our sample HTML page as as example from above, figure out where your header and footer sections are and save these sections in the folder "mytemplate" or whatever the name of the folder you created. Save these files as: header.html.php and footer.html.php (names are exact and should not be changed).

Next, copy any images that are specific to your header and footer files to the images directory in "mytemplate". Be sure your image files are readable by the web server. If you are using stylesheets with your template, copy the style sheets file to the "mytemplate" directory. All files related to this template should now be stored in one directory including images and style sheets.

Edit your Image Paths

Any images which are referenced in your header.html.php and footer.html.php files need to have the img src tags re-written so the system knows where to look for these images. The constant: TEMPLATE_URL is used to designate where the template resides.

Incorrect:

< img alt src="images/FiltrationLogo.jpg" border="0">

Correct:

< img alt src="<?=TEMPLATE_URL?>images/FiltrationLogo.jpg" border="0">

Switching your Template in LogiCreate

LogiCreate uses a system pre-template function to call your template. This function allows a developer to change the template at runtime based on certain conditions as well as change the style sheets at runtime. If you are planning on upgrading your LogiCreate Application Server with future releases you will want to skip to the recommended section below. If you are not planning on upgrading then use the quick change section below.

Quick Change

Edit the file: lib/LC_include.php

Find the lcSystem object and change the following line:

var $templateStyle = 'default';
to
var $templateStyle = 'mytemplate' //(or the name of your template directory)

The above change will make your new template "mytemplate" the default template which will be processed at runtime. Note: If you upgrade to a newer version of LogiCreate in the future, this change will get overwritten.

Recommended Change

As stated above, we can make a quick change to LC_include.php so our new template is the default template or we can make a change to the systemPreTemplate function so upgrades to our LogiCreate Application Server will require minimal effort. To do this, create a file in your /lib directory called "changes.php". This file will hold any custom changes which are made to the core libraries. In order to allow us to easily upgrade our LogiCreate site from version to version, we are going to replace the systemPreTemplate() function in the lib/LC_include.php with a new one in changes.php. The file lib/changes.php is reserved for LogiCreate Developers who need to make changes to the core libraries in LogiCreate. To get started open lib/LC_include.php and find the class lcSystem, there you will find the function systemPreTemplate(&$obj,&$t). Copy the entire lcSystem class to the new file changes.php and modify the function so it resemebles the following.

<?
function systemPreTemplate(&$obj,&$t){
    
    $t['cssFile'] = 'site.css';  //name of your default stylesheet file
    $obj->templateStyle = 'newFolderName';    // name of your template folder ex. "mytemplate"

    define(TEMPLATE_PATH,TEMPLATE_PATH_PARTIAL.$obj->templateStyle."/");
    define(TEMPLATE_URL,TEMPLATE_URL_PARTIAL.$obj->templateStyle."/");
    define(CSS_FILE,TEMPLATE_URL_PARTIAL.$obj->templateStyle."/".$obj->cssFile);
    include(INSTALLED_SERVICE_PATH."menu/menuObj.php");
    $obj->user = lcUser::getCurrentUser();
    $obj->menu = menuObj::getVisibleCached($obj->user->groups);
}
?>

After you have changed /lib/changes.php, comment out the lcSystem class in lib/LC_include.php. To do this wrap the entire class definition in /* */ comment tags. Now that we have our newly modified class in lib/changes.php we will be able to easily tell what code changes we have made over time. During the next upgrade we simply need to comment out the functions and classes listed in lib/changes.php so they are not duplicated.

The last change we need to do is put the following line at the top of LC_include.php

include(LIB_PATH.'changes.php'); // place in LC_include.php

Choosing your opening Page

Depending on your site design, you may want to have your opening home page open to different modules or static pages. To change your site so it opens up to the module or page you want, edit the "defines.php" file in your document root folder (ex. /www/htdocs/defines.php). In the defines.php file find the following line "define(DEFAULT_SERVICE,"welcome");". As you see by default your site opens to the "welcome" module. Change this to your needs. Here are a few examples:

  • define(DEFAULT_SERVICE,"html/main/welcome.html"); - Sets you opening page to the welcome.html file in the HTML Module.
  • define(DEFAULT_SERVICE,"welcome/news"); - Uses the built in service "news.lcp" which includes the welcome.html file and news on your home page.

Inserting the Menu(s)

In order to take advantage of the Menu Module, we need to place some LogiCreate code into our header.html.php file in our templates directory. Find the specific place you would like your menu to appear in your header file and place the following code in the file:

<? while ( list($k,$m) = @each($obj->menu)) print $m->toHTML();?>

Merging Stylesheets

Out-of-the-box your LogiCreate system applications take advantage of stylesheets so your site colors can be applied to these applications. It is recommended that you use an existing stylesheet which ships with your LogiCreate system for your site. A standard stylesheet you can use to incorporate into your header can be found in templates/logic/site.css. Either copy this file to your new templates directory or merge this stylesheet with your existing stylesheet.

Incorporating a Site-wide Search Box

If you wish to incorporate a search box in your template use the following code as an example:

<form method="POST" action="<?=APP_URL?>search/">
<input type="text" size="15" name="q" value="Search our site" onfocus="this.value='';" >
<input type="submit" name="Search">
<input type="hidden" name="event" value="search">
</form>

Switching the Template

There are times depending on certain scenarios where you may want to switch templates at runtime. An example would be if you want to have one template for users when they are not logged in, and another when they are logged in. Or, maybe there is one particular event in the system that requires a different look and feel to render properly. Depending on your overall goal there are different ways to accomplish this. Here are two examples that may assist you in doing this.

Example of switching template at runtime

Switching the template at runtime involves modifying the event you wish to switch the template in. Observe the following code as an example:

<?
    function Run(&$db, &$u, &$arg, &$t) {    
        $date = date(F);

        if ($date == 'December'){
        $arg->templateStyle = 'christmas';    // switch to christmas template during december
        } else 
            {
                $arg->templateStyle = 'mytemplate';    // switch template to default
            }

    }
?>

Switching templates based on groups

Another example is to switch the templates based on groups a user belongs to. Since we want this to happen in every module and every event in the system, we need to do this higher up in the system. Although this could be done in several places, remember that if we modify the core libraries we run the risk of having our changes overwritten. In an above section we created a /lib/changes.php file and modified the systemPreTemplate() function. This would be a good place to put additional logic to switch the template based on groups or other things. Observe the following example:

<?

function systemPreTemplate(&$obj,&$t){

        $obj->user = lcUser::getCurrentUser();
        $obj->menu = menuObj::getVisibleCached($obj->user->groups);
            
        if (in_array('reg', $obj->user->groups))
            {
                $obj->templateStyle = 'coolTemplate';  // for registered users only
            } else
                {
                    $obj->templateStyle = 'default';   // default template
                }
                
        define(TEMPLATE_PATH,TEMPLATE_PATH_PARTIAL.$obj->templateStyle."/");
        define(TEMPLATE_URL,TEMPLATE_URL_PARTIAL.$obj->templateStyle."/");
        define(CSS_FILE,TEMPLATE_URL_PARTIAL.$obj->templateStyle."/".$obj->cssFile);
        include(INSTALLED_SERVICE_PATH."menu/menuObj.php");
}

?>

The above code will check to see if a user is logged into the site and switch the template to a template called "coolTemplate". Just to be perfectly clear, the name "clearTemplate" is the name of the folder in the templates directory. Although we didn't show it in our example above, we could have just as easily switched to a different set of stylesheets by using the following variable: $t['cssFile'] = 'site.css';.

Inserting Banners into your Templates

The banner module is a useful module when combined with the e-commerce module to display different banner ads on your site. Similar to including the menu as we did above, to include the banner we simply need to add one line to our header.html.php file or footer.html.php file in the appropiate template. The line is as follows:

Advert::getBannerLink(1,$obj->user->groups);

The first option in this function is the banner placement. You can create different banners to place in different portions of your site. For example, you can have a standard banner at the top of your site and a different collection of banners ads a different size at the bottom. Another example:

Advert::getBannerLink(2,$obj->user->groups);

The second option is an array of groups the banner application uses to figure out which banners a user is able to view.

Creating Dynamic Templates

Dynamic templates is a term which simply means display data in a template based on certain conditions. Since these conditions can be different based on a particular user's group, username, or whatever we call these "Dynamic Templates". Let's take the following scenario and apply it to a template.

Scenario One: Display a login form in the template if a user is not logged in. If they are logged in, show their username.

<?
 if($obj->user->username == "anonymous") 
    { // if user is anonymous it means they are not logged in, display login form?>

    Thank you for visiting the LogiCreate Demo site.  If you wish to check the demo, either <b><a href="<?=APP_URL?>login">login</a></b> below or <b><a href="<?=APP_URL?>login/register">register</a></b>. <hr>
        <form method="post" action="<?=APP_URL?>login">
        <input type="text" name="username" size="15" maxlength="15"><br>
        <input type="password" name="password" size="15" maxlength="15"><br>
        Remember this login? <input type="checkbox" name="permanent" value="yes"> Yes<br>
        <input type="submit" value="Login"><br>
        <input type="hidden" name="event" value="login">
        </form>
<? } 
    else { // user is logged in, display search box and addition links ?>
    
        Welcome:<br>
        Logged in as: <b><?=$obj->user->username;?></b><br>
        Logout: <a class="rightnav" href="<?=APP_URL?>login/out">Click Here</a>
            <hr>
        Thank you for visiting the LogiCreate Demo site.  Try out the powerful <a class="rightnav" href="<?=BASE_URL?>herc/">Hercules Control Center</a> to see how easy it is to make changes to this site.
            <hr>
            <b>Member Links:</b><br>
            <a class="rightnav" href="<?=BASE_URL?>herc/">Control Center</a><br>
            <a class="rightnav" href="<?=APP_URL?>forum">Member Forums</a><br>
            <a class="rightnav" href="<?=APP_URL?>filemgt">Briefcase</a>
            <form method="POST" action="<?=APP_URL?>search/">
            <input type="text" size="12" name="q" value="Search the site" onfocus="this.value='';"> <input type="submit" value="go"><br>
            <input type="hidden" name="event" value="search">
            </form>

        <? } ?>

The above code was taken from the templates/logic/footer.html.php file. It displays a login form if a user is not logged in and displays additional links and a search form if a user is logged in. To see the above code in action, switch your template to "logic" to called the LogiCreate Demo code.

Scenario Two: Links based on permissions.

To create links in your templates based on permissions we will use some of the same logic from above. To display a link to the Hercules Control Center for users in the group "admin" we would do the following.

<?

if (in_array("admin", $obj->user->groups)) { ?> <a href="http://oursite.com/herc/">Hercules Control Center</a> <? } ?>

?>

We are sure you will come up with different scenarios and find new and interesting ways to use Dynamic Templates.