plainblack.com
Username Password
search
Community Support
WebGUI User Guides
Wiki
Forums
Report A Bug
Request Features
WebGUI TV
Add-ons and Plug-ins
Service Providers
webGUI in the news
Karma
API Docs
the people behind wg
webgui worldwide
Mascot
wallpapers
powered by icons
Sightings
WebGUI 8
Bookmark and Share
Subscribe

How To Give WebGUI Your Own Style

Table Of Contents

Introduction 

This is anything but a short article, so be ready for a long haul. We're going to cover a lot of ground on how to make WebGUI behave the way you want it to. This article is aimed at the same sort of person I was at the beginning of Jan, 2007: I've installed WebGUI. Now what the heck do I do with it? How do I make it look like I want it to look, and not how Plain Black wants it to look? As a result, the first few sections cover some terminology that more experienced people probably don't need. Instead, they want to head straight to Bringing It All Together, to show the actual process of creation and installation from beginning to end.

Beginning Outside of WebGUI 

First, though, we have to cover one very important thing: Making WebGUI look like your site really means creating a stylesheet, along with HTML, which defines how your site will look. As a result, I'm going to recommend starting your work in a very non-technological way: Get out a pen and paper, and draw on it, until you have an idea how you want your site to look.

After you've got your drawings, make the graphics that you need to. Personally, I use the GIMP, though many people prefer Photoshop, or other tools. After you have the graphics, you will need to make the HTML and CSS for your site. Personally, I find ViM(for making the original .html and .css files) helpful, along with Mozilla Firefox and Firebug. Using the latter two items will let you view your site and edit the CSS right in the browser, live, and view the results, without the usual "edit/save/reload" process you would normally have to go through. Naturally, we can't ignore Internet Explorer, so for debugging the CSS/HTML/etc. on that browser, you will need IE Web Developer (alas, not a free plug-in).

Only after you've completed all of the above are you ready to begin the process of making the style templates in WebGUI. 

Pre-Requisites

Commit/Clear/Reload

This process is quite important, and you will use it a great deal, so take some time to get comfortable with it now.

Version Tags

First up, you need to know about version tags. Simply put, you are able to go back in time to how a website looked at a specific date and time. Because of this, WebGUI must  keep track of the work you do while you are doing it. It does this by creating something called a version tag.

As you work on your site, editing and saving your work, your work is, basically, put in a "pending" state. One way of looking at this is to say that webgui internalizes the development/qa servers, allowing you to work on the production site without worry of how you will affect the users of your site. All of your changes are given a label. If you do not specify the label yourself, then WebGUI will create one for you when you first save something. It will usually be named something like "username date time".

As you can imagine, an article as long as this one could be written about version tags. However, you're not really here for them, so I'm giving the you bare minimum to deal with them while customizing your site. When you have a version tag, you will be able to see it under your "Admin Console", under the heading "Version Tags". You will need to know that you have one before you can commit it.

Commit Your Work 

In order to make your changes apparent to other users of your site, you must commit your work. Fortunately, this process is much easier than understanding version tags, and takes only a few steps.

  1. Turn on "Admin Console"
  2. Click "Version Tags"
  3. Click "Commit My"
  4. Enter a comment in the text area which shows up.
  5. Click "Save"

Your work is now visible to other users of your site. This is the "Commit" part of the process being documented: "Commit/Clear/Reload".

Clearing The Cache

After committing your work, your changes might not be visible to all users of your site immediately. This is due to the object cache, which WebGUI uses to dramatically speed up page load times for your users. Normally, this is a good thing. When making changes like these, though, this can be distracting for you.

To clear your cache, take the following steps:

  1. Turn on the "Admin Console"
  2. Click "Cache"
  3. Click "Clear Cache"

That's it, your cache is now emptied, and WebGUI will force all pages it serves to be rebuilt. This is the "Clear" step of "Commit/Clear/Reload".

Reload Your Browser Window

This part probably goes without saying, but it will be said anyway for completeness: Browse to the page you've modified, and click "Reload".  You should now see your updates.

