The Zibings Development Team has been working pretty hard on the ZibTech sites recently, which all use the Zibings Site Framework (v1.3.3). Through their work, I've been told that there is a pretty serious need for some standardization for the way we work with the ZSF system. It was something on our agenda for ZSF 2, but there's no time like the present to start shoring up holes in our process I always say!
The following blog post will be a bit involved and requires you to have a good working knowledge of the ZSF system, but for those who do it should be a good help for defining the best methods of using each part of the system. Off we go..
DefinitionsZSF - Zibings Site Framework
TPL - Template
User Space - Code done inside of the usr.cnf files
Page Space - Code done elsewhere, but not inside the TPLs
TPL Space - Code done inside the TPLs
User SpaceThe
User Space (or usr.cnf files) is where your backend work should be done. As much database work as possible should be handled through function/method calls created inside this area of the code. This helps centralize where you have to go should you be having database problems of any kind. Should there be anything you want to be available to the entire of the system, this is also where it should be done.
Because of the way that ZSF is constructed, the User Space code is called up pretty quickly upon system initialization. The system will call every single usr.cnf file in the current scope, regardless of which module is actually being loaded.
Current Scope is defined by which section of ZSF 1 your user is currently viewing. There are two possible scopes, the first being global when anyone views the main index.php and modules through it. The second scope is admin scope, obviously when a priviledged user views the system modules through admin/index.php. Global scope will only pull all top-level usr.cnf files into the system at initialization, whereas the admin scope will load all top-level usr.cnf files
as well as all admin-level usr.cnf files. This is an important thing to note as it can cause problems in your admin scope if you use redundant code in your admin-level and top-level usr.cnf files.
The best way to view the User Space is to pretend that it is where you create an API for the rest of your spaces. Try keeping as true to that as possible and you will get the most (and best) use of the User Space as ZSF can offer in its current state (v1.3.3 at time of writing).
Page SpaceThe
Page Space is easily described as the rest of the code excepting our TPL files. In order to use the system effectively however, there are certain things that you should ensure do
not find their way into your Page Space.
The Page Space is meant to be used as the intermediary between our User Space 'API' and the TPL files. Page Space should control which TPL files are being used/displayed, and provide them with information to help in their displaying of information. As I mentioned above, the User Space should take care of the majority of all database calls, if not all database calls. This makes it so that the Page Space does nothing but use the functions/methods offered by the User Space to do things such as validate user input and send that input to the database.
Even so, because the Page Space has to control the templates, often times the Page Space will end up much more expansive and confusing than the User Space. It is good (and suggested) that you seperate different page controls into different files which branch off from the modules' main index.php file. For example, lets pretend we have 3 pages to a module: Home, Page1 and Page2. The following would be a generally accepted file structure for the module directory:
myModule
myModule/index.php
myModule/inc/page1.inc.php
myModule/inc/page2.inc.php
All of the data handling for the 'Home' page is done inside of the index.php file. If the index.php file finds that it is dealing with either Page1 or Page2, it calls the appropriate .inc.php file and exits so that the .inc.php file can do everything for itself in regards to that specific page.
Remember that the Page Space, unlike the User Space, is only available when that particular module is being called, so if you need something to be available globally, it must go into the User Space, not the Page Space.
TPL SpaceThe final section, the
TPL Space, is meant to be only for displaying data provided by the Page Space. Though the TPL system is really just a fancy way of doing PHP inside of a somewhat scope-limited file, the effect is just as good as any high-end high-overhead system out there, such as Smarty. The difference between our TPL Engine and that of Smarty's, is that ours requires us to use a bit of due diligence to ensure that the TPL Engine is used properly.
Your template should never have any kind of functionality thrown into it beyond a rare instance of seperating pages off of a variable-based token. The best thing to ask yourself when coding a TPL file is: "Does this really need to be done in order for my information to be displayed?" If you ask this question and are honest with yourself, you will end up with TPL files with little more than variable access and an occassional conditional loop inside of them. That is the desired makeup of the TPL Space, nothing but the work we do in order to display the data provided by the other two spaces.
ReviewLet's go over this in review, just quickly.
The
User Space is meant for globally accessed code API's which do things such as data validation and database interaction.
The
Page Space is meant for module-specific code and is the bridge between the User Space and the TPL Space. This space provides all information from the User Space to the TPL Space so that it can be used there.
The
TPL Space is meant to simply display the data provided from the Page Space (and ultimately the User Space). There should be very little code in this space.
I hope that this has helped
someone out there. Any questions, as usual, can be commented here or over at
STH, I troll both places on a regular basis.
- Andy
Labels: Development