Username Password
Bookmark and Share

Trouble Shooting

This chapter covers issues that you can run into using WebGUI, CSS and Javascript. Many of the examples mentioned here come from other areas of the book, so it is best to read the book in its entirety before consulting this chapter.


General Design & WebGUI

Q: Why do you seem to criticize Internet Explorer?


A: It isn't so much that I'm criticizing it, it's that it is extremely difficult to code for. Microsoft chose to not support most of the web standards that the W3C laid down, so consequently Internet Explorer (both 6 & 7) has poor implementation.


On the flip side, Mozilla Firefox supports most (although not all) of the standards, and it behaves in a much more predictable manner. This is why I strongly suggest coding for it first, then trying to make your CSS work in IE later.


Internet Explorer still dominates the browser market, so it's not like you can ever not code for it. But merely because it has the largest market share doesn't make it the darling of designers.


Q: I really don't understand programming logic. Why can't it be simpler?


A: The real trick to thinking of how to accomplish something with programming logic (which will help you immensely when using WebGUI loops, template variables and macros) is to talk about it out loud.


You'd be surprised how much easier it is to figure out almost any problem when you just explain the logic to yourself. Don't worry yourself about variables and loops, merely say out loud what you are trying to accomplish.


Programming logic is just human logic as we try to get a computer to understand it. Make sure you understand what you're trying to do first, and the rest will follow.


Q: I would really like it if I could change the size of thumbnails on my site. Where would I configure that?


A: There are actually two places.


If you want to configure your thumbnails across the entire website, then you'll want to go to the “Admin Console > Settings” and then the “Content” tab. There is a field there that lets you enter in a pixel value for the width of the picture. The height will scale proportionately to this value.


Thumbnail Size in Settings



Otherwise, you can just change the setting on a case by case basis, such as for a collaboration system. For more information, refer to the chapter on using a Collaboration System as an Image Previewer.


The most important thing to remember is that changing either value is not retroactive. If you change the thumbnail to either a larger or smaller value, you aren't going to see previous thumbnails scale to a new size.



Thumbnail Size in Collaboration Systems



Q: I made a change to the template and I'm not seeing the change, what's going on?


A: This is a problem I often run into, and it can be traced back to caching 9/10 times. The question is, what is caching?


Although when most people think of cache, they think of your local machine (or the green in your wallet) the culprit is usually WebGUI's cache. There are times where it still could be your browser's cache, and a simple refresh can solve the issue, but it's not always that simple.


A little known fact about WebGUI is that the caching system turns off when Admin Mode is on, so you may see your design work fantastically when it's on, but it frustratingly doesn't show up when it's off.


The best solution, at least for testing purposes, is to change the cache settings for an item where you're not seeing an update. I typically change the setting from 1 hour to one second, at least when I'm working on the asset.


Just remember to change it back when you're done.



Cache Setting



Q:  What should be in my style template? Should I have multiple ones?


A: First and foremost, NEVER put content into your style template. Your style template should be devoid of content, unless you have a very specific reason to include it.


Whatever you put into your style template will show up on every page you put it on, so it's best just to keep content where it belongs... and that's not in the style template.


As far as having multiple style templates, you'll actually find that somewhat unavoidable. There's nothing wrong with having multiple templates, you'll often need them because there are some limitations to templates.


For example, perhaps the only difference between one section and another in your site is the header graphic. There currently is no way in WebGUI for it to dynamically display a different graphic header based on where you are in the site.


Q: I went ahead and tried using a snippet for my [INSERT TYPE OF FILE HERE], but it doesn't seem to be working. Any ideas?


A: You probably didn't pick the right MIME (Multipurpose Internet Mail Extensions) type. Remember, for a snippet to emulate a file type, you have to pick the right one. You can pick one of six MIME types for your snippet to emulate.


  1. text/javascript – Emulate Javascript

  2. text/css – Emulate Cascading Style Sheets

  3. text/xml – Emulate XML

  4. application/xml – Emulate XML for Applications

  5. text/html – Emulate (X)HTML

  6. text/plain – Emulate plain text


Pick the correct one, and you should be off and running.


Snippet MIME Type Dropdown


Q: Do I have to put my templates in a specific folder for WebGUI to see them?


