Creating A New Page - Global Vs Template Files Explained

THL Toolbox > Developers' Zone > Web Development > Creating A New Page - Global Vs Template Files Explained

Creating A New Page - Global Vs Template Files Explained

This section discusses how to make a new page, in the generic THL site design, and in the process illuminates much of what you need to know about the separation of content from design and interface elements for the new site.

If you haven't accomplished everything outlined in the previous steps, please do not waste your time trying to skip ahead here, unless you are just reading ahead while waiting for your subversion account to be activated or something.

This section of the Production Manual is self-contained on this one page - with one Exception near the end. I would print this page (and the one Exception) if I were you, to refer to as you look around the site directory tree as per the instructions below.

Here's a quick Table of Contents:

  • Where to Put a New Page
  • Making Your "testing-area" Directory
  • Using a Template File to Make Your New Page
  • The Anatomy of Your New Page, Part 1: Php Include Syntax
  • An Introduction to Global Files
  • How Specific Global Elements get Called from Templates, or, "Where is that CSS Coming From Anyway?"
  • The Anatomy of Your New Page, Part 2: Top to Bottom
  • Your First Words
  • Finally…

Where to Put a New Page

A conceptual issue here first. This may or may not seem obvious, but it is very easy to start making new content in the wrong place. When you actually get into building real content, you should first and foremost be sure that the Project Director, or whoever directly manages development of the content in your area, knows what it is your are going to build, and where (in terms of site interface and directory or wiki structure) you will be building it.

For now we will proceed with this exercise by using your own "testing-area" directory, which you will now create.

Making Your "testing-area" Directory

