search

WebGUI Macros and Template Variables

You’ve come up with a design, decided between tables or pure CSS for your layout, and you’re ready to take the plunge and turn that design into a WebGUI template. Now the question is, how does that transformation occur?

The good news is, if you’ve already taken your design from a Photoshop (or other program) mockup and turned it into HTML and CSS you’re practically done. All that’s needed now are some WebGUI macros and template variables. First, you need to understand what macros and variables are.

Variables

Most people have taken an algebra class at some point in their educations. This background is a good way to approach understanding variables.

In mathematics, a variable is an unknown quantity that has the potential to change; in computer science it represents a place where a quantity can be stored. Think back to algebra and consider the following equation: A + B=6.

You know the answer has to be 6, so that limits the quantities that can be assigned to A and B. A could equal 4 and B could equal 2, or A could equal 5 and B could equal 1. Although their values can vary, there are restrictions because their final sum must be 6.

WebGUI uses variables liberally in all its templates, which gives you a great deal of flexibility. Consider this: you have an article asset in WebGUI that you’ve named “Example Article.” Let’s say you have another article that has the name “News.” Both of these articles are displayed using the exact same template called “Default Article.” However, if you choose to display the titles of the articles via the Display tab of the asset add/edit screen, each article displays a different title, despite the fact that they have the exact same template.

This is done through variables. There is a variable in the Default Article template that grabs whatever title you give a particular article and displays it. This is a simple example of a variable at work in WebGUI.



The Basics of WebGUI Template Variables

To understand template variable syntax, remember that every template variable in WebGUI follows this format:

Syntax of a Template Variable



This is similar to an HTML tag: opening and closing brackets with a cryptic word, or words, within them. The text in red is the declaration that signifies a template variable is being used. The text in blue is the actual template variable's name.

Aside from these familiar tags, every template variable begins with tmpl_var, which stands for “template variable.” Following that declaration is the actual name of the variable, in this case body.content.

Some template variables will follow this format, with one word followed by a period, then another word. In other cases, there will only be a single word, and in still other cases there could be multiple words, each separated by a period. It isn’t important to understand the logic of why there are multiple periods, but it is important to remember that some variables use them, and some don’t.

Example Template Variables

body.content

Use: displays content in style templates.

Used in: style templates

This variable allows content to appear in the body of the page, just as its name implies.

This is an incredibly important template variable. If it doesn’t exist in a style template, you have a very broken WebGUI site. Without this, when admin mode is turned on you have none of the controls for editing, copying, pasting etc. Worse, without this template variable you are unable to place content on the page.

Use: calls necessary code to make a style template function in WebGUI.

Used in: style templates

Just like body.content, this tag is very important. This variable can be thanked for drag and drop content positioning, meta tag creation, and the Admin Bar scrolling up and down on your screen.

This variable calls all of the javascripts and other pieces of code that make a style template, and all of the WebGUI user interface, work.

page.url

Use: returns the URL of a given page layout asset

This template variable returns the URL you assigned to an asset.

If you gave your “About Us” section on your site the URL /about_us, this template variable would display the URL on the page. When you combine this with a standard HTML anchor tag, you create a link to the page. For example:

Use: returns the menu title of a given page layout

Used in: Navigation templates, Style templates

This template variable returns the Menu Title you assigned an asset. Using the example above, if you put “About Us” as your Menu Title for an asset, this template variable would display it on the page. Combine this with page.url:



Because there aren’t any titles or URL’s hardcoded into the navigation template, and because the navigation template is set to loop through all the pages, the entire navigation system has been created with just a simple loop.

page.reldepth

This template variable is useful in navigation templates. WebGUI pages work in a hierarchy, as seen in the asset manager. The homepage in the site navigation has descendant pages, and the descendant pages have their own descendants and so on.

This variable returns a numeric value to tell you on what level the page exists. In this case, the number returned is dependent on where you tell the Navigation asset to start displaying pages. This is set at the time of navigation creation in the “Start Point Type” and “Start Point” fields of the navigation add/edit screen.

To better illustrate this, consider the following example.

