Confluence Docs 3.0 : Confluence UI Guidelines This page last changed on Sep 24, 2008 by mryall. These are Atlassian's internal guidelines, published for the reference of plugin developers. More thorough documentation can be found in the Plugin development guide. Not all of these guidelines are followed throughout Confluence yet, but they set the direction of our future work in the product's front-end. ## Separation of content, presentation and behaviour It is imperative that functionality in Confluence separate content, presentation and behaviour for maintainable front end code. This means the following: HTML content goes in Velocity files. No CSS or JavaScript goes in Velocity files. Not even in style or onclick attributes. CSS styles go in CSS files. JavaScript code goes in JS files. JS files must be static and not generated by Velocity or any other mechanism. The remainder of this document describes how to achieve this in Confluence. ## Naming Conventions At the moment we have two simple naming rules: use dashes for HTML element ids or class names e.g. comment-actions use camel cases for variables, method names in javascript e.g. commentToggle() ## Markup Wherever possible, use meaningful tags in your markup and do not use markup for formatting (e.g. <strong>) or layout (e.g. <table>). For example, the following markup is suitable for the File menu in an application:
    <h3 class="menu-title">File</h3>
    <ul class="navigation menu">
    <li id="menu-item-new-window"><a href="#">New Window</a><span class="shortcut">⌘N</span></li>
    <li id="menu-item-new-tab"><a href="#">New Tab</a><span class="shortcut">⌘T</span></li>
    ...
    </ul>
The use of meaningful tags, rather than a sea of tables and divs make it rendering the page without stylesheets possible, and provide better degradation in mobile browsers, Internet Explorer, and so on. Assign classes and IDs that allow you to style the content appropriately. Use multiple classes in markup when required, but be aware that IE has limitations with parsing style selectors including multiple classes. Ensure IDs are unique within the page or Javascript code will not be able to access the elements properly. Do not use inline script and style tags. Put them in separate CSS and JS files and use `#requireResource` - see Including web resources below. Put attribute values in double-quotes and use lower-case tag and attribute names in all cases. Do not use self-closing tags (e.g. `<link />`) or include tags or attributes that are not part of the spec. Use closing tags for all elements that support them. We want our HTML to be valid and well laid out. Although HTML 4 allows the omission of attribute values for boolean-style attributes, do not omit attribute values in Confluence HTML. Rather, set the attribute value to the name of the attribute. For example: `<input type="checkbox" name="subscribe" checked="checked">`. This allows better forwards-compatibility with XHTML. Be sure that you are familiar with how Confluence automatically HTML encodes template references. ## Including Web Resources Confluence web resources (css & javascript) are now all defined in a System Web Resources plugin under `confluence/src/etc/java/plugins/web-resouces.xml`. You should no longer use the `#includeJavascript` macro that generates inline script tags wherever you invoke it. You should now use `#requireResource(pluginKey:webResourceKey)` to tell the `WebResourceManager` that you require a particular resource on this page. Note, this macro does not generate the actual markup but is done in `conf-webapp/src/main/webapp/decorators/includes/header.vm` via `$webResourceManager.getResources()`. Example from wiki-textarea.vm
    #requireResource("confluence.web.resources:prototype")
    #requireResource("confluence.web.resources:scriptaculous")
    #requireResource("confluence.web.resources:yui-core")
    #requireResource("confluence.web.resources:ajs")
    #requireResource("confluence.web.resources:dwr")
    #requireResource("confluence.web.resources:page-editor")
Currently, we don't have a way to indicate dependencies between the web resources. For example, it would be nice to define in the web resource module 'ajs web depends on yui-core'. The work around at the moment is to explicitly make calls to `#requireResource` in the order you would like the resources to be included. Multiple calls to the same web resource does not result in multiple includes of that resource, but rather the WebResourceManager will try to maintain the 'order' in which the resources were called. This is why you may see duplicate chunks of `#requireResource` scattered throughout Confluence. For more information about the declaration and inclusion of web resources, see: Including Javascript and CSS resources. ## Stylesheets #### No more site-css.vm We no longer have the huge site-css.vm velocity template. This has been split up into separate css files: master.css, master-ie.css, wiki-content.css and more (see master-styles web resource module) default-theme.css colors-css.vm The only dynamic styles in Confluence are the colors set by colour schemes, hence all color styling was extracted into colors-css.vm. We also have a separate stylesheet for the setup wizard, `setup.css`. #### Stylesheet ordering CSS resources are included in the following order: Confluence default styles (resources included via calls to `#requireResource` such as master.css) Colour scheme styles Theme styles Colour scheme and theme styles are also included in the header via the `combined.css` action call. It essentially produces a set of imports to other css resources, hence the name 'combined'. Sample output of combined.css
    @import "/s/1317/7/1/_/styles/colors.css?spaceKey=DOC";
    @import "/s/1317/7/1.0/_/download/resources/com.atlassian.confluence.themes.default:styles/default-theme.css";
Note, the old monster main-action.css (i.e.`StylesheetAction`) has now been deprecated and split into separate actions. #### Style guidelines Use the shortest form wherever possible. That means using three character colours, combined margin declarations, simple selectors, and so on:
    .menu li.menu-item a {
        color: #fff;
        background: #8ad6e8;
        margin: 0;
        line-height: 1.2;
        padding: 5px 1em;
    }
