Symphony.

"It's an important and popular fact that things are not always what they seem." For instance, you may have thought that Symphony's backend before version 2.2 was bug-free and easy to customize. Not quite. Let's say you wanted to add a form to a page. You simply couldn't do it, because the main form acts as a wrapper for the whole layout, header and footer included (and if you didn't know that HTML doesn't allow nested forms, Allen is going to slap you in the face with a fresh copy of Symphony Start to Finish).

During the last few weeks you may have noticed the whispers circling the globe, hushed voices murmuring excitingly about Symphony 2.2 (or squeaking excitedly, if it's dolphins we're talking about... What? They're the second-most intelligent creatures on the planet. They must be into Symphony, no?).

If you are a dolphin, you are probably already updating your extensions before Symphony 2.2 goes stable (will happen soon, so be ready). If you are a smart dolphin (or a dolphin spy, which would be pretty cool), then you might have heard about some very important changes coming in 2.2 that will make your life as a marine mammal developer way better than before. But amongst the many bugfixes and improvements, it's unlikely that you've heard about the ones related to the back-end stylesheets and layout. Lucky for you, I'm here to explain it all.

The back end has undergone significant changes that make it easier to adapt to your own needs. You are finally free to add as many forms as you want (don't go crazy, though). Furthermore, there are a few new UI components to help your extensions shine as they never have before.

Back-end Page Structure

There are four new XMLElements that can be accessed through the AdministrationPage object:

Wrapper

The main container, wraps the whole layout.

Header

Includes the site’s name and the backend navigation.

Contents

Everything that changes from page to page goes here.

Footer

Symphony’s version and user links.

The most important change concerns the main form element, which is now a child of Contents. If you used to append new elements to Page->Form, you should consider replacing Form with Contents or one of the other new elements at your disposal. You can still access Form, but remember that it's no longer the main wrapper, so be careful.

Back-end CSS

Consolidation

Up to Symphony 2.1.x there were four CSS files linked to the back end: basic.css, admin.css, tables.css, and forms.css. Over time it has become evident that this was overkill, really, so we decided to get rid of both tables.css and forms.css, for convenience's sake. In Symphony 2.2:

• basic.css contains only CSS rules that are meant to be shared throughout the whole system -- a global reset, to put it in other words.

• admin.css is responsible for styling the whole backend and contains some new classes that might be useful for extension developers.

Page types

If your extension makes use of setPageType("form") or setPageType("table"), please make sure you replace every occurrence of form and table with single and index, respectively. The old values are deprecated and might be dropped in future versions.

• index is for pages that show a list of homogeneous items (e.g. the entries table).

• single is for pages that represent a single entity or a page of preferences.

New UI components

Let's talk about the cool stuff. Symphony 2.2 includes a couple of new UI components:

Nested settings

If your extension provides the user with a plethora of options, then you'll probably want to organize your settings into subsections (otherwise fellow dolphins may ostracize you). This is where nested fieldsets comes in handy:

If you want to achieve that, just insert a new fieldset with class settings inside the outer one. Use a proper legend for your subsection and remember that text is part of the UI.

<fieldset class="settings">
    <legend>Main section</legend>

    // ...

    <fieldset>
        <legend>Subsection</legend>
        // ...
    </fieldset>

    // ...

</fiedlset>

List of checkboxes

I know you like checkboxes. Everybody does. Checkboxes are useful when you want to allow users to enable/disable certain features with a single click. However, as the number of checkboxes grows it becomes harder to keep the UI tidy and clean. If you care about your users, wrap your group of checkboxes in a div with class compact.

<div class="compact">

    <label>
        <input type="checkbox" ... />
        <i>Help text</i>
    </label>
    <label>
        <input type="checkbox" ... />
        <i>Help text</i>
    </label>

    // ...

</div>

Updated or Old UI Components

The call-to-action

Do you remember the famous "Create Ensemble" button? Maybe "Change password" is more familiar?

The effect is still around, but in order to make it work you must insert your button inside a span element with class frame:

<label>
    <span class="frame">
        <button>Save the world</button>
    </span>
</label>

The two-column grid

You are probably accustomed to the two-column grid. It's been around for a while:

If you want to replicate this effect, just use the following:

<div class="group">
    // First wrapper (e.g <label> ... </label>)
    // Second wrapper
</div>

Remember that in this two-column grid, you cannot have more than two wrappers, otherwise it will break. If you need to add a large number of elements inside each columns, just wrap them inside a nested div et... voilà!

The three-column grid

Only the most clever dolphins know about the legendary three-column grid, but it does exist in Symphony (and has for some time):

<div class="group triple">
    // First wrapper (e.g <ul> ... </ul>)
    // Second wrapper
    // Third wrapper
</div>

Here's the result:

Cool, isn't it?

The Tag list

Last but not least, you can create tag lists like this:

You only need an unordered list with class tags to be done.

<ul class="tags">
    <li>Alpha</li>
    <li>Beta</li>
    <li>Gamma</li>

    // ...
</ul>

Final notes

The back end has been tested in the following browsers:

• Opera 9+
• Firefox 2+
• Safari 3+
• Chrome 8+

Every change was meant to be as backward compatible as possible. It's likely that your extension requires a small update, but you will benefit from the way Symphony 2.2 breaks some things while improving others. We tried to find a balance, a trade-off between what was critical enough to require some tuning and what worked sufficiently to be considered acceptable. So, "Don't Panic" and feel free to ask if you've got any questions!

Summary

• Four new elements besides $this->Form: $this->Wrapper (in place of the old main form as the main wrapper), $this->Header (title + main navigation), $this->Contents (everything else but footer, replaces most of the ->Form occurrences), $this->Footer (Symphony version + user links).
• setPageType() accepts two new values:single and index, that are preferred to form and table.
• Call-to-action buttons like "Change Password" need a parent span element with class frame.
• Two CSS files to rule them all: basic.css for a global reset, admin.css for all the rest.
• Two new UI components (see above).