This is the "Reload" part of "Commit/Clear/Reload".

From now on, anytime you need to do this process, I will simply tell you to "CCR", which is short for "Commit/Clear/Reload".

WebGUI Templating Language

A common enough question regarding WebGUI is something like "What programming language do I have to learn to make my own templates?". You don't have to learn any programming language. Instead, you learn the WebGUI templating language.

Well, it is the templating language for WebGUI, but that's kind of overstating things. It's a normal templating language, and very easy to deal with, and is used outside of WebGUI as well. It's called HTML::Template. Go and read some of the articles about it (linked to from the HTML::Template site), and you'll see. It's easy to deal with, but you do need to know it in order to make sense of what's coming up soon.

Assets

Assets are what WebGUI is all about. Specifically, WebGUI is about managing the pieces that make up your website, and providing an easy way to build some very complex pieces. In this discussion and tutorial, we won't cover even 1% of the possibilities. Instead, we will focus on some very core items, so that you can understand the pieces you need to to make your site.

Basically, everything on your site is an asset. Every file, every image, every snippet of CSS, or HTML, or Javascript, every calendar, every article, absolutely everything that you would present to the user (or to you) is an asset. WebGUI is what makes managing those assets feasible.

Now, broadly speaking, there are two types of assets: Container Assets and Displayable Assets. We will not cover all of the Displayable Assets. I recommend purchasing the official training guides and books from PlainBlack. In addition, the WebGUI Wiki (which is what you're using right now), is extremely useful and almost always has the information you require. Just search for it!

So, what is the difference between the two? Container Assets hold all of your Displayable Assets. Container Assets include "Page Layout", "Folder", and "Dashboard" (an advanced topic, and one we won't pursue for this discussion). Displayable Assets include "Page Template", "Snippet", "Image", and others.

"Page Layouts" are what many other sites would consider to be a page. For instance, you might be looking at http://www.webgui.org/support/ at some point. That would be a "Page Layout" in WebGUI terms. While browsing through there, you would find a section named  Contibutions, then Packages, then Burned. After clicking on the Burned package, you would finally find yourself looking at an "Article", along with other Assets (to hold the package, a forum, and the like).

This point cannot be overstated: Page Layouts contain Assets, and are generally what are given out as URLs to your site. Remember this above all else. Your Assets go on Page Layouts.

"Folders" contain just about everything, including Page Layouts, Snippets, Articles, Images, and everything in between. They are a handy way to organize your site. We will be showing how to use these assets by example, later in this article. 

Macros

Macros are not Assets, not by the definitions we used above. Macros are a part of WebGUI. You can make your own Macros, but that is definitely a topic for another time. For now, we are going to cover a set of Macros that we will use heavily in making our own style, and making WebGUI use that style. Note that this is just a listing of the macros, not a full "how to use" guide. We will use every one of them in the final section, "Bringing It All Together". Here, though, you have links to the online help files, along with basic information on what each one is, and why you might need/want it.

AssetProxy : One of the two most used macros you can/will have in your template. This will put the appropriate code for the Asset right into your page. This is useful for putting in images, calendars, wiki's, etc.

FileUrl :  The other of the most used macros you can/will have in your template. This will only put the uURL of the asset into your page, and will not add in any necessary HTML code to make it work. For instance, this is a great way to do your own link to an image, but using it to place a Navigation will only do you harm.

There is one other important difference between AssetProxy and FileUrl, though: FileUrl gives exactly the URL of a file. When the web browser receives this information, it will request the file url itself from WebGUI. This has the benefit of bypassing an access to the database, thereby helping the page load slightly faster for the user, and reducing load on the server. If you are putting an image onto a page, then FileUrl might save your web server some small effort. On the other hand, if you're putting in a Collaboration system, you probably need to use AssetProxy anyway.

L : This is how to place a login box on the page, so the user can login. Pretty important to allow them to modify the site more easily later. 

AdminBar : This code is what handles displaying the Admin Bar, which is the set of controls that allow you to place new content, modify existing, etc. This macro should be placed right after your opening <body> tag. This macro is not enough to ensure the user can display the Admin Bar! Make sure to insert the AdminToggle macro (covered next).

AdminToggle : This macro is what is responsible for showing the link to allow the user to turn the Admin Bar on and off. Generally speaking, you will place this near to the ^L; macro.

c : This macro displays the company name, as defined in the Site Settings. Most often, this will be useful in a footer, as part of a copyright statement. At least, that's how I've used it most often, so far.

PageTitle : Using this macro, you can insert the title of the page. Very handy when writing your <title> tags, and quite possibly as a page element.

/ :  This will insert the URL of the root of your site. For instance, if your site is actually under your home directory on the server homes.webgui.org, it will paste the URL http://homes.webgui.org/~yourhome/ into the output. Very handy in menus, or as a way to specify where to find a stylesheet (i.e.: <link rel="stylesheet" href="^/;style.css" type="text/css">)

Modifying the Body of the Style 

When making your site, there are two critical pieces that you simply must add. Failure to add them will, in fact, prevent your site from working in any way, shape, or form. Namely, two magic lines of code. Well, not so magical if you remember that WebGUI is a very specialized use of HTML::Template. You need to insert two template variables into your style template, and that will make your page display the way you expect.

In your <head> section, add the following line, right after your <title> tags:

<tmpl_var head.tags>

In your body section, find the location for where WebGUI should put its output from the page, and insert this line:

<tmpl_var body.content>

After doing that, you will see the site behaving the way you would expect. 

Installing Your Template 

Create The Folder (Root/Themes)

Everybody has their own opinion on where their themes should go. My standard is for any of my themes to be installed in a folder named "Themes", under the Root Folder. So, here's how to do make that folder.

  1. Login to your site, and click "Turn Admin On"
  2. Click on "Admin Console", then "Assets"
  3. In the upper left corner of the screen, click "Root"
  4. In the "New Content" menu, click "Folder"
  5. Set the title to "Themes", and all other values in all other tabs should be able to be left at default values. Do make sure that, in the "Security" tab, the "Who can view" dropdown is set to "Everyone".
  6. Click "Save".

We are now going to make the place where your new theme will reside.

  1. Click on your "Themes" folder.
  2. In the "New Content" menu, click "Folder"
  3. Set the title to be the name of your theme. Make sure that "Who can view" under "Security" is set to "everyone", and then hit "Save"
  4. Commit/Clear/Reload 

Upload images

You will almost always be uploading multiple images. As a result, this article will only explain how to use the "File Pile" to upload a pile of files. It really does make it easier to upload the 4 to 10 images common for many themes.

  1. Login to your site, and click "Turn Admin On"
  2. Click on "Admin Console", then "Assets"
  3. In the upper left corner of the screen, click "Root"
  4. Click "Themes"
  5. Click the name of your Theme
  6. In the "New Content" menu, click "Folder"
  7. Set the title to be "images", and set the url to be "themenameimages" (makes it easier later to refer to your images in your CSS file).
  8. Make sure that "Who can view" under "Security" is set to "Everyone", and click "Save"
  9. Click on "images"
  10. In the "New Content" menu, click "File Pile".
  11. Make sure that "Who can view" under "security" is "Everyone".
  12. Under "Properties", click "Browse", and select a file. When you do so, you will have a second line appear to allow you to "Browse" for a second file. That then opens a third, and so on. Use it to select all your images.
  13. Click "Save"
  14. Commit/Clear/Reload

The images for your theme are now ready for use.

Add Navigation

Add Navigation Control

Adding in a Navigation to your theme is one of the most critical pieces of your theme. Without it, people will not be able to navigate your site (well, unless you use only static menus hardcoded into your theme, but that makes it impossible to distribute very well). 

The first thing you must do is navigate to your theme's root folder. Take these steps.

  1. Login to your site, and click "Turn Admin On"
  2. Click on "Admin Console", then "Assets"
  3. In the upper left corner of the screen, click "Root"
  4. Click "Themes"
  5. Click the name of your Theme
  6. In the "New Content" menu, click "Navigation"

After doing the above, you will be presented with a moderately complex screen. Let's cover the options, one at a time:

  • Title: Give your navigation a name. My standard is "Theme Name - Navigation"
  • Menu Title: Leave Blank
  • URL: Fill this in. You will need it to be able to specify your Navigation in your theme later. My standard is "themes/themename/menu"
  • Description: Blank
  • Start Point Type: This can take any of three values. This is necessary as this control can show menu items from farther down the URL tree you will build for the rest of your site, and you want to make sure you specify what items can appear in the menu.
    • Specific URL: You can specify the location where to start scanning. This can be any URL on your site.
    • Relative To Current URL: This will always start scanning at the page the user is viewing.
    • Relative To Root: This will always start scanning at the top of your site.
  • Start Point: This will allow you to specify where to start scanning. For instance, if you chose "Specific URL", you would place that URL here. If you chose "Relative To Current URL", you would choose modifiers for the current URL here (such as "go up 3 levels", or "just start here"). Feel free to experiment with this to get it just right.
  • Relatives To Include: Specify which other pages to include in this Navigation
    • Ancestors: Show the ancestors of the current page
    • Self: Show the current page
    • Siblings: Show pages which are at the same depth as the current page, and in the same folder as the current page.
    • Descendants: Show pages which are children of the current page.
    • Pedigree: Show all pages which would be clicked to get to this page, in the order in which they were clicked.
  • Descendant End Point: How deep should this Navigation scan for pages? This will let you specify that answer.

Make sure that "Who can view" under "Security" is set to "Everyone", and then click "Save". You are now ready to attach this Asset to your Page Layout.

Add Navigation AssetProxy To Page Template

This step will be done outside of WebGUI. Open up your HTML page in your HTML editor, and find the place where your menu will go. Insert the following there: 

^AssetProxy(themes/themename/menu);

That will put your menu on your page when it is displayed. Make sure to save your HTML file now! 

When/Why To Use Snippets, and What Are They?

This section might seem out of place, but it has a direct bearing on the following sections, so we're going to interrupt this article to discuss a snippet. So, what is a snippet? A snippet is a segment of HTML, or CSS, or JavaScript, or even just plain text. It is referred to as a URL, but the contents of it are stored in the database. The difference between a Snippet and a File is that a File is stored on disk, with references in the database. A Snippet is stored right in the database.

That's the backend differences. The frontend differences, though, are more readily visible. If you need to update a file, you have to browse to the file, upload a new copy, and overwrite the old. A snippet gives you an editor right in the browser, and lets you edit there. For ease of use, I prefer the snippet, though others prefer a file. I will be recommending a Snippet for the following pieces.

In all cases, the way to make a snippet will be fairly familiar to you by now. Here's the process.

  1. Login to your site, and click "Turn Admin On"
  2. Click on "Admin Console", then "Assets"
  3. In the upper left corner of the screen, click "Root"
  4. Click "Themes"
  5. Click the name of your Theme
  6. In the "New Content" menu, click "Snippet"

Give it a Title, give it a URL, and insert the contents of the Snippet in the editor window. Turn off "Process as template", and set the appropriate mimetype. Update the "Who can view" in "Security" to "Everyone", and hit Save.

As an added benefit of the Snippet, once you update the Snippet in one place, all places which refer to that Snippet are updated, without your needing to do any work. 

When/Why To Use Templates, and What Are They?

Templates are the meat of making your own themes. Without them, you will not get a theme to work correctly. If you make them incorrectly, your theme will not work. They are extremely important. Fortunately, they are also extremely easy to make, and to make correctly. 

  1. Login to your site, and click "Turn Admin On"
  2. Click on "Admin Console", then "Assets"
  3. In the upper left corner of the screen, click "Root"
  4. Click "Themes"
  5. Click the name of your Theme
  6. In the "New Content" menu, click "Template" (in the current version, at the very bottom of the "New Content" menu)

You will now do some very common steps: Give it a title, give it a URL, make sure "Who can view" in "Security" is "Everyone".

There is a major "gotcha" which happens right here: If you do not set "Namespace" to "style", then you will be unable to use this template as a template. Make certain you set "Namespace" to "style"! Furthermore, you only get one chance to do this right! Failure to do this will result in your having to remake your template!

Also under "Properties", you will have a text editor window. Copy and paste the HTML which comprises your template into here, and hit Save. You'll now be able to specify this as your style for your site, or for anything which can use a style. 

Add Navigation Template (if necessary)

You might not need to do this. You might be happy with the default Navigation Template chosen when you added the Navigation Control. If, however, you are not happy with it, you will need to choose another.

  1. Login to your site, and click "Turn Admin On"
  2. Click on "Admin Console", then "Assets"
  3. In the upper left corner of the screen, click "Root"
  4. Click "Themes"
  5. Click the name of your Theme
  6. Click on the "navigation" Asset, and then click on the "Display" tab.

Now, choose a different "Display Style". If none of the other "Display Styles" suits you, you will need to make your own. Making your own Navigation template is beyond the scope of this article, and definitely fodder for another one. While not overly complex, you will need to be able to handle some very minor coding in HTML::Template.

Copy/Paste CSS

First, make sure you have updated your CSS file that you've created back in the Pre-Requisites. You must change all URL's to use the appropriate FileUrl macro's. For instance, this line of CSS code:

background: #000000 url('images/a1.jpg') top left no-repeat;

becomes this line of WebGUI template code:

background: #000000 url('^FileUrl(images/a1.jpg);') top left no-repeat;

Double-check to make sure you are not using any other Assets in your CSS code, and then create a snippet in your Theme folder, and paste the contents of your CSS file as your snippet. Make sure you pay attention to your URL, as you will need it in the next section. 

Copy/Paste Template

Finally, the part you've been waiting for: Actually installing your newly converted theme!

Create a new Template in your Theme folder, and paste the HTML into the template window. Make sure you've inserted all your macro's properly, as this is where all your work comes to fruition.  For a better example of what I mean, check out Bringing It All Together, and you will see a complete list of the edits that were made to the source HTML file to make it work.

Now, don't forget to Commit/Clear/Reload! 

Apply To Entire Branch

At this point, you've got your theme installed, and want to see how it will look.

  1. Login to your site, and click "Turn Admin On"
  2. Click on "Admin Console", then "Assets"
  3. In the upper left corner of the screen, click "Root"
  4. As we are assuming this is a brand new install of WebGUI, we are going to apply the theme to the "Home" folder under "Root". Click the word "More" on the same row as "Home", and then click "Edit Branch" on the popup menu.
  5. Click the "Display" tab.
  6. Set the "Style Template" to be your theme.
  7. Underneath/next to "Style Template", set "Change Recursively" to "Yes"
  8. Click "Save"
  9. Commit/Clear/Reload

Your theme is now applied, and your site will look the way your theme allows it to. However, you are not yet done! Follow the next section. 

Apply to User Functions (Under Admin/Settings/UI)

When an error occurs (for instance, the user attempts to login, and gives the wrong password), a User Function page is brought up. By default, WebGUI uses its own style for that page. We want it to use the new style that you've just applied.

  1. Login to your site, and click "Turn Admin On"
  2. Click "Settings" under "Admin Console"
  3. Click the "UI" tab.
  4. Change "User Function Style" to the new style you have just created.
  5. Click "Save"

Now you're done. Your style is made, installed, and in use throughout your site. As long as you work under the Root/Home folder, your style will automatically be used. If you make another folder under Root, and expect it to be used, you should apply your style (using the "Edit Branch" technique) to it, as well, to keep the overall look and feel uniform.

Next, we'll work together to build a complete style, working by example.

Bringing It All Together: Conversion By Example

Right about now, your reaction should be something like "Great. So what in heck do I do with all of this information?" We're now going to work our way through a conversion together. We need a common starting point, so let's use an existing open source theme. In this case, I've chosen Sundark. We'll take the zip file, analyze it, make some artistic changes (which we need to make for WebGUI), and create a theme. We'll apply it to our site, make sure it gets used everywhere on our site, and then export it as a package, for upload to the WebGUI Contributions Packages Section.

Now, before I continue, I'd like to point out why I chose  Sundark. It's simple. The entire uncompressed archive takes up 28K of disk space. Of that, 20K goes to the graphics. For the CSS and the HTML files, there's a total of 137 lines. The display is minimalist. We can focus on the conversion process, rather than on debating the artistic merit of the style of navigation, etc. So, even though Sundark might not be the most beautiful theme, for these purposes, it is perfect.

Artistic Examination

As with any conversion, we first have to identify what we are going to do, and then perform the steps to do it. So, first, let's examine a screenshot of the theme, before we have done anything:

Unmodified Sundark Theme

Now, in order to make this work for WebGUI, we need to have five elements. More are fine, but these five are pretty much mandatory:

  1. A place to allow somebody to login.
  2. A place to identify the site/company.
  3. A way for people to navigate.
  4. A place to put the title of the page.
  5. A place to put our body content.

I've already modified that screenshot to show the first 4 elements (highlighted), and the last one, the body, should be fairly self-evident (if not, it's all the Latin text).

Marked Up Sundark Theme

You'll notice that I had to make a place for somebody to login. I chose what seems to be a fairly empty place in the banner of the page. What can I say? It seemed good to me.

I'm also changing the "Pagename" section to reflect the site name. I wanted to put the Page Title in place of the word "Content", and that made things fairly redundant unless I changed "Pagename". Having the site name display is a good thing, and I didn't have any other location jump out at me as being a good one, so there you have it.

The Navigation was already placed, so I just used the original placement location. 

Modifying the CSS

First, we need to set up the section for the login box/display. Add the following CSS code to the end of the file:

#login {
color:#000000;
font-family:verdana,tahoma,arial,helvetica,"sans serif";
font-size:8pt;
margin:0cm 0cm 0cm 11cm;
padding:0px 0px 4px;
}
#login a {
color:#000000;
font-weight:normal;
letter-spacing:0px;
margin-right:18px;
font-size: 8pt; 
}
.loginBox {
display:inline;
font-size:8pt;
}
.loginBox input {
margin-top: 0.75cm; 
font-size:8pt;
}