Avoid child selectors like `ul > li`. Instead use a class name of "first" for compatibility with IE. (You can use child selectors if you want to intentionally exclude IE, however.) When designing a new section of Confluence, consider using a style reset to clear out default styles for lists, paragraps and so on. #### Internet Explorer stylesheets Very often, it's desirable to serve custom styles to Internet Explorer. Confluence web resources can be marked as 'ieOnly' in order to be rendered in conditional comments only parsed by IE. See Including Javascript and CSS resources for more details and an example of how to do this. #### Print stylesheets Stylesheet web resources can be include a 'media' parameter with a value of 'print' to have media='print' included on their `<link>` tag so they are only used for printing. See the master-styles web resource in Confluence's web-resources.xml for an example. Any media type will be passed directly into the link tag, so you can also provide styles for handheld, projector media types, etc. as supported by your user's browsers. See Including Javascript and CSS resources for more details and an example of how to do this. ## JavaScript #### JavaScript guidelines Use closures to prevent unnecessary variables and functions being exposed in the global scope. For example, the code below binds an onclick handler to a button in the page without exposing itself or its variables in the global scope:
    jQuery(function ($) { // I am a closure, hear me roar!
    var i = 0;
    function increment() { alert(i++); }
    $("button.counter").click(increment);
    });
Don't introduce new global variables in JS. Rather put them under some namespace such as `AJS.Editor.MyGlobalVariable`. Don't mix Velocity and Javascript code. See Passing dynamic values to Javascript if you need to pass dynamic values to Javascript. #### Atlassian.js (AJS) To avoid depending on a particular JavaScript library too much, we have atlassian.js ("AJS") as an abstraction on top of each particular library's functions. In Confluence 2.9, AJS wraps jQuery so many functions work in the same style as that library. Throughout Confluence's JavaScript, we should use AJS to make common function calls such as `$`, `toggleClassName` etc. wherever possible. This enables us to easily change the underlying JavaScript library later on if necessary. #### Event Handlers In the past, we have used embedded event handling like (horribly) so: Sample code from common-choosetheme.vm
    <tr bgcolor="ffffff" onMouseOver="style.backgroundColor='f0f0f0'"
        onMouseOut="style.backgroundColor='ffffff'"
        onclick="javascript:checkRadioButton('themeKey.default');">
We are now moving to binding event handlers in javascript, using the jquery's `bind` function. Sample code from page-editor.js
    AJS.toInit(function () {
    AJS.$("#markupTextarea").bind("click", function () {
    storeCaret(this);
    });

    AJS.$("#markupTextarea").bind("select", function () {
    storeCaret(this);
    storeTextareaBits();
    });

    AJS.$("#markupTextarea").bind("keyup", function () {
    storeCaret(this);
    contentChangeHandler();
    });

    AJS.$("#markupTextarea").bind("change", function () {
    contentChangeHandler();
    });

    AJS.$("submit-buttons").bind("click", function (e) {
    AJS.Editor.contentFormSubmit(e);
    });
    });
You may have noticed in the above example, all the binds are wrapped in a `AJS.toInit()` function. This is only necessary if you require the code to be fired after DOMReady. Unfortunately, we haven't been able to port all the embedded event handler code to javascript. If you encounter such code during development, please fix it up as you go #### Using jQuery directly For advanced dynamic functionality, you can use jQuery directly. However, we don't allow jQuery to set the global `$` variable (which is still used by Prototype.js), so you should use the 'jQuery' global variable as shown below. To use jQuery properly in a JS file, do the following:
    jQuery(function ($) {
    // your code goes here
    // use '$' for jQuery calls
    });
#### Passing dynamic values to Javascript We are now trying remove inline scripts that are scattered throughout Confluence. Most of these inline scripts are in the velocity templates so dynamic values such as i18n strings and values from actions can be used in the script. We now have a way around this via AJS.params. You simply need to define a `fieldset` in your template with classes "hidden" and "parameters". AJS will automatically populate itself with the inputs defined in the fieldset. Example from page-location-form.vm
    <fieldset class="hidden parameters">
        <input type="hidden" id="editLabel" value="$action.getText('edit.name')">
        <input type="hidden" id="doneLabel" value="$action.getText('done.name')">
        <input type="hidden" id="showLocation" value="$action.locationShowing">
        <input type="hidden" id="hasChildren" value="$!helper.action.page.hasChildren()">
        <input type="hidden" id="availableSpacesSize" value="$action.availableSpaces.size()">
        <input type="hidden" id="spaceKey" value="$action.space.key">
        <input type="hidden" id="pageId" value="$pageId">
        <input type="hidden" id="actionMode" value="$mode">
        <input type="hidden" id="parentPageId" value="$!parentPage.id">
    </fieldset>
With the above code, you would use the above i18n edit label by calling `AJS.params.editLabel` in your javascript. If your i18n message includes variables in the form {0}, {1}, etc. which are meant to be populated by JavaScript values, you can use the `AJS.format()` function to present them. For example:
    $(".draftStatus").html(
        AJS.format(AJS.params.draftSavedMessage, time) // "Draft saved at {0}"
    );
The second and subsequent arguments to `AJS.format` replace all instances of {0}, {1}, etc. in the first argument, which must be a String. ## Related pages Including Javascript and CSS resources Web UI Plugins Confluence Plugin Guide Anti-XSS documentation W3C HTML 4.0 specification

Document generated by Confluence on Nov 05, 2009 23:34