In the thdl-quandu repository, which you now have checked out to your local hard drive, you will find a directory called /www/testing-area/. You will see existing directories in there with co-workers' names, "than", "mark" etc. Inside that directory on your local:

  1. Create a folder.
  2. Name it using your name (tashi, frank, whatever).
  3. Add and commit it to the repository.
  4. Deploy it to staging.
  5. Go check the url via web to be sure it is there (e.g. external link: http://staging.thdl.org/testing-area/tashi/)

Using a Template File to Make Your New Page

Now open up /www/template/ and look at the files listed there. These are the templates from which all THL standard web pages are stamped. As you can see from the filenames, you have a choice to make your new page with the 3 column design (example: external link: http://staging.thdl.org/tools/); the 2 column design (example: ); or the 1 column or full width design (example: external link: http://staging.thdl.org/encyclopedias/art/contemporary/ - altho note that this page has been modified to replace standard THL banner, navbar and footer). You can ignore the wiki.php and side-colum.php files in there for the present.

As of this writing, some elements within pages using the 3 column template seem to be in flux, and typically most content pages you'll make within an existing section will be of the 2 column variety. Plus the utility of the 3 column file for our training purpose here is not much greater than the 2 column. So for this purpose let's copy /www/template/index-2column.php into your testing-area directory. (If the Subversion User Guide did not stress this sufficiently, you should never actually *move a file from one directory to another; and definitely never ever copy, move or edit one of the .svn folders or its contents.)

  1. Make a copy of the index-2column.php file, and put it into your test directory.
  2. Name the file "newpage.php".
  3. Add and commit it to the repository.
  4. Deploy it to staging.
  5. Go check the page via web to be sure it is there.

The Anatomy of Your New Page, Part 1: Php Include Syntax

As you have no doubt realized, your new file is a php file. Open it up using one of the several good code editing tools you hopefully installed earlier, and take a good look at the code. You will see several php includes, like this one that calls the "header" for the file:

<? include_once  "$droot/global/php/header.php" ; ?>


These php includes are one of the main tools we used to "templatize" the new site. If that header.php file is changed, the change will instantly be reflected in every page on our site that "includes" that header file (virtually all of them do). Beats editing every file on the site, no?

Let's look at every bit of that syntax, before we go on to explain the various different includes used on every template page:

  • The "<?" and "?>" are there to enclose the include call.
  • The "include_once" statement includes and evaluates the specified file (here, that would be /global/php/header.php) during the rendering of the page. "include_once", vs "include", means that if the code from a file has already been included, it will not be included again, used just as a sort of safety measure.
  • "$droot" is the server environment variable; it allows whichever web server is delivering it, be it staging.thdl.org, www.thdl.org, or even your localhost, to regard that server's docroot (the starting point of absolute url paths, like /reference/index.php, as set in whichever web server's httpd.conf) as the docroot to use. The "$droot" variable is set at the very top of the file, where you probably already noticed it: <? $droot = $_SERVER['DOCUMENT_ROOT']; ?> (you'll very likely never need to mess with that code).
  • Finally, there is the path to the included resource: /global/php/header.php. We'll talk about that "global" directory in detail now.

An Introduction to Global Files

The /www/global/ directory in the repository contains files that are used throughout the thdl.org site. Thus this is a very sensitive area - errors introduced to some of these files could bring down the entire site, if such were to be deployed to the production server. The following is for the purpose of demonstrating how the site uses and depends on the global files, not to show you how to edit them. You should never touch the files in /www/global/ unless you really really know what you are about.

The global files were created to separate out code that is used repeatedly across the site. They can be, and are being, tampered with indefinitely, without any need for adjusting the files that have been made from templates and strewn across the whole site. On the other side we have the three template index.php files, which contain only the most basic, unvarying code before the content gets poured into them. This approach let us leap into development of the site using the templates long before the design and interface issues controlled in the global files were settled. As of this writing they are in fact still far from settled, but as the templates just include all that code, we don't have to go back and change an ever-increasing number of files to reflect the latest menu search box scheme.

What is Global, What is Not?

To quote from the File Naming and Storage Conventions for THL section on Storage:

"First, the general rule of thumb: An asset should be placed only as high on the directory tree as necessary. That is, if you have an image that is used across the whole site, like the THL logo, it qualifies for the top level /global/images/ directory; you wouldn’t want it hiding down somewhere like /collections/images/ or whatever. Conversely, if you have an image that is used only in "Places", it has no business cluttering up the /global/images/ directory, it should live in /places/images/."

How Specific Global Elements get Called from Templates, or, "Where is that CSS Coming From Anyway?"

Inside /www/global/ there are 5 subdirectories - go take a look at the filenames inside each one of these now please, to familiarize yourself and have them on hand:

  • css
  • images
  • js
  • php
  • xml

Just a few words of explanation for how these files get pulled into your rendered newpage.php page will suffice - the rest you'll be able to figure out from the code trail.

The starting point is the /global/php/header.php include in your newpage.php file - of course all the template index files include the header.php, as does wiki.php. The header.php file is responsible for pulling in all of the javascript - go pop it open and take a look to see all those js calls. Among them you will see fn.js - this one is important in that it contains the call for /global/css/thdl_style.css. The thdl_style.css file in turn imports these:

@import "thdl_layout.css";
@import "thdl_nav.css";
@import "thdl_legacy.css";

This should get you on your way to tracing any further css resources at play.

The "php" directory contains the standard header, footer, masthead and masthead links, and other sitewide php files including a number of utility files. Some of these were created for possible future use and are not yet in play. Later you will learn how to override some of this code by copying files from /global/php/ to a new directory and editing them there. It's worth your time to open each one and give them a quick look.

As for the other directories, the /global/xml/ directory btw contains just the xhtml file for the popup "THL Menu" in the upper left corner of the new site design, and the "/global/images/" were just explained above.

The Anatomy of Your New Page, Part 2: Top to Bottom

Ok, so you've seen some of the innermost workings of the php, css, javascript and etc as they have been crafted for our new site design. Now let's step out a little bit further and look at the template index page as a whole. Once you've gotten thru this, there will be just one more step!

This is The Exception referred to at the beginning of this page - the full page anatomy is too much, so please go see The Anatomy of Your New Page, Part 2, Top to Bottom.

Once you've come back from there, you can:

Write Your First Words

At last, you can put some content into your newpage.php page. From the last Anatomy lesson you'll recall seeing this:

&lt;p&gt;
(PRIMARY CONTENT HERE)
&lt;/p&gt;


Just delete the words "(PRIMARY CONTENT HERE)", enter in whatever you want, throw in some img src tags or whatever, then save, commit and deploy your file to staging.

Finally…

CONGRATULATIONS! You rock - now you know how to make a new page. Took a while, but now you have it and won't ever forget how to do it. You can always refer back here for details of course.

The next challenge you may wish to aspire to is Creating a New Portal or Project.

Provided for unrestricted use by the external link: Tibetan and Himalayan Library