plainblack.com
Username Password
search
Bookmark and Share

How to Build a Style Template

 

The versatility and creativity of templates is one of WebGUI's keys to a great looking site. Without templates you have a flat, boring, and uninspiring site. With WebGUI's templates you can create virtually anything. This simple guide will help designers with HTML and CSS experience become better acquainted with WebGUI style templates to optimize design and control.

 

Get Started

 

A WebGUI style template is similar to a standard HTML page, so begin by making the design work as a standard HTML (.htm) file. WebGUI style templates contain many of the same tags and methodologies, but WebGUI integrates its own macros to create dynamic content. A clear understanding of those macros is the key to making successful templates.

 

To simplify the process, it is best to begin by making a copy of your existing .htm page (from now on the Working Copy). Always keep an original reference in addition to the Working Copy. If you are working with a program like Dreamweaver or Frontpage, now is the time to find a good program editor. Design staff at Plain Black recommend Notepad++ for Windows, or Taco HTML for Mac. Both are free and easy to use.

 

Note: If any part of the template does not configure how you expected, try checking the source. This will allow you to view your code alongside WebGUI's. The problem can often be found in the HTML.

 

First Steps

  1. To begin designing your own WebGUI style template, start your file editor and open the Working Copy of your .htm file.

  2. Consider all of the page elements that aren't actually part of the file: graphics, javascripts, CSS files, etc.

  3. Convert all <img> tags to use either AssetProxy or FileUrl.

Choosing Whether to Use AssetProxy or FileUrl

 

ˆAssetProxy();

 

As a general rule, use ˆAssetProxy(); if you intend to pull in an image without changing any of its attributes, such as border, align etc. The macro will detect that you're requesting a graphic to be drawn and will generate the necessary <img> tag.

  • Standard HTML Tag: <img src="images/top_left.gif"/>

  • WebGUI Macro: ˆAssetProxy(images/top_left.gif);

 

Example

 

<div class=”headerArea”>
<div style=”position:absolute;top:0px;left:0px”>
^AssetProxy(images/top_left.gif);
</div>
<div style=”position:absolute;top:0px;right:0px”>
...

 

 

ˆFileUrl

 

If you want to directly control the image attributes, use ˆFileUrl();

  • Standard HTML Tag: <img src="images/top_left.gif"/>

  • WebGUI Macro: <img src="ˆFileUrl(images/top_left.gif);" />

 

Example

 

<div class=”headerArea”>
<div style=”position:absolute;top:0px;left:0px”>
<img src=“^FileUrl(images/top_left.gif);” />
</div>
<div style=”position:absolute;top:0px;right:0px”>
...

 

 

The difference is that ˆFileUrl simply returns the URL, without drawing the<img> tag. This allows you to define attributes directly in the template.For example, to apply an inline style to a specific image:

 

  • Standard HTML Tag: <img src="images/top_left.gif"style=vertical-align:middle;"/>

     

  • WebGUI Macro: <img src="ˆFileUrl(images/top_left.gif);"style="vertical-align:middle;" />

Example

 

<div class=”headerArea”>
<div style=”position:absolute;top:0px;left:0px”>
<img src=“^FileUrl(images/top_left.gif);”
style=”vertical-align:middle” />
</div>
<div style=”position:absolute;top:0px;right:0px”>
...

 

 

You could accomplish exactly the same thing with AssetProxy, but it would require you to add the “style=”vertical-align:middle” property to the image's parameters in the Asset Manager. Either option accomplishes the same thing, and when it comes right down to it, it becomes a judgment call on the designer's part. I, however, tend to use FileUrl more than AssetProxy for images just so that I can control image properties on a case-by-case basis.

If you have an external style sheet or style tags between the head tags of your Working Copy, you need to convert them using FileUrl.


For a more in depth look at FileURL and AssetProxy, refer to the chapter on Macros and Variables.

 

Example

 

#header { 
background: url('^FileUrl(style3/header_bg.jpg);');
width:100%;
margin:0px;
height:115px;
}

 

 

A macro is not necessary to reference Javascripts and CSS; however, you should give them an absolute path. For example:

 

Start with:

<link href="css01.css"rel="stylesheet"type="text/css"/>

End up with:

<link href="/css01.css"rel="stylesheet"type="text/css"/>

Note: the change is subtle. You need to place a / in front of the "css01.css".

 

Example

 

<html>
<head>
<link href="/css03.css" rel="stylesheet" type="text/css" />
<tmpl_var head.tags>
<title>^c; - ^Page(title);</title>
</head>

 

     

