Blog

Customizing jT CarFramework Pages

Customizing jT CarFramework Pages

INTRODUCTION

jT CarFramework 2 Series was design for the auto dealership and trading industry. Due the implications of requirements of this industry, we set out to build a custom framework which would provide:
- an easy platform to learn (code wise)
- fast to load (due the amount of images required to be loaded at run time)
- open source (no encrypted code)
- which could be installed and used by any user regardless of code experience (such as WordPress)

Following these parameters, we built a framework which doesn’t use a templating system such as Smarty. We focuses in keeping everything in PHP so you won’t be required to learn Smarty just for the sake of building a template which won’t be changed afterwards (companies don’t usually change their business colors and flags). It also saves server process and increases loading time.

We designed the framework to be fast even in shared hosts (although some shared hosts are below avarage quality).

With that said, this tutorial will attempt in guide you through the steps of customizing your installation. Make sure you read the entire tutorial “before” creating new pages!

UNDERSTANDING THE FILE SYSTEM

The framework itself takes care of all processes and helps you to handle forms and other requests by allowing you to use PHP at all times and, by providing you with access to all libraries at all times regardless if you are working on the page code (HTML) or controller (PHP class).

By doing so, you won’t be required to override or extend anything. There is no learning curve.

There are 3 major directories plus, the administrator directory within the installation directory which you need to be aware before starting customization. Understanding the directory structure will automatically allow you to understand how the entire page system works.

The following describes how the directory system is organized:

[root]
[admin] : the administrator interface and handler files.
[app] : 3rd party applications.
[controller] : the public and user page controllers.
[view]
|_ [css] : css files for public and user pages.
|_ [js] : javascript files for public and authenticated user pages.
|_ [page] : public and authenticated user pages.
|_ [3rdparty] : 3rd party framework and plugins (jquery,ckeditor,etc).
|_ [header] : page headers (see About Page Headers section).
[language]
|_ [en] : language files (localization).
[core] : framework core files.
...

UNDERSTANDING GROUPS

jT CarFramework 2 Series provides 4 different groups:
admin (administrator)
public (guest user) |
user (authenticated user)
dealer (authenticated dealer)
Each group is direct associated with the file system to make it easier to locate and modify any functionality to a specific page.

UNDERSTANDING THE PAGE SYSTEM

Each page you see on the front-end is a part of a 5 files group system which we call FFS (five file system).
What that translates to is, each page has 5 basic files:
css file (optional)
javascript file (optional)
language file (optional)
page file (required)
controller (required)
So, as you can see, 2 files out of the 5 described above are required and, the other 3 are optional ( you can create as needed ).
If the optional files are created, they are automatically detected and add too the page’s head tag so, you don’t need to worry about anchors, hooks or, making style declaration on the middle of your page.

How all that comes together?

As mentioned, the FFS is bound by the current user’s authentication group which, it’s also used to help you to easily find a particular file.
Imagine the following situation:
- a user just typed your domain and is accessing your website. Since the user just accessed it, he’s not authenticated. He’s a guest. As a guest, he’s group is automatically assigned to “public”.
The framework will understand that and keep track of the user at all times to improve security. Since the user is assigned to the public group, the following files (from FFS) will be loaded:

root/controller/public.home.php (controller)
root/view/page/public.home.php (the page HTML)
root/view/css/public.home.css (stylesheet)
root/view/js/public.home.js (javascript)
root/language/public.home.php (language)

As you can see, all files are structured in similar way respecting the extension required for each file type. These five files allows you to completly change your home page, with exception to the headers.

ABOUT FILE NAMES

The file name of each FFS file is structured in the following way:

group.page-slug-name.php

As you might have already guessed, if you create a page and name your FFS files public.test-page.xx, you will be able to access that page instantly through the URL http://mysite.com/test-page/

ABOUT PAGE HEADERS

We classify as header the parts of the page which repeats itself in every other page such as the top banner, horizontal navigation menu and page foot.
Like pages, headers also uses the authentication group to define which header to load to each group.
In the example mentioned above, the header root/view/header/public.top-header.php would be loaded.

CREATING NEW PAGES

The easiest way to create a page in which you want to work on is to login into your administrator’s panel, click the “Create new page” tab and, create a page through the interface.
By doing so you will avoid having to create a MySQL query to register the page into the database.
Pages created this way are also made available to be add into the navigation menu.
With that said, let’s begin:

1.step – Create a new page

As described above, login to your administrator’s panel and create a new page. For the sake of simplicity, let’s say you gave the page’s title a name of “Test Page”. Make sure you select “public” under the permission drop-down. The system will create a permanent slug name to it called ”test-page”. Therefore, your page can be accessed through the URL http://yoursite.com/test-page/.

2.step – Prepare files for edition

Reach your root directory and open the following files with your prefered code editor:

- root/controller/public.test-page.php
- root/view/page/public.test-page.php
- root/view/css/public.test-page.css
- root/view/js/public.test-page.js
- root/language/public.test-page.php

As you can see, by using the administrator’s interface, all files are already created for you saving you a bunch of time.
Now, find the HTML comment tag which says:

<!-- content start -->


<!-- content end -->

Add your page’s content within these tags unless you redisigned the entire layout.

HANDLING FORM POST/GET REQUESTS

Supposed you created a form on your page with the following code:

<form method="post">
<input type="text" name="tinput" />
<input type="submit" name="savebtn" value="Submit"/>
</form>

How do you catch the form data? – Simple!

On the controller file, under the constructor method, add the validation:

if( isset($_POST['savebtn']) ){
$this->myHandlerHere();
}

That will give you complete freedom to handle your form in any way you want! Oh, just don’t forget to create your method “myHandlerHere()” else, you going to get an error!

CONSTANTS

There are a couple of constants set to help you include classes as described below:

BASE_RELATIVE : the page’s URL. ie. http://mypage.com/ (notice end slash)
BASE_CLASS  : absolute system path to core classes.
BASE_ROOT  : absolute system path to the root directory.

All constants ends with a slash so, make sure to remember that!

HANDLING PHP ERRORS

jT CarFramework 2 Series has it’s own error log system. As a developer, you know that is not often that we got access to the PHP error log files.
Logs are stored at root/log/ directory and can be viewed through the administrator’s panel.
To add messages to the log file use the following class:

require_once BASE_CLASS . 'class-log.php';
LogReport::write('Your message here.');

CONNECTING TO DATABASE

Use the core class to access the database as follows:

require_once BASE_CLASS . 'class-connect.php';
$cnx = new Connect();
$cnx->open();

From this point on, you can do your mysql queries using mysql_query, mysql_fetch_assoc(), etc. The connection class also provides you the meaning to manually close the connection after a query:

$cnx->close();

QUESTIONS

Don’t hesitate in contacting us for questions, ideas and/or constructive critics.

 

 

 

 

Leave a Comment

Your email address will not be published. Required fields are marked *

     

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>