Let’s say you have a Navigation asset that is set to start displaying pages that are descendants of your homepage. If this template variable was put into a navigation template, it would display a 1 next to the first set of pages, a 2 next to the immediate descendant, a 3 next to the following level of descendants and so on.

Bulleted List Template

Bulleted List is one of the more complicated WebGUI templates, and the point of showing it here is not to go in-depth with every variable, but to show you the use of page.reldepth. The text in bold shows you where the variable is used.

In the first instance, it is used to create a dynamic classname.



• removed="window.open('')" href="#" href="" > -

•

Take a look at the XHTML that is generated by this template.

Bulleted List XHTML

 ``

The numbers show you where the template variable was actually rendered, displaying the page's relative depth as each link to the page was drawn. As you can see from the indenting of the code, the further down in the page tree you go, the higher the number.

The top level pages all have a dynamically generated class name of “level1.” The secondary pages are “level2,” and of course the third set of pages are “level3.” In addition, you also told the template to spit out the relative depth after each link, which is why you see “- 1”, “- 2” and “- 3” after the closing </a> tags. Take a look at the final product.

Loops

In WebGUI, loops are frequently used to sort through, display and organize data. The best example of a loop is navigation. Your site consists of tens, possibly hundreds, of pages, but with WebGUI you don’t have to manually code all of the links to those pages in your design. Instead, you can just use a WebGUI Navigation asset.

What this asset does is “loop” through these pages, one at a time, and write out the name of the asset and the link to the asset. Result: instant navigation, and you didn’t have to code anything!

Another example of a loop is the Collaboration System. A series of posts exist within a collaboration system, and with a loop WebGUI goes through them one at a time and draws their titles, links to the posts, who wrote each post, etc.

A loop can be created using a template variable. Below is an example of a very basic page loop that could be used in a navigation template:

Basic Page Loop



The very first template variable you’ll notice is page_loop. The syntax for this variable is different from other template variables because, unlike other template variables, it doesn’t actually return anything, it performs an action. It loops through the pages of your site and performs the actions within it. So, taking a closer look, everything between the following tags...

Loop Syntax

 ...

...happens to every page this navigation template is set to loop through. Be sure that you have that closing </tmpl_loop> tag to match the opening tag, otherwise this won’t work.

Note: Each WebGUI template has access to its own set of template variables. That means that a variable from one template won't necessarily work in another. A surefire way to figure this out is if a variable does not actually return anything at all when used in a template. Variables, when used in a true/false test, will alway return a false if they aren't available. Always refer to WebGUI Help to double check which variables are available.

Logic Tests

Logic tests were touched upon briefly in chapter one. “If this is true then do this action, Else do another action.” This section discusses how to turn the concepts discussed in chapter one into practical use in WebGUI.

The If Statement

 ...

Look familiar? This is very similar to the syntax used for a loop. There is an opening tag to begin the IF statement, and then a closing tag. If the IF statement is true, then whatever is between those tags will be displayed on the page. The “n” that comes after the initial tmpl_if would be the value tested against.

Consider combining this IF statement with another template variable.

The If Statement with a Variable

 ...

In this example, a template variable is being used in a navigation template. It allows you to test to see if a page’s relative depth is 1. The idea of relativity was discussed along with the page.relDepth template variable; now, instead of returning a value (1,2,3...), this template variable generates a true or false answer. So, in plain English:

The IF/ELSE Statement

   ...     ...

There is a logical test to determine if something is true, and then an action is performed if it is true. But what if it isn’t true? In that case, nothing would happen with just an IF statement. That’s where the IF/ELSE statement comes into play; if a test returns false, an action is performed. Consider the earlier example with an ELSE thrown in:

IF/ELSE Example

   My relative depth is 1!     I am not located at relative depth 1.

Again, this is testing to see if a page’s relative depth is 1. In this case, if its relative depth is 1, then the line, “My relative depth is 1!” is drawn on the page. In all other cases, the line, “I am not located at relative depth 1.” is displayed. Essentially, the IF/ELSE statement gives a default value so that something is drawn onto the page regardless of whether or not the original returns true.