Now that all your external files are referenced, it's time to start thinking about getting the template to work correctly in Admin Mode. There are three pieces of code necessary to make this happen:

 

<tmpl_var head tags> : Place this tag between the <head> tags in your page. To make it easy to find, put it right after your <title> tags. This tag (known as the template variable) pulls in all of the code that actually make the other two pieces of code work. If you forget this, your page will appear to be broken.

 

Example - <tmpl_var head.tags>

 

<html>
<head>
<link href="/css03.css" rel="stylesheet" type="text/css" />
<title>^c; - ^Page(title);</title>
<tmpl_var head.tags>
</head>
...

 

ˆAdminBar(); : It's best to put this immediately after the starting <body> tag. This macro references the Admin Bar located at the left hand side of the page, and will only appear when in Admin Mode.

 

Example - AdminBar

 

...

</head>
<body>
^AdminBar;

...

 

<tmpl_var body content> : Most designs have an area denoted for content; put this template variable in that spot. This tag is probably the most important of the three: without it, you can't place any content on the page.

 

Example - <tmpl_var body.content>

 

...
</div>

<div id="mainBody">
<div id="contentArea">
<tmpl_var body.content>
</div>
...

 

 

 

Installing the Template

 

A design has been created, and the steps necessary to create a style template from the original XHTML have been covered. All the code necessary to edit the page, add content and have it work in Admin mode is present.

 

Now comes the time to take that simple file and put it onto a WebGUI server. This process is often seen as cryptic and difficult, but honestly it isn't at all. You just need to know the steps to accomplish the task. First, understand how WebGUI handles URLs.

 

Note: Remember that your content is dynamic; you're just making a generic template. Anything you put into this template will be rendered on any page it is used.

 

WebGUI URLs

 

Ordinarily, paths rely on directories and subdirectories; however, WebGUI allows URL's to be specified by you. This gives you an incredible amount of freedom since you are not bound by a directory structure to have a URL name. You could have a page three levels deep in the asset tree, and you could still have the URL for an asset as “/bob_smith” instead of “/home/about_us/staff/bob_smith.”

 

Start the process by going through a few simple steps in order to keep all of the files, images, snippets, assets, etc. in one central location on the WebGUI Server.

 

Creating a WebGUI Workspace

 

  1. Log in and enter Admin Mode.

  2. In the Admin Console, click on the Assets link, denoted by a small filing cabinet icon.

  1. The "Assets" screen will open.

 

 

  1. In the top left hand corner of the "Assets" screen you'll notice a series of links: Root>Home.

 

 

  1. Click on the "Root" link to go to the root of your WebGUI Asset Manager.

  1. Open the folder labeled "Import."

 

 

  1. Begin installing your design.

    1. In the "Import Node" screen, locate the New Content menu on the left side of the screen.

    2. Click on the "Folder" link at the top of the New Content menu of the Admin Console.

  1. The "Add Folder" screen will open.

 

  1. Give the folder a title and a URL (if the URL field is left blank, WebGUI will automatically generate a URL for you). 

    1. Both should be simple, easily recognized by you, and should reflect the nature of your template. From here on, this will be called your "Template Folder."

    2. After you have entered your title and URL, click save.

       


10. You will now see your new folder displayed in the list of folders contained in "Import" (probably at the bottom). From here, we will call the folder you just created "Template Folder".

 

11. Open the "Template Folder" you just created and create a folder for your images within the "Template Folder." This is important to ensure a smooth and seamless install of your graphics.Once you have opened the "Template Folder," again go to the New Content menu and select Folder.

12. Give the folder a title. Whatever name you used for the folder that held your images should be duplicated here.

 

13. Enter the same title in the URL field.

 

14. Click "save" at the top of the "Add Folder" screen. You will see your new "images" folder appear as a folder within the "Template Folder" you previously created.


Upload Images

To begin to upload your images, open the "images" folder you just created in the Asset Manager.

 

1. Click on "File Pile" in the New Content menu of the Admin Console located at the bottom of the "images" folder screen. The "Add a Pile of Files" screen will open.

 

2. Click on the "Browse" button to locate the desired graphic's file on your computer.

 

3. From the file upload screen, select the file you want, and click on "open."

 

You will see the file name appear in the field next to the "Browse" button of the "Add a Pile of Files" screen. You will also notice a new field has appeared from which to browse and select another file to upload.


