How TNG builds a page

Process Map v2

Process Map v1

In order to effectively troubleshoot or enhance your site, you need to know how the information gets put on the user's screen. How does the HTML file your visitors looks at get constructed from the PHP file that they select? It's an exceedingly convoluted process, and it's easy to get lost.

Definitions

Some of these definitions are contrived for this article, especially since terms like "module", "package", "program", "category", "style", and "type" are quite ambiguous in English (with overlapping meanings), but we need to use them to refer to objects and concepts in a particular programming context.

Template

To TNG, a template is a set of CSS rules, images, and PHP files that are stored in a called template{nn} (where nn is the number by which the template is identified). All of the templates are stored under a folder called Templates that is just underneath the "main" TNG folder. Most TNG sites use exactly one template at a time. The site administrator can change the template, and the newly selected template is then used exclusively on that site.
By and large, the end-user and admin pages handle template switching just fine.

But for home pages, considerable text is entered into the home page template, and if the template is switched, that text is likely to be unavailable.  The admin can enter text into the new template, but because of differences among the home page components within a template, not all of the text and structures of a home page are transferable to other home pages. This problem can perhaps be understood better by looking at some of the template definitions at Admin >> Setup >> Template Settings.  You can select different templates, and even enter text (and select images) in different templates without switching to another template.

Module

Each PHP file is a "module". PHP files can contain PHP, HTML, and JavaScript code. Different kinds of modules (all with the filename extention .php) contain different types of code, and serve different purposes. TNG PHP Modules can be classified as Programs or Include Files.

Program

A PHP file that is intended to be invoked through a hyperlink, through form submission, or by entering its address into a Web browser address bar. Many programs, of course, require querystring or form parameters, and thus really can't be run when without those parameters.

HTML Document

The HTML code delivered to a web browser by a PHP program or an HTML file. HTML documents produced by PHP programs are temporary; they exist only as they are being transferred from the server to a web browser.

Web Page (or HTML Page)

What the user sees in a web browser as the web browser "renders" an HTML document.

TNG Page

A TNG program that creates an HTML document (and ultimately, a Web page); i.e. not an Action Script nor an AJAX Program.

Action Script

A PHP Program that (in most cases) does not produce output (e.g. generates no HTML code) and would not likely be directly specified in a browser command line. Action Scripts typically are invoked by an HTML form, and write the form's data to a database or text file. An Action Script typically terminates by executing the PHP built-in function header, specifying "Location:" as the first parameter, and a program name as the second

AJAX

