Theme Creation in phpWebSite 1.0 by Matthew McNaney Version 1.0 ---------------- Original version Introduction --------------------------------------------------------------------- PhpWebSite 1.0 uses a template system for theme creation. If you are familiar with the previous version of the software, you should be right at home. You can probably skip the first couple of sections. Newcomers should continue. It is assumed you know how to create a page using just HTML encoding. If you would like to jump in, take a look at the fishy theme's creating_this_theme.txt file. It gives a tutorial of sorts. Templates -------------------------------------------------------------------- As mentioned in the introduction, you need to be familiar with our templating system. Templates contain an HTML framework with content "tags." PhpWebSite fills in these tags with dynamic information. Here is an example of a template:

Today's Top Stories

{STORIES}

"STORIES" is our tag and they will always be surrounded by curly brackets - {} When PhpWebSite sees these brackets, it will check to see if it has some information named STORIES. If so, it will copy the data into the tag. For theme design, that is enough to get you started. If you want more information on templates, please read the template.txt file contained in this directory. Setting up your theme -------------------------------------------------------------------- All themes should be saved in the "themes" directory. Your theme name forms the theme directory's name. Let's look at the default theme. Open up your phpwebsite/themes/default/ directory. Two files in this directory form the foundation to your theme. "theme.ini" contains information about your theme. "theme.tpl" is the theme template. Your theme will not display without both of these files. theme.tpl -------------------------------------------------------------------- This is our theme's template file. Take a look at the default theme.tpl file. Let's view the tags in our template. These tags need to written above your opening HTML tag. {XML}{XML_STYLE}{DOCTYPE}{XHTML} Each of these tags assists in defining your page. Make sure they are above the html tag of your theme. You do not need a html tag. These tags will take care of it. The following tags should appear between your HTML tags. {BASE} Required by style sheets. Leave it in. {PAGE_TITLE} This tag sits between the html tags. You don't have to use it, however phpWebSite uses it to dynamically entitle pages. Making it static will obviously defeat this ability. {METATAGS} Your meta tag settings in the Layout module appear in this tag. You should leave it. {JAVASCRIPT} Various Javascript routines appear in this tag. Make sure to include it. {STYLE} PhpWebSite can perform some neat tricks with your theme's style sheets. Make sure to include this tag. You may add extra style information before or after if you wish. That covers the header tags. Next we will go over the tags that should appear between the <body> HTML tags. {BODY} Your site's main content will appear in this tag. As such, it is a required tag. {DEFAULT} Any content that does not appear in the BODY tag, appears here. DEFAULT usually receives short content, administration menus, advertising, etc. It is also required. Module tags --------------------------------------------------------------------- That is the end of the required tags. If you are looking at the default theme.tpl file, you should notice tags like MENU_MENU_1, SEARCH_SEARCH_BOX, USERS_LOGIN_BOX, etc. These are module specific tags. They are not required, but very useful. When a module developer creates a content "box" that doesn't appear in the {BODY} tag, they give it a content variable name. This specific name, allows you to move the box around your page via Layout. As a theme developer, you may want to secure this content in a specific area. For example, lets look at the search box. If left to its own devices, when the search form is sent to the theme, it will look for its special parking spot. If it doesn't see one, it appears inside the DEFAULT tag. So, if we have a special area we wish it to appear in, we have to create a module tag. The name of the tag is composed of the name of the module, an underline, plus the content variable name. module name + underline + content variable ----------- --------- ------------------ search + _ + search_box So the search theme tag is named "search_search_box". We just capitalize the name, surround with curly braces {SEARCH_SEARCH_BOX} and place our default search box tag into our theme. Extra tags --------------------------------------------------------------------- If you want to add more content areas to your theme, just create other tags with whatever you want to name them: {HEADER} {BOTTOM} {RIGHT_COLUMN} As long as they are registered in the theme.ini file (covered next), you can move content into them using Layout. theme.ini -------------------------------------------------------------------- PhpWebSite looks to this file for information about your theme.tpl file. Look at the default theme's theme.ini as an example. Information sections are entitled with square bracketed titles. [theme_variables] The most important setting. Whenever you add a content tag to your theme, it MUST be registered here. If it isn't, then phpWebSite doesn't know they exist in your theme. You don't need to register the BODY or DEFAULT tags as they are assumed to exist. Starting at zero (0), number each tag name sequentially. [theme_variables] 0 = LAYOUT_HEADER 1 = LAYOUT_FOOTER 2 = BOTTOM (etc.) The remaining setting cover the style sheet definitions. The theme.ini file contains comments explaining each setting but we will go over them here as well. You can have as many style sheet definitions as you want. Just number them sequentially (style_sheet_n) Look at the theme.ini file's first style sheet - [style_sheet_1] There are three settings - file, import, and media. file ---- Required. The style sheet file name. This file name is relative to the current theme directory. So if your style sheet was in themes/my_theme/css/style.css, you would set file = css/style.css import ------ Not required. Defaults to FALSE If true, phpwebsite will import this file instead of linking it: <style type="text/css">@import url('themes/my_theme/style.css');</style> vs. <link rel="stylesheet" href="themes/my_theme/syle.css" type="text/css" /> media ----- Not required. Choices are: all, aural, braille, embossed, handheld, print, projection, screen, tty, tv A list of media devices, separated by commas, which determine the style sheet's availability. Remember, if you don't use "screen", the style sheet won't be used when displaying your theme in a web browser. title ----- Required alone for preferred style sheet, and with alternate setting for alternate style sheets. If you are using alternate style sheets, you need to give the style sheet a title. If this style sheet is the "preferred" style sheet, then only set the title. If this is an alternate to the preferred style sheet, then set the alternate setting to true (see below). alternate --------- Required for non-preferred, alternate style sheets. Default is FALSE. Setting this value to "true" indicates this is an alternate style sheet. Extra Styles -------------------------------------------------------------------- Sometimes, the site administrator may want to use a specific style sheet for a certain page. You can indicate these alternate files with the [extra_styles] section. The default theme has two: [extra_styles] bigfont.css = Big Chief Font green.css = Emerald City When a specific page sets an alternate style sheet, phpWebsite appends the file to the list of current style sheets. Locking variables -------------------------------------------------------------------- Layout gives administrators the ability to move content into different theme tags. If you want to prevent admins from accessing a certain tag you can lock it. [locked] ignore = 0,1,3,4,5,6,7,8 Each number corresponds to a theme_variable. If that number is ignored, Layout will not offer the opportunity to move content to that tag. Alternate templates (Advanced) -------------------------------------------------------------------- Modules use templates as well. The results of these templates are piped into the theme. Sometimes, a specific module's template may not fit your specifications. You can force phpWebSite to use a copy of your version of the template instead. First, find the template you want to change. The easiest way to do so is go into the config/core/template.php file and change the LABEL_TEMPLATES value to TRUE. Make sure you change this back to FALSE when finished. Refresh the page and look at the source. You should see comments like:  (content here)  Look for the area you want to change and note the file name. There are two ways you can change this template. First, you can go edit the template directly. The second option is to create a copy in your theme. The second method is best used when you plan on sharing your theme. Using the above example, I just need to recreate the directory structure in my theme. Example: phpwebsite/themes/my_theme/templates/usermenus Now I make a copy of the top.tpl file in the usermenus directory. That's all there is to it. Now if I make changes to the template, they will be reflected in my theme. Theme.php -------------------------------------------------------------------- If you want to insert the results of a small php script, you can use the theme.php file. In order for Layout to run the theme.php file, LAYOUT_THEME_EXEC must be set to "true" in your config/layout/config.php file. Once set, Layout will include the current theme's theme.php file before compiling the output. The best way to use theme.php is to pipe the content into the plug function: Layout::plug($some_bit_of_content, $theme_variable_name); Afterwards, the theme.tpl just needs a tag named after the $theme_variable_name. In other words, if the $theme_variable_name is 'foobar' then you need a {FOOBAR} tag in your theme.tpl file. Unless you are testing, I do not recommend simply echoing content in your theme.php file. Use Layout to display the content.