4. Continue to click on "Browse" and select as many files as you need to upload.

 

5. When you have chosen all your files, hit the “save” button to upload them.

 

Finish Template Installation

Now, finish installing the template. Return to the "Template Folder" you created in the Asset Manager.

 

1. Click on "Template" in the New Content menu on the left side of the screen. The "Edit Template" screen will open.

 

3. Give your template a title and URL, making sure they are simple and easily recognizable. (You can leave the URL field blank and WebGUI will generate one for you.)


4. From your Working Copy, select all of the code and copy it to the clipboard. Paste it into the "Template" text area of the "Edit Template" screen

 

5. Verify that all your settings are correct, then click save at the top of the screen. Note: You must set the namespace field of the template to "style".

 

Congratulations! You have just installed your template into your WebGUI server. If you don't have any Javascript or CSS files, you're finished. But first, you should really test out your template to make sure it works.

 

Preview Your Template

 

Now that you've installed your template, take a moment to look at it. The following steps will outline how you do that.

 

  1. Begin from the homepage of your WebGUI website. From the New Content menu, create a new page layout asset by selecting "Page Layout."

 

  1. The "Add Page Layout" screen will open.


 

  1. Click on the "Display" tab.


  1. Under the "Style Template" dropdown menu, select the template you just created.

 

 

 

  1. Check the other settings on your page, and click save. A new page with your design should appear.

     

 

Fantastic, you have your template and it actually works!

 

Navigation

 

WebGUI comes with many navigation styles and configurations. It's important to understand that the Navigation Configuration and navigation style template are different, although inextricably linked together.

 

  • Navigation Configuration: determines what is displayed.

  • Navigation Style Template: determines how it is displayed.

 

If simply modifying one of WebGUI's preinstalled Navigation Configurations doesn't fulfill your needs, you'll have to create your own. From a designer's perspective, one of WebGUI's biggest advantages is its ability to map out navigations. While Navigation Configurations don't determine the look of your navigation, they are important in determining what pages appear in the navigation. If you choose to use dynamic navigation, first familiarize yourself with the Navigation Configurations.

 

Navigation Configurations

 

  1. All of the pre-installed WebGUI Navigation Configurations are located in “Root>Import>Navigation” from the Asset Manager.

    1. Look for the small icon shaped like a compass and the word "Navigation" to ensure that you are locating a Navigation Configuration.

 

  1. Click on "Edit" next to the desired configuration, and note the URL.

 

 

3. Copy the URL to your computer's clipboard.


4. Return to your Working Copy and locate where you want to place the navigation system.

 

5. In that location, AssetProxy the Navigation Configuration using the URL you just copied.


Configuring Your Navigation Configuration

 

Each Navigation Configuration has its own settings, so you can either use an existing one, or create a new one. If you need to create a new one, simply click on Navigation in the New Content menu to get started.

 

Note: If you need to hardcode your links, instead of letting WebGUI handle them dynamically, remember to turn them into absolute paths, not relative paths.

 

The Navigation Asset

 

A good way to begin is to copy and paste an existing navigation using WebGUI's clipboard. You may then alter it to your liking. Place your new navigation configurations in the same folder that holds your style template and images.

 

Take some time to examine the Navigation Configuration settings that came with WebGUI to determine if one of them already meets your needs.

 

 

  1. Start Point Type: This setting tells the navigation from where it should start pulling pages. It has three options available from the drop down menu:

    1. Specific URL: allows you to enter the specific URL of the page from which you want the navigation to start.

    2. Relative to Root: sets the navigation to begin from the Root of the Asset Manager

    3. Relative to Current URL: the most dynamic of the three, this has the navigation system start pulling pages from whatever page the user is currently viewing.

 

  1. Start Point: based on what you choose for your start point type, this specifies from where the navigation starts pulling pages.

 

 

  1. Relatives to Include: this series of checkboxes allows you to specify what pages, based on their relationships to other pages, should appear in the navigation. 

 

    1. Ancestors: pages that are higher up in the page tree.

    2. Self: the current page.

    3. Siblings: pages that are at the same level as the current page in the page tree.

    4. Descendants: pages that are lower in the page tree from the current page (aka subpages or children).

    5. Pedigree: performs the functions of Ancestors, Siblings, and Descendants.

 

If you select Ancestors or Descendants, new boxes show up to give you more options.

 

 

  1. Ancestor End Point: You can define how many levels back in the page tree you want to go.

  2. Descendant End Point: The reverse of Ancestor End Point, this lets you set how many levels of descendants should show up in the navigation.

 