A technique used by JavaScript (running within a user's web browser) to call a PHP programs (on a server) whose output will (most likely) be incorporated into the current web page being displayed in the web browser.

JSON

A text format for transferring structured data. You can think of it as a cross between XML and CSV (comma-separated values). It is frequently used to format data requested through Ajax.

Ajax Program

A PHP program that is executed through the JavaScript ajax function, and whose output is intended to be read by the "success" function defined by the JavaScript ajax function. Ajax programs do not use Ajax; they are just used by Ajax. Ajax program are really like any other PHP program, except that their output is not likely to be an entire HTML document, and may not even be HTML. The output of an Ajax Program will often be JSON code or just plain text. In TNG, most Ajax Program filenames begin with "ajx_"

Main (or Mainline) Code

Code that is executed at the same level as the beginning of a program; that is, not within a function. The "Mainline Code" of a "Program" is likely to include code incorporated into the Program through Include files.

Also, Program files, may, of course, contain functions, which are not part of the "Mainline Code".

Extended Program

A PHP program that has been expanded by executing Include statements that incorporate other PHP code into the program.

Include file

A PHP file that is not a Program and is intended to be incorporated into Programs through the PHP include statement. There are three types of Include files (defined below) - Function Libraries, Inline Code, and Mixed Include Files.

Function Library

An include file that consists of PHP function definitions. These functions might be called by the "main" program, or might be called by functions loaded by other include files.

Inline Code

Code that is in an Include file, and not in a function. Inline code is executed the moment it is included, as though it was directly in the file that included the Include file.

Config File

An Inline Code file (i.e. an include file) that consists only of assignment statements and other include statements. Several config files (all of whose base filenames end with 'config') are 'TNG System" files that define TNG system variables (see below).

Mixed Include file

An Include file that contains some inline code, plus some function definitions.

TNG System Variables

Numerous variables that describe the user, the environment, the language to be used, and many other are shared among TNG system function. These are all intended to be available globally, but most of them are not defined in arrays, so when specific TNG system variables are needed by system or custom functions, they must be declared with PHP global statements.

TNG Page Roles =

The three roles that TNG pages take on are: of TNG page are:

1. The site home page, which (assuming that you are using a TNG template) is built from an index.php file in the template folder, along with images and text blocks taken from the TNG template file. There are some common components, but, in general, the TNG home pages in the different templates are completely different from each other.
2. End-user pages; basically, any page that a non-administrator can see. These are built from two template files in the TNG folder, and a content area. The layout of the content area is identical in all templates. The two template files define
   1. The graphics and navigational menus at the top and potentially the left side of the page, and
   2. The graphics and navigational menus at the bottom of the page.
3. Admin pages; basically any page that is accessed through the Admin menus (except for a few that end-users can reach through a different path. All admin pages are displayed in a frameset and have the exact same layout in all templates.

Note that the elements in each type of page that are common to all templates may have the same layout, but they still look different from each other because they use style classes and some graphical borders and icons that are defined by the templates.

Phases to Building a TNG Page =

These phases overlap; they each happen at the same time as PHP code is loaded and executed, but they can be distinguished logically.

Assemble the extended PHP program

• When the "main" program (the PHP file that is in the URL being loaded) is first loaded, it begins to execute. Some of the statements in it are "include" statements, which pull other PHP code into the "extended" PHP program.
• At the beginning of the program numerous systMany included files include other PHP files.
• Some included files consist only of PHP code that is executed the moment it is included.
• Other included files consist only of PHP functions that are called from the "main" program or other included files.
• Finally, other included files contain PHP code that is executed the moment it is included, plus PHP functions.

See PHP Include Structure below for maps of how extended programs are built for end-user, admin, and home pages.

Execute Structural Functions

To a large degree, TNG system functions are responsible for the structure of the page, and the distinguishing characteristics of each template. This is particularly true of TNG functions that begin with the letters "tng". These TNG system functions are placed strategically in essentially all

Execute Custom Code

By "Custom Code", I mean the PHP, HTML, and Javascript code that is unique to a particular program (as opposed to the code that produces the template-based page layout components. This custom code generates output for the "content area" of the web page.

Let's try to map this out. For the text based folk among us, here's the list of files and the order in which they are called.

In TNGv11, admin programs create the extended PHP programs like this:

1. include begin.php
   1. Check for some querystring parameters that cause the process to die
   2. include processvars.php to define all $_GET[] and $_POST parameters as variables
   3. include subroot.php to define the error/warning state and define $subroot, which is the path the config files folder
   4. include tgconnect.php, which is a function library. Including it does not execute any code.
   5. include config.php, the main configuration file
   6. include templateconfig.php, which loads the all of the home page template strings for all templates. (This seems distinctly unnecessary)
   7. define the TNG system variable that contains the path to the selected template folder.
   8. set a couple of cookies related to the site version
   9. include siteversion.php, which is just a function; no code is executed
   10. call the function in siteversion.php to determine the device type based on the browser ID stored in a PHP system variable.
   11. call session_start to initialize (or re-initialize) the PHP session.
   12. move a couple of session variables to TNG system variables.
   13. include getlang.php, which determines the language that has been set for this user or this site.
   14. define 3 more TNG system variables.
2. include adminlib.php
   1. include pwdlib.php
   2. include globallib.php - a set of PHP functions used by admin and end-user programs.
   3. include mediatypes.php
   4. include tngfiletypes.pohp
   5. adminlib also contains numerous PHP functions that are available only to admin programs.
3. getlang.php (again?!?)
4. include Languages/{language}/text.php
   1. Defines zillions of $text[] variables
   2. include alltext.php
      1. define $date[] variables plus some $text[] and $admtext[] variables
      2. include cust_text.php
5. include checklogin.php, which determines whether the user is logged in
6. include version.php, which sets some system variables related to the TNG version and its release date

that determines TNG                      begin.php: define $subroot
                    begin.php: include templateconfig.php
                    begin.php: define siteversion.php
                    begin.php: define the language and the characterest
                    begin.php: include getlang.php

            begin.php (see above)

Admin programs: include adminlib.php (instead of genlib.php)

            adminlib.php: include pwdlib.php
            adminlib.php: include globallib.php
            adminlib.php: include mediatypes.php
            adminlib.php: include tngfiletypes.php
            adminlib.php: define numerous functions available only to admin programs

Admin programs: include getlang.php (again?!?) Admin programs: include $mylanguage/text.php

            admintext.php: define $admtext strings
            admintext.php: include alltext.php
                    alltext.php: (see above)

Admin programs: include checklogin.php Admin programs: include version.php

Starting with ANY main php file on your site - any "menu item" link:

1. begin.php
   1. subroot.php
   2. config.php
      1. customconfig.php
   3. templateconfig.php
2. [optional files depending (mapconfig, cmsevents, etc.)]
3. genlib.php
4. getlang.php
5. text.php
6. connect to database - nothing in the previous files can refer to things in the database, because it has not yet been connected, errors will result
7. checklogin.php
8. [log.php, personlib.php, functions.php]
9. [variables and scripts for this file]
   note that up to this point, only variables have been created, the web page has not yet been started
   
10. tng_header
    1. create doctype and xmlns lines - this is the beginning of the actual web page
    2. <head>
    3. title, keywords, description, scripts
    4. css files
    5. $custommeta => load your custom meta file as defined in Admin Setup
    6. </head>
    7. $customheader => load your custom header file as defined in Admin Setup
    8. <body>
    9. tng_icons (the three button menu that you put on left or right)
11. [stuff in the file]
12. tng_coreicons (links enabled in Admin Setup - home/login/search/print/bookmark)
13. [stuff in the file]
14. tng_footer
    1. $customfooter => load your custom footer file as defined in Admin Setup
    2. load some scripts
    3. end.php
       1. </body>
       2. </html>

tng_header, tng_icons, tng_coreicons, and tng_footer are all functions defined in the file genlib.php

Some of the information on how TNG builds a page can be found in the Genlib Functions article.