The best way to think of it is a catch-all statement. Sure, you may have tested to see if something was true, but if it isn't true nothing at all would happen. By putting in the “Else” you are ensuring that something is done no matter what.

The IF/ELSE IF Statement

 ... ... ...

The IF/ELSE IF statement gives an even greater amount of control over what can be displayed on a page. With an IF/ELSE statement the best outcome is coming up with a default action if the IF value tested against is false. Now, another test can be added to further narrow the actions.

IF/ELSE IF Example

   My relative depth is 1!     My relative depth is 2!

If the page’s relative depth is 1, the phrase, “My relative depth is 1!” is displayed. If a page’s relative depth isn’t one, then the ELSE statement kicks in.

However, in this case another IF statement is part of the ELSE. The idea here is that once the ELSE statement kicks in, the very next thing that happens is another IF statement that tests against a different value. In plain English:

Macros

One of the most powerful and useful tools in WebGUI is the macro. Macros expose some of the programmatic features of WebGUI to the user, but don’t require the user to know anything about programming.

Put simply, to use a macro you need to learn what’s available and select the appropriate choice. Take a look at this example of a macro to understand its makeup.

Macro Example

Note: WebGUI Help has a full list of available macros. Although this focuses on macros used for design purposes, there are many more that you may find useful.

 ^AssetProxy(n);

The syntax of a macro is very simple. The most important thing to remember is the very first character and the very last character. In this case, the opening carrot symbol (^), and the closing semicolon (;). Every single macro in WebGUI follows this format. The carrot symbol lets WebGUI know that you’re trying to use a macro, and the semicolon lets WebGUI know when you’re done.

Immediately following the opening carrot is the name of the macro, in this example that would be AssetProxy. Macros never contain spaces or underscores. There are dozens of macros available in WebGUI, and each has its own unique name.

Some macros can be called with just the opening carrot, the name of the macro, and the semicolon. However, many macros can accept “parameters,” pieces of data that can make the macro behave differently from its default behavior.

To place a parameter in a macro, a pair of parentheses is placed between the last letter in the macro name and the ending semicolon. Place the parameter within these parentheses, typically in quotation marks.

In the example above, the letter “n” was used to indicate a parameter. Here is a more realistic example:

Passing a Parameter to a Macro

 ^AssetProxy(“images/blue-dot.gif”);

In this example, “images/blue-dot.gif” is the parameter being passed into the “AssetProxy” macro. This particular macro doesn’t really work properly without a parameter passed into it, and still others require multiple parameters. For example:

Passing Multiple Parameters to a Macro

As you can see, the only difference when calling a macro that requires two parameters is to place a comma between those parameters. The order in which the parameters are passed is important, so be sure to refer to WebGUI Help (and the examples in this book) to learn in what order you should place them.

Macro Examples

^AssetProxy();

Use: to display nearly any asset on a page layout or in a template

Requires Parameter(s)?: Yes, one. The URL of the asset to display.

One of the most commonly used macros in WebGUI, this allows you to grab an asset and display it. It is most commonly used to display images on a page, but can be used for almost anything.

To use it, simply pass the URL of the asset as the parameter and AssetProxy will find it, then draw it into your template or page.

The great thing about AssetProxy is that it is intelligent. If you give it the URL of an image, it will recognize that image and draw the appropriate HTML tags to draw that image out. For example:

AssetProxy Example

 ^AssetProxy(“images/t-shirt.gif”);

WebGUI will then process this macro and return the following HTML:

AssetProxy XHTML



The macro draws out all information related to the image, so any properties that you've listed for the image will also be drawn out. Notice the text in red? Here's where AssetProxy gets that from.

Image Properties

Consider an example other than an image. What if you were working on a style template for your website and you wanted to display a WebGUI Navigation asset at the top of your page?

In that case, you’d just put the URL of the Navigation asset into AssetProxy and WebGUI would draw it on the page. This works with nearly every asset in WebGUI, so you can call Snippets, Polls, etc. into your pages and templates with a simple Asset Proxy call.