Choose a Navigation Style Template

 

Once a configuration has been chosen or created, it's time to pick a navigation style template to associate with it. Here are the steps to accomplish that.

 

  1. Create a Navigation Asset by clicking on Navigation asset in the New Content menu, denoted by a small compass.

  2. The "Add Navigation" screen will open.

  1. Click on the Display tab of the "Add Navigation" screen. There are many options here, but for now it's only important to focus on the option in point 4.

  1. From the "Navigation Template" dropdown menu select a navigation style template.

 

 

WebGUI comes pre-installed with a number to choose from. Take some time to become familiar with each in order to choose which best meets your needs. Indent Nav and Bullet List work well for many, and can be configured using CSS. Chapters devoted to these two navigation styles can be found later in the guide.

Options for CSS and Javascripts

 

CSS and Javascript present unique opportunities and also unique considerations within WebGUI. The first thing to consider with CSS is backgrounds. Like many, you might use backgrounds in your CSS classes and ids. The best way to accomplish this is with the WebGUI macro, FileUrl. Here's an example of a standard CSS class using the background property.

 

 

Standard Background Property in CSS

 

 

.redBg {

background: #ff0000 url('images/red_bg.gif');

}

 

 

And here's the same CSS modified with the WebGUI FileUrl macro.

 

Standard Background Property in CSS

 

 

.redBg {

background: #ff0000 url('^FileUrl(images/red_bg.gif);');

}

 

 

It looks very similar to the original CSS, but the FileURL macro has been inserted directly into the code so that WebGUI is pointing to the correct image. You have to do this for every image that you are referring to in your CSS.

 

This now brings up an interesting question. What if you made a mistake in your CSS and you need to edit it? You'll have to edit the .css file on your computer, then find the file in the WebGUI asset manager, then replace the file you have in WebGUI with the revised version. It seems like a pretty big hassle, doesn't it?

 

Here's a thought though... have you ever considered a Snippet?

 

CSS Snippets

 

Snippets can emulate other MIME types, including style sheets and Javascripts. That means that within WebGUI you can create a wobject that behaves exactly like a style sheet or a Javascript. They're incredibly easy to set up and use, and you'll have the advantage of being able to directly edit your CSS right on the server.

 

Once you've set up the snippet with the correct MIME type, all you have to do is copy and paste your CSS into it. Remember the absolute paths set up earlier in the chapter? Those will be used to reference the snippets.

 

Once again, be sure to save your Snippets in your Template Folder along with all of your graphics and templates. It's always a good idea to keep all of these different WebGUI objects together.

 

Although you can set up a snippet to behave as many different file types, this example is going to focus on using it to emulate CSS.

 

Absolute Path to the Snippet

 

 

<link rel="stylesheet" type="text/css" href="/style.css" />

 

 

Using snippets is simply a matter of selecting the correct MIME type and then targeting it appropriately with the absolute path.

 

  1. Navigate to the folder housing all your template files and click on the Snippet icon in the New Content menu.

 

  1. The "Snippet Add/Edit" screen will open.

  2. Give an easily recognizable title to the snippet in the "Title" and "Menu Title" fields.

 

 

  1. Give the URL the same name as in the external reference (style.css); no slash should precede the name.

  1. Open your CSS file, and copy all of it to your computer's clipboard.

  2. Paste the CSS file into the Snippet field.

  1. You do not need this processed as a template, so leave that field set at "no."

  2. Most importantly, in the "MIME Type" dropdown menu, select text/css.

  1. Click save at the top of the screen. This will effectively create your CSS file!

 

 

Conclusion

 

Putting a style template together can at first seem like a daunting challenge. But once you start to realize that you actually put your entire design together outside of WebGUI, it starts to seem like a manageable task. Try to think in steps when you're about to tackle installing a template, and you'll find that it will become second nature.

 

  1. Create Your Design Outside of WebGUI, including XHTML and CSS

  2. Insert the necessary WebGUI Macros and Template variables into a COPY of your original .HTM file.

  3. Go to WebGUI and create a folder to store all of the assets necessary for your style template.

  4. Upload your images to WebGUI.

  5. Create a Template object, copy and paste all of your XHTML into it, and select the “style” namespace.

Keywords: CSS HTML macros navigation snippet style Templates theme

Search | Most Popular | Recent Changes | Wiki Home
© 2018 Plain Black Corporation | All Rights Reserved