A: No, not at all. WebGUI uses namespaces (covered in a Q & A above) to find templates that are applicable to an asset and puts them in whatever dropdown boxes are appropriate.


I actually encourage you to put different types of templates into one single folder, and use that folder to hold everything that is specific to one project. Put your style template, your page template, your article template, etc, etc into this folder. WebGUI is smart enough to know what you created, and it'll deal with it in turn.


Q:  Can I really assign any URL I want to my assets? What about directory structures, don't I have to worry about that?


A: Yes, you can really assign any URL you want, and no, you don't have to worry about directory structures.


Even if a page is 5 levels deep into your asset tree, you could still give it a URL like, “/bob_smith”. WebGUI doesn't really care where the page is.


However, if you don't assign a specific URL to an asset, WebGUI will create a URL based on the URL's of its parent. For example, if you upload a JPG called “bob.jpg” to a directory that has a URL of “home/images/”, WebGUI will automatically generate a url of “home/images/bob.jpg”.


Cascading Style Sheets (CSS)


Q: Is it really necessary to wrap your projects within one main <div> tag?


A: No, I wouldn't say necessary but it's extremely helpful.


In most of the examples there was what is called a “wrapping” <div> tag that held all of the XHTML. It's a good idea to go this route mostly because it gives you a greater level of control.


Remember that WebGUI is dynamic, and you never know when someone might put your custom article template on the same page as your custom Collaboration System template. By wrapping each of those projects in a <div> tag and then targeting elements within those tags, you can be sure that your CSS for each one of those doesn't interfere with one another.


Example XHTML



<div class=”customArticle”>

<h2>An Example Title</h2>




<div class=”customCollaborationSystem”>

<h2>An Example Title</h2>






Example CSS



<style type=”text/css”>