Using AssetProxy to Display It

 ^AssetProxy(example-design/top-nav);

This macro works similarly to AssetProxy in that an asset’s URL is passed as a parameter; however, what is returned is quite different. FileUrl returns the actual URL of the file that you pass to it. Whereas AssetProxy not only returns the URL, it also draws all of the necessary HTML tags and any properties assigned to the image.

Also, AssetProxy can have nearly any asset’s URL passed to it, while FileUrl only works if you pass it the URL of some type of file that is not native to WebGUI. In other words, files that you yourself uploaded to your WebGUI site, such as graphics, flash files, javascript files, CSS files, etc.

^FileURL();

Use: to return the URL of a file not native to WebGUI (images, javscripts, files, etc).

Requires Parameter(s)?: Yes, one. The URL of the file.

FileUrl Example

 ^FileUrl(images/t-shirt.gif);

One of the more commonly asked questions about FileUrl is, “Why do you need it?” If you’re giving it the asset’s URL to draw the asset’s URL, isn’t that redundant? The main purpose behind FileUrl is performance. Hardcoding a file’s URL into a template or page will result in low performance levels in WebGUI. FileUrl speeds up the server request to display the file more quickly. This is noticeable if your site is being visited often by many users.

Requires Parameter(s)?: No

This is a very simple macro, but extremely important. When admin mode is turned on in WebGUI, this macro calls the Admin Bar into existence on the left side of the page. The only acceptable place to put this macro is into a style template, and for it to work the template variable head.tags must have been declared earlier in the style template. Without this macro, the option of adding content to a page outside of the Asset Manager is eliminated. This macro does allow you to pass it a parameter, but it isn't necessary. Just by calling it, WebGUI knows to use the default template for the Admin Bar.

Using AdminBar in a Style Template

Use: displays an on/off toggle allowing users with at least content management access to easily turn admin mode on/off.

Requires Parameter(s)?: No

Another simple, yet important, macro. When called, a user with a valid level of admin rights will view a “Turn Admin On” link. Clicking this link will turn on admin mode, and the link text will change to “Turn Admin Off.”

Like ^AdminBar, this macro belongs in the style template, although it can be placed anywhere within it. Although this macro doesn’t require any parameters, it will accept three. You can alter the words displayed in the toggle, so instead of “Turn Admin On,” you could simply have the words “Turn On,” and similarly reword the “Turn Admin Off” toggle.

Like the AdminBar, the AdminToggle macro runs on a template, so you could either modify the existing AdminToggle template, or create your own.

^RandomAssetProxy();

Use: to display random content

Requires Parameter(s)?: Yes, the URL of the asset that contains the content you want randomly displayed on the page.

With this macro, you can easily display random content on a page. This macro can be placed inside any template, but in most scenarios it is used in style templates.

It’s extremely useful to have random images display in a banner or even to have random customer testimonials display in your design. Simply place this macro into whatever location you want the random content to appear, and the macro will take care of the rest. That being said, you need to give it a location from which to pull content. The parameter it accepts is the URL of an asset in your asset manager. Whatever that asset’s children are is what the macro will randomly choose from.

Plain Black staff recommend creating a folder asset and placing any of your random content within it, then pass that folder’s URL as the parameter to the macro. Provided here is a visual explanation of setting up this macro.

Using RandomAssetProxy

1. First, create a parent asset, like a Folder.

1. Give the folder a recognizable name, and copy its URL

1. Write the macro in any WebGUI template, and paste in the URL of the parent folder. You're done!

 ^RandomAssetProxy(random-home-banners);

Conclusion

The real power for a designer comes from the use of WebGUI macros and template variables. It can take a little time to learn them, but as long as you know the basic syntax of both it shouldn't take too long to figure out what you need.

The best way to think of template variables is the concept of Algebra. They are things that are representative; they themselves aren't actually your content. Keeping this in mind can help you consider innovative ways to use them in your templates.

Macros are predefined actions that are built into WebGUI. By calling one, you can display the Admin Toggle, call in a Navigation asset, and much more. Even better, you can pass most of the parameters that allow you to customize their behaviors.