Now, we have to adjust the URL's in the file. Since we're going to be putting them into the "images" folder, we're going to be making noticeable changes. Find the two URL's listed below (they are at very different sections of the file):

background-image:url(header.jpg);
background-image:url(footer.png);

And now we will change them to the following:

background-image:url(^FileUrl(sundarkimages/header.jpg););
background-image:url(^FileUrl(sundarkimages/footer.png););

There is one other change, but this one does not make sense for now, mainly because it is something that is found after trying things out. Find the section for ".title" and change the "padding-top: 160px;" to "margin-bottom: 15px;" This is due to the addition of the login box that we need to make this adjustment. 

And, finally, save the changed CSS file. We're done working with this file for now. We'll need it again in a few more minutes, though.

Modifying the HTML

Find this line:

<title>www.rotw.de.ki | Template</title>

Replace with this line:

<title>^c; | ^Page("title");</title><tmpl_var head.tags>

Find this line:

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

Replace with this line:

<link rel="stylesheet" href="^/;themes/sundark/style.css" type="text/css" />

Find this line:

<div id="all">

Insert immediately before it:

^AdminBar;

Find this line (it ends with an "a href" tag, but the wiki tries to convert it, so I can't place the tag here):

<span style="float:right;margin-right:5px;display:inline;">

Get rid of all <a> tags between it and the closing </span> tag.

Insert this line between the opening and closing <span>:

^AssetProxy(themes/sundark/menu);

Immediately after the closing <span> tag, place the following code:

<div id="login">
        ^L("","","PBtmpl0000000000000092"); &middot; ^AdminToggle;
</div>

Find this line:

<div class="title">Pagename</div>

Replace with this line:

<div class="title"><a href="^/;">^c;</a></div>

Find this line:

<h1>Content</h1>

Replace with this line:

<tmpl_var body.content>

Find this line:

<div id="footer">&copy; 2007 Pagename | Design by <a href="http://www.rotw.de.ki/" target="_blank">RotW</a></div>

Replace with this line:

<div id="footer">&copy; 2007 ^c; | Design by <a href="http://www.rotw.de.ki/" target="_blank">RotW</a></div>

Now, save the HTML file. We're done working outside of WebGUI, it's time to get into it and make all our pieces. 

Making The Folder 

This is fairly straightforward: We want to place the newly created theme in one place, with all of the pieces of the theme, so that we can easily manage the theme later. 

  1. Login to your site, and click "Turn Admin On"
  2. Click on "Admin Console", then "Assets"
  3. In the upper left corner of the screen, click "Root"
  4. If you don't already have a Folder named "Themes", do this:
    1. In the "New Content" menu, click "Folder"
    2. Name it "Themes"
    3. Set the URL to "themes"
    4. Under "Security", set "Who can view" to "Everyone"
    5. Click "Save"
  5. Now, click on your "Themes" folder. Your path (across the top) should now read "Root > Themes"
  6. In the "New Content" menu, click "Folder"
  7. Name it "Sundark"
  8. Set the URL to "themes/sundark"
  9. Under "Security", set "Who can view" to "Everyone"
  10. Click "Save"

Adding the Navigation 

Now, we need to define the Navigation for this theme. I strongly recommend re-reading the info in this article about the Navigation control now.

  1. First, make sure you are in the Assets view of the Admin Console, and then make sure your current folder is Root > Themes > Sundark.
  2. In the "New Content" menu, click "Navigation"
  3. Set the title to "Sundark Navigation"
  4. Set the URL to "themes/sundark/menu"
  5. Set "Start Point Type" to "Relative To Root"
  6. Set "Start Point" to "/ (0)"
  7. Set "Relatives To Include" to "Descendants"
  8. Set "Descendant End Point" to "Infinity"
  9. Click "Display"
  10. Set "Navigation Template" to "horizontalMenu"
  11. Set "Display Title" to "No"
  12. Under "Security" set "Who can view" to "Everyone"
  13. Click "Save" 

Installing Images

Now, we upload the images. First, though, we need a place to  store the images.

  1. Login to your site, and click "Turn Admin On"
  2. Click on "Admin Console", then "Assets"
  3. In the upper left corner of the screen, click "Root"
  4. Now, click on your "Themes" folder. Your path (across the top) should now read "Root > Themes"
  5. Now, click on your "Sundark" folder. Your path (across the top) should now read "Root > Themes > Sundark"
  6. In the "New Content" menu, click "Folder"
  7. Name it "Sundark Images"
  8. Set the URL to "sundarkimages"
  9. Under "Security", set "Who can view" to "Everyone"
  10. Click "Save"

Now, to upload the files.

  1. Click on your new "Sundark Images" folder.
  2. In the "New Content" menu, click on "File Pile"
  3. Click "Browse", and find your file. A second  line will appear, allowing you to click "Browse". You want to upload footer.png and header.jpg  . Once you have selected both, click "Save".

You're done, your images are now uploaded.

Installing CSS

Now, we need to supply the CSS file for this theme.

  1. Login to your site, and click "Turn Admin On"
  2. Click on "Admin Console", then "Assets"
  3. In the upper left corner of the screen, click "Root"
  4. Now, click on your "Themes" folder. Your path (across the top) should now read "Root > Themes"
  5. Now, click on your "Sundark" folder. Your path (across the top) should now read "Root > Themes > Sundark"
  6. In the "New Content" menu, click "Snippet"
  7. Set Title to "Sundark Style.css"
  8. Set URL to "themes/sundark/style.css"
  9. Set the "MIME Type" to "text/css"
  10. Leave "Process as template" set to "No"
  11. Copy and paste the contents of your style.css file into the editor window.
  12. Click "Save"

Your stylesheet is now ready to be used by your theme.

Installing HTML

  1. Login to your site, and click "Turn Admin On"
  2. Click on "Admin Console", then "Assets"
  3. In the upper left corner of the screen, click "Root"
  4. Now, click on your "Themes" folder. Your path (across the top) should now read "Root > Themes"
  5. Now, click on your "Sundark" folder. Your path (across the top) should now read "Root > Themes > Sundark"
  6. In the "New Content" menu, click "Template" (towards the very bottom in my installation).
  7. Set Title to "Sundark Template"
  8. Major gotcha: Set "Namespace" to "style". Your theme will not work otherwise! Furthermore, you only get one chance to do this right! Failure to do this will result in your having to remake your template!
  9. Copy and paste the contents of your index.html file into the editor window.
  10. Click "Save"
  11. Clear/Commit/Reload

Okay, your template is installed, and ready to be used. Now to apply it.

Final Application To Site

  1. Login to your site, and click "Turn Admin On"
  2. Click on "Admin Console", then "Assets"
  3. In the upper left corner of the screen, click "Root"
  4. Click the "More" link on your "Home" folder, and click "Edit Branch"
  5. Click the "Display" tab.
  6. Set the "Style Template" to be "Sundark Template".
  7. Underneath/next to "Style Template", set "Change Recursively" to "Yes"
  8. Click "Save"
  9. Commit/Clear/Reload
  10. Click "Settings" under "Admin Console"
  11. Click the "UI" tab.
  12. Change "User Function Style" to "Sundark Template".
  13. Click "Save

Your site will now have the Sundark look applied to it throughout the site.

Exporting .wgpkg File

So, now that you have your theme built and in use for you, what if you wish to distribute your theme? For instance, maybe you've converted a design from Open Source Web Designs, and want to let other people use it as well. Here's how.

  1. Login to your site, and click "Turn Admin On"
  2. Click on "Admin Console", then "Assets"
  3. In the upper left corner of the screen, click "Root"
  4. Now click "Themes"
  5. Click "Edit" on the Sundark line.
  6. Click on "Metadata", and set "Make Package" to "Yes".
  7. Click "Save"
  8. When you return to the Assets view, you will see a section named "Packages". "Sundark" will be in the list. Click the "Export" link.
  9. Save the resulting file with the name "Sundark.wgpkg"

Now, you can distribute this file to other users of WebGUI, including posting it at the Plain Black Package Contributions page.

Testing .wgpkg File

Now, the last thing you need to do is to test your .wgpkg file. You need to have a way to make sure that when somebody else installs it on their site, they can see the entire theme, and have it work correctly. Fortunately, this is easy to do, thanks to Plain Black. Visit the Online Demo page, and set up a new demo. After doing so, take the following steps.

  1. Log in as Admin.
  2. Turn on "Admin Console", go to Assets.
  3. Make a new folder under "Root", called "Themes". Enter that folder.
  4. Under the "Packages" area, click "Browse". Select your .wgpkg file.
  5. Click "Import"
  6. Now, using the techniques listed above, apply the theme to your Root/Home folder.
  7. Commit/Clear/Reload

You can now see the result with your own eyes as to whether or not others can use your theme.

Conclusion

As promised at the beginning, we covered a lot of ground. I hope this has been helpful to you in learning how to make your own templates, and make your site look the way you want it to look.

The files for Sundark can be found in the contributions section of the Plain Black web site.

I'd like to thank the participants of the IRC channel, as they gave me lots of information when I was trying to work out how to do my own templates, and basically taught me what I needed to know in order to make them work. Thanks to them, this page became possible.

If you wish to email me directly, you may do so at m.pedersenNO@SPAMicelus.org.

Keywords: howto layout style theme

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