After spending many hours going through the core templates, I thought I'd make a list of best practices here for people to add to and update.

Perl Generation of HTML/CSS

HTML and CSS that is generated from Perl creates difficulties in creating and maintaining templates. Avoid generating HTML or CSS in Perl code. If CSS is needed, add it to the asset's stylesheet. If an asset does not have a stylesheet, add one.

CSS Inheritance

Styles (CSS) should inherit their attributes (like font-color, background-color) instead of having this defined on a per asset basis. This will make the appearance of assets more flexible and easier to work with for designers.

Inline Styles

Avoid using styles inline. This makes it difficult (and sometimes impossible) to override styles.

HTML Markup

• Use table-less markup for positioning and layout. Consider page divisions (divs), spans and other semantically appropriate tags.
• If you feel there needs to be a presentational option (e.g. - bold or italic), use a span tag instead of b, i, or strong.

Checklists

You can find more templating best practices in the HTML and CSS checklists on the site of the Template Working Group. A javascript checklist is in the works. Please take the time to use these checklists to review any new templates.

Extras

Since the extras directory can be changed in the WebGUI config file, hardcoding extras as /extras will break on some sites.  Instead, use the Extras macro to help you out:

^Extras(favicon.ico);

If your javascript needs to reference the Extras directory, then you can take advantage of some javascript that is automatically added to each page.

getWebGUIProperty('extras'); //Get Extras directory, absolute path

If your CSS needs to reference the Extras directory, and it's a static file from the Extras directory, use a relative path.  If your CSS is served up with a Snippet asset, then use the Extras macro.

Gateway

The gateway macro will prepend the user's choice of gateway URL from the config file to a URL.  In it's simplest usage it's used like this:

^/;myStyle.css

However, if the user has turned on Prevent Proxy Cache in the Settings, the gateway macro will also add a randomized URL fragment to prevent proxies from caching content.  In the simple usage, the URL ends up looking like this:

/?noCache=12349asfdsdjmyStyle.css

That of course, is completely broken.  Admittedly, not very many people use Prevent Proxy Cache, but especially with core templates all options have to be covered.  To get around this problem, pass the URL to the Gateway Macro, and it will do the right thing:

^/(myStyle.css);

Internationalization

Please avoid hardcoding English (or any other language) text in templates.  Use the International macro to pull entries from WebGUI's i18n system

Submitting Templates

Templates should be submitted on a per template, or per folder basis if there are multiple templates being updated in a folder.  Please do not create a temporary folder to hold all changed templates.  It is more work for the developer to move them all into the right place and remake the packages than it is for the packages to be exported one at a time.

Each set of templates should be submitted as a bug to the bug board.  For good documentation, it would be best if each package had its own bug, but use your own judgement.  The changelog entry will be based on your bug title, so choose a good, descriptive one.

Templates should be developed against the latest version of WebGUI to make merging easy on the developer who commits them.  If the template isn't developed against the latest, please describe what changes were made, and which version the template was developed against.

If the template completely replaces a template, we need a gotcha entry describing why the old template is obsoleted.  See the link above for an example.  General guidelines for gotcha entries:

• One entry for each template, or class of templates.
• Why was it changed, or deleted?
• If deleted, what template should users use in its place?

It's the developer's responsibility to build any upgrade subroutines necessary to delete and/or do search and replace operations on templates.

All templates have to pass the WebGUI test suite, which tests for broken i18n labels and bad macro usage.  If you follow the guidelines above, you should have no problems.  It's best, however, to get the templates submitted as early as possible so that hard deadlines aren't missed.