.customArticle h2 {




.customCollaborationSystem h2 {








Resulting XHTML



Q:  When should I assign an ID in a template, and when should I use a class?


A: Any time you are dealing with something that can be reused, you should make it a class. A good example would be if you were to use and re-use an article template.


A user could potentially have several articles on a single page. If you made a wrapper <div> for the template code and assigned it an ID, you'd have a problem because now you have duplicated many of your ID's.


However, there are definitely times when using an ID is a good idea. You should consider using them in your style template or your page template. Only one of each of those ever appears on the same page, so you can be sure that you won't have a duplicated ID.



Q: What is the z-index property? You've mentioned it before but haven't given a good example of it.


A: Quite simply, the z-index helps determine the depth of a page.


Picture 3 sheets of paper sitting side by side, they all have a z-index of 0. Now, move the first sheet of paper on top of the second one. The first sheet of paper now has a z-index of 1. Then, move the third sheet of paper on top of the first one. It now has a z-index of 2.


You can give whatever value you want to your z-index. For example, you could have given them 10, 20 and 30 respectively, it doesn't matter. Just as long as you understand the highest value gets put closer to the “top” of the pile.


The z-index really only matters when you're dealing with elements on a page that are absolutely positioned above others. You'll need to set a z-index for the objects that they appear on top of.


Example of Z-index



Q: Argh! Internet Explorer keeps putting things in slightly different places than other browsers. How do I fix that?


A: This plagues many designers. There is no simple answer to this question, as every design has its own quirks. But, there are a few things you can do to at least make life a little easier.


  1. Create a Javascript to detect what browser the user is viewing the site on, and create different CSS files that are applied based on that test. I can't really recommend this option as all it does is give you a massive amount of work to keep track of.


  1. Make a very simple design where positioning of elements doesn't need to be exact. This is a good option if your site has very few graphics. It has the advantage of being very versatile as it should be able to easily stretch to fit whatever resolution the user is viewing the page at. However, if you want to use many graphics, this won't work.


  2. Create small changes in your main CSS file to separately target Internet Explorer and other browsers.


With the introduction of IE 7, the third option becomes a little more difficult, but is still workable. The example below takes advantage of an IE parsing bug, something that no other browser will recognize.


IE Parsing Bug



<style type=”text/css”>

p { /* For all non-IE browsers */




* html p { /* For IE 6 & 7 */







In all other browsers, the <html> tag is considered to be the element that holds all other elements. In Internet Explorer, there is some mysterious element that holds even the <html> tag. The second property is targeting that element, but since no other browsers have that element, they don't know how to interpret the code.


One of the many nice things about CSS is that if the syntax of something is wrong, the browser will just ignore it. So in this case, it is essentially saying that all browsers should give paragraphs 5 pixels of padding, but IE should give its paragraphs 15 pixels of padding.


  1. The last option is somewhat similar to the first, except that it employs no Javascript and creates less work for the designer. By adding in a conditional HTML comment, you can import a specific style sheet for problematic browsers. This style sheet can contain only the properties you need to fix or override.




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

<!--[if IE 6]>

<link rel=”stylesheet” href=”ie6style.css” type=”text/css” />





In the above code, the overall style sheet is imported first. The next line is a conditional comment that checks to see if the browser accessing the page is Internet Explorer 6. If it is, then the style sheet “ie6style.css” is imported. This style sheet would contain fixes to the problems that show up in that browser. Using this, you are able to avoid CSS hacks for the most part.


NOTE: There are many conditional comments that can be used here, including ones that check for just a specific browser with no version, ones that check for version X and above, ones that check for version X and below, and so on.


As an example, let's say that you are having an issue with margins and padding in Internet Explorer 6 (a common problem due to it's non-standard implementation of the box model). You could set the margins and padding to the normal value in “style.css”, then set them to the value that displays correctly in Internet Explorer 6 in “ie6style.css” using normal selectors – no need for the star hack listed above!


Usually only one or two additional style sheets need to be created, and they contain the exact same amount of extra declarations as using the third method. The only drawback is slightly decreased performance due to the multiple style sheet links.


Q: I'm having a hard time figuring out where my <div> tags are in my design, or even if I'm actually targeting the right thing. How can I know for sure?


A: That's easy. Make your design gaudy.


It pains most designers to make a design look awful, but sometimes it's necessary in order to debug your CSS. Don't be afraid to give your <div> tags bright red or green borders so you can see where they are on a page, and make your text fuchsia or periwinkle to be certain that your selector is actually targeting the right element in your page. It may not be pretty, but it'll help you track down problems as you code. Just remember to remove them before you publish your design.


Last, if you follow my advice and use Firefox to originally code your pages, there are some tools you can use to help. While in Firefox, go to “Tools > Add Ons” and click the “Find Updates” button. You'll be taken to Firefox's Add Ons page where you can find tons of helpful little tools that integrate into the browser.

In particular, I suggest these three:

  1. FireBug : A great debugging tool.

  2. CSS Viewer: Allows you to mouseover any element on the screen and see its class name, its ID, its properties, etc.

  3. Edit CSS : This lets you edit the CSS of your page in real time.



Q: You went on and on about how great bulleted lists are. Can we use any type of nested layout to accomplish anything similar?


A: Absolutely. The reason why so many people use Bulleted Lists for this kind of thing is because they are familiar, and they have their own formatting without CSS.


A concern that everyone should have is how the page will look with CSS turned off, or in a browser that can't interpret CSS correctly (often the case with portable devices). A bulleted list will retain its indentation and sub-levels regardless of whether CSS is on or off, so it's a good choice.


Q:: I'm having some major problems getting my bullets to line up properly between IE and Firefox. What do I do?


A: I'll admit, both browsers don't behave in exactly the most logical manner when it comes to bullet positioning.


The simplest way to combat this is to remove all left and right padding from both <ul> and <li> elements. This will make them all flush to the left, and then you'll be able to position them how you want.


Removing Spacing from Bullet lists



<style type=”text/css”>

ul.exampleClass {





ul.exampleClass li {







Another option, although a little trickier, is to “fake” your bullets with background images. You can create a background image for your <li> elements and position it so that it looks like you have bullets. This should not be confused with the “list-style-image” property.



CSS - Creating Fake Bullets


<style type=”text/css”>

ul {









li {


background:transparent url(icon.png) no-repeat;

background-position:0 5px;








Q: I set up a property for [INSERT OBJECT HERE], but it doesn't seem to be working, instead it seems to be using a property I declared later. How come?


A: Don't forget about the “Cascading” portion of “Cascading Style Sheets.” If you have a selector towards the top of your CSS, and then another one further down that may interact with those same elements, whatever comes last is what the browser will use.


An example will make this more clear.



Demonstrating “Cascading” - CSS



<style type=”text/css”>

a {







a.navigationLinks {







You might expect that any link you have on the page will be orange, but because there is also a class for links later, those links will be green. On top of that, any links with the “navigationLinks” class will actually do their best to combine both declarations! Take a look.


Demonstrating “Cascading” - In Action



Notice how the second link is bold, has a large font size and no underline for the link? That's because the properties that preceded it cascaded down. Also, because “navigationLinks” comes after the general “a” properties it overrides the color setting and uses its own.


If, for some reason or another, you need to override a style that is coming after your declaration, there is a way to get around the cascading nature of CSS.




a {
color: red !important;



a {

color: green;



Adding “!important” to the end of any declaration causes it to take precedence over any other declarations for that tag, even if they come after. In the above example, the link color would remain red even though the declaration for green comes afterwards.


It is still best to work with the cascading nature of CSS and use the !important tag only when absolutely necessary.


Q:  What the heck is a pseudo class?


A: Pseudo classes give more properties to some selectors. These were covered somewhat in the Indent Nav chapter.


Pseudo classes can be applied to most selectors on a page, with some notable exceptions in Internet Explorer. The most common use is the “:hover” pseudo element, which gives links their rollover action when the mouse is hovering over them.


Most commonly, pseudo classes are associated with links, however they can be used with other elements. Also, not all pseudo classes work in all browsers.


Example Pseudo Classes



a:link { /* Targets all links on the page */




a:visited { /* Targets all links that have been clicked */




a:hover { /* Targets any link that is hovered over */




li:hover { /* Targets any <li> that is hovered over */





The examples above are the more commonly used pseudo classes. There are many more introduced in CSS2, but since they are not widely supported they are not covered here.


The last example won't work at all in some browsers, particularly Internet Explorer. This is actually very unfortunate, because if it did support this property we wouldn't need Javascript in some cases, like to make dropdown menus.


WebGUI Templates


Q:  My style sheets don't seem be showing up in my style templates.


A: This happens most frequently if you aren't correctly targeting them. Remember, you must reference external style sheets in your template with an absolute path. You can also use the macro, ^/;, which returns the domain of the website.



For example:






would return:



Q: I've tried using a few different template variables and nothing shows up on the page. What gives?


A: 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 of figuring 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 always return false if they aren't available.


Always refer to WebGUI Help to double check which variables are available to you.


Q:  I've been working with the default templates that came with WebGUI, and after we upgraded our server all my work was erased. What happened?


A: It's very important never to modify the templates that come with WebGUI. The reason being, if Plain Black ever make a change to one of the templates in WebGUI, it will overwrite the old template in your install.


That being said, you should always make a copy of an existing template if you want to modify it.


Q:  I can't drag around any of the assets I dropped on my page after I applied a new custom page template. What's going on?


A: The most common reason for this is because a piece of important code is missing from the page layout template.




Page Layout Code





<tmpl_if showAdmin>


<tr id="blank" class="hidden">



<div class="empty">







<tmpl_var dragger.init>




This last block of code is needed to enable the dragging functionality. Without it, you will be able to add assets to a page, but you'll never be able to move them around. Just be sure that this is at the very end of whatever custom page template you've created, and you'll be fine.


Another possible answer is that you aren't actually viewing a page layout. You can view individual assets outside of a page layout, so when that happens you won't be able to drag around anything.


Remember, a page layout is just that- a layout. It lets you position content around a page. Since anything in WebGUI has its own URL, you can view any asset as its own page/content.


Q: Is there a template variable for [INSERT QUESTION HERE]?


A: First of all, remember to check WebGUI Help. There is a fairly comprehensive list of variables listed for each asset.


That being said, there are times where some variables actually aren't listed. Go ahead and play around a little and try a variable from one template and see if it returns anything in another. There are times where this is the case, and the only way to find out is to try.


There are many templates available for a specific asset, but we don't necessarily use every template variable in each of these. Edit each one and see what variables are being used.You might find something that you want to use in your own custom templates.


Q: What's this mysterious extra item listed in my navigation? I had it set to show my collaboration system and threads.


A: Chances are you just have enabled RSS for the Collaboration System. Unlike the threads that are a child of a CS, you actually can hide the RSS Asset from navigation just like you can hide any other asset.


RSS Settings



Q: I created a [INSERT TYPE OF TEMPLATE HERE] template, but it's not showing up in the dropdown menu. Where is it?


A: There is a very important field that, although small, is critical to a template functioning properly, the namespace field. Every template, regardless of what it's used for, has a namespace.


If you do not have the correct namespace associated with your template, then WebGUI will not know what kind of template you created.



There are dozens of namespaces, so it can be a little daunting knowing which one is correct for what you need. When in doubt, edit a WebGUI default template and take a look at what namespace is selected for it.


You can't change a template's namespace after you've created it, so be sure that you check out existing templates before creating your own.


Namespace for an Existing Template






Q:  I tried using getElementById but I got an error when trying to manipulate the object.


A: First, be sure you spelled the function right. On more than one occasion I have accidentally made the “Id” all capital letters.


If that isn't the issue, it could be that you are actually trying to target a class instead of an ID. Name, which was used before ID, won't work so be sure you're not using that either.


One of the most likely culprits, though, is that your javascript is running before your page has fully loaded. If you are ever going to use getElementById, make sure that you are using it in conjunction with the removed action in your body tag.


A good example would be to run a function you've created that has getElementById inside of it.


Using removed





<script type=”text/javascript”>

function exampleScript() {





<body removed=”exampleScript>







Q: What's with all this family terminology in the DOM?


A: Thinking of page elements as family members is a very high level way of looking at the DOM. Most people can understand relationships like parent, child, sibling, orphan, etc.


Look at a little XHTML and see how these relationships all work.




DOM Example




<a href=”/about_us”>About Us</a>

<a href=”/products”>Products</a>





<script language=”javascript”>

var tmp = document.createElement(“li”);




  • <div></div> - These tags are a parent of the <a> tags within them.

  • <a></a> - These two tags are both children of the <div> tag that holds them.

  • <a></a> Both of these are siblings to one another because they are at the same level.

  • tmp – This Javascript is dynamically creating an <li> element, but because it's being spontaneously created it doesn't have a parent. EVERYTHING else has a parent, but not this. Not until it gets placed into the DOM.


Q:  I'm trying to dynamically create an removed action that calls a function I created, but the script is firing without a click. What's going on?


A: This happens to me all the time. You probably put in a parentheses when you tried to assign the function to your removed event. If you put in the parentheses, the script will figure that you're actually calling the function instead of just associating it.


This is a common problem, and presents a problem as far as passing a parameter into the function that you're associating with the removed event.



Assigning a function to an object



<script language=”javascript”>

function exampleA {


var temp = document.getElementById(“exampleID”);

temp.removed = startMe;




function startMe() {







In the next line, the word this helps target the temp variable. So in a way, you are still able to pass parameters to the function. By using this, you can trace your way to any point in the DOM because you have the position.


Q: I'm having a hard time following what's happening in my Javascript. Is there a good way to track it step by step?


A: It's a very common practice to put in alert() throughout a script to track your code. In the code example above, it is used to display the content of the template variable, temp. A little code box would pop up that information.


Using alert()



<script language="javascript">

var temp = document.getElementById("example");







This example is grabbing the element by its ID, “example.” Then, just to be sure it's the right item, it's checking what's inside the tag by using alert. You can do this for any object or variable in your script, and it really can help you solve bugs that have cropped up in your script.


Results of alert()







Fantastic examples of what you can do with pure CSS layouts


The World Wide Web Consortium: the online organization that determines web standards.


  • WebGUI Help

  • Template Variables

There is no one location where all template variables are listed, but they are listed individually for each asset. Be sure to check out help for each asset if you're trying to see what variables are available. You can find Help from the Admin Console in WebGUI.


  • Macros

    There is a complete listing of macros in the WebGUI help section. You can also search for specific macros in the Community Wiki at


  • W3C Schools


The W3C put out a site that helps users learn how to use various web technologies on the web. You can learn CSS, XHTML and much more here.


  • Mozilla Firefox


If you haven't started using it yet, now is the time. This is the official website of the Mozilla Firefox browser.


Keywords: help question and answer troubleshooting

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