TemplateAndCssGuidelines

A brief guide to maintaining highest standard templates and CSS

Created by: Anonymous, Last modification: 09 Jun 2010 (09:12 UTC) by Tochinet

Notes

we have dedicated a lot of our time to tidy up our php, templates and css, which seems to be greatly appreciated by anyone who decides to delve into the guts of bitweaver.

to maintain this high standard and make it easy for new developers to understand what is going on, we would like to ask you to stick to these few simple rules:

  • please maintain all indenting in the template files. i know everyone has different ideas of what the real way to do intenting is, but the bitweaver way is to indent using tabs, every nested tag is indented and smarty block commands are treated like html tags in terms of indenting. if you are worried about excess white space, it is stripped using the {strip} tags in virtually all templates.
  • please try to reuse css classes. try to make yourself familiar with how classes are used in bw by viewing some template files and by visiting pages such as ThemeTutorial and CssSchema. we have been working with bitweaver for quite some time now, and there has been virtually no occasions where we've had to introduce new classes. hell, we even have individual classes for every single wiki page.
  • if you should feel that you need more classes to get the styling you require, you might want to consider creating a custom theme where you store your custom template files.
  • please try not to add definitions to base.css unless you've tested the changes with all themes that use it. this file is used by several other themes and other users might not appreciate your custom settings.
  • this point i cannot stress enough: check your html code on w3c! if you think it's tedious, use a browser like firefox and use the web developers extension. better yet, use opera, and hit <alt><ctrl><v>, which will upload the file to w3c and get it checked (since it uploads the file automatically, you can even use a local URL). the link to the validator is: http://validator.w3.org/

it would be a shame to see sloppy php / html code being reintroduced into this rather quite clean code again, after having tidied it up.

How-To

Here are basic instructions on how to build your template, using Bitweaver standard Smarty tags.

The Beginning

Firstly, we want the template all indented correctly, but don't want the whitespace - so we use the {strip}...{/strip} tags to surround the template, from top to bottom.

{strip}


Next, is the {bithelp} tag. this will hopefully be a link to online help docuemntation at some point. it is currenlty not maintained well, but will be important in the future.

<div class="floaticon">{bithelp}</div>


Ok, now the fun begins. The first thing we want is an all-encapsulating < div> to help format the panel. We normally include a CSS class of the type of page and the same name as the package here, to help with per package look-and-feel.

<div class="admin galaxia">


Within this ))
((, we now start the header section of the page and place the title of the page within < h1> tags. We use the {tr}...{/tr} tags to translate text for different languages.

<div class="header">
    <h1>{tr}Admin process roles{/tr}</h1>
</div>


Body

Next we open the BODY section of the page.

<div class="body">


In this example, we have a navigation bar and set of error message that will only appear if editing content. We use the {formfeedback} tag to iterate through an array and present the information as a list.

{if $pid > 0}
    { include file="bitpackage:Galaxia/process_nav.tpl"}
    {if count($errors) > 0}
        <div class="error">
            {tr}This process is invalid{/tr}:

            {formfeedback hash=$errors}
        </div>
    {/if}
{/if}

Some templates rely on the use of solely {formfeedback} which is quite a clever function since it only displays information when it's handed information:
no need to check for contents of the array:

{formfeedback hash=$feedback}


Tabs

Ok, more fun! We use Javascript tabs throughout Bitweaver to provide an intuitive and standardise navigation environment. The {jstabs} tag will surround all content on the page that will appear in separate tabs. If any information is to appear below, for every tab, it will be outside the closing tag. The {jstab} tag (notice the singular) begin an individual tab with title. We do not use {tr} tags around the title, as they are provided by the tag.

{jstabs}
    {jstab title="Create / Edit Role"}


Forms

We use {form} tags to simplify and standardise the forms used in Bitweaver. The legend parameter provide a title to our form.

{form legend="Create / Edit Role"}


The following hidden parameters are used by the sorting and filtering components below. As a standard, we specify these early on in the form.

    <input type="hidden" name="role_id" value="{$info.role_id|escape}" />
    <input type="hidden" name="pid" value="{$info.p_id|escape}" />
    <input type="hidden" name="offset" value="{$offset|escape}" />
    <input type="hidden" name="where" value="{$where|escape}" />
    <input type="hidden" name="find" value="{$find|escape}" />
    <input type="hidden" name="sort_mode" value="{$sort_mode|escape}" />
    <input type="hidden" name="sort_mode2" value="{$sort_mode2|escape}" />


Next are the individual form inputs. This is our standard layout, using {formlabel}, {forminput}, and {formhelp} tags to simplify look-and-feel.

    <div class="row">
        {formlabel label="Description" for="description"}
        {forminput}
            <textarea rows="5" cols="60" name="description" id="description">{$info.description|escape}</textarea>
            {formhelp note="A brief description about the purpose of the role"}
        {/forminput}
    </div>


{formlabel}
<label> is used to link a text filed to a particular input field using an id. in the above example, the label links to the input filed that has the description id.
formlebel simplifies and standardises the use of <label for="" />. this should make the use of labels easier in bitweaver and should improve access for handicapped people since it allows the user to determine what text elements belong to what input fields.

{forminput}
the forminput simply inserts a div class around the input area with the correct class names. the reason why we use this, is that we can potentially exchange all div driven forms with tables and it should simplify upgrading to XFORMS in the future.

Submission
Next, is our SAVE button and closing the form. Similar to the form inputs. The {smartlink} tag is used to simplify the insertion of html links. originally created for the simple insertion of links in tables to create links for sorting tables.

    <div class="row submit">
        <input type="submit" name="save" value="{if $info.role_id > 0}{tr}Update{/tr}{else}{tr}Create{/tr}{/if}" />
        {if $info.role_id > 0}
              {smartlink ititle="New Role" pid=$info.p_id}
        {/if}
    </div>
{/form}


...MORE TO COME...

We close the BODY and page, using the following.

    </div><!-- end .body -->
</div><!-- end .galaxia -->
{/strip}


</label>
</v></ctrl></alt>