03 Feb 2011
Development Notes

"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:

The main container, wraps the whole layout.
Includes the site’s name and the backend navigation.
Everything that changes from page to page goes here.
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


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:

Nested Fieldsets

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>

    // ...

        // ...

    // ...

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.

Checkboxes List

<div class="compact">

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

    // ...


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:

    <span class="frame">
        <button>Save the world</button>
The two-column grid

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

Two-column grid

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

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

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

Here's the result:

Three-column grid

Cool, isn't it?

The Tag list

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

Tag list

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

<ul class="tags">

    // ...

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!


  • 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).


  • Lewis
  • 07 Feb 11, 12:27 am

Thanks Simone, great overview and documentation!

  • eKoeS
  • 07 Feb 11, 6:51 pm

There was a little mistake concerning nested fieldsets that has been corrected.

Nested fieldset must not have a settings class, as shown in the updated example. Sorry for the inconvenience!

Thanks Simone.

The three-column grid also needs the group-class, I think.

Yes, just realized that yesterday too. Have updated the post.

I can’t get nested fieldsets to look like this, they are not two columns like the pic above, and also, if I append a help ‘p’ tag to a div group, it breaks the layout!

Can we have a tutorial on how to do this in PHP to get the layout shown above?

  • eKoeS
  • 13 Feb 11, 9:49 pm

@designermonkey: if you want nested fieldsets to be placed inside a two-column grid you have to do the following:

<div class="group">
    <fieldset />
    <fieldset />

Remember that in a two-column grid it’s the first two nested HTML elements that act as columns. The same holds true for the three-column grid.

Moreover, “in this two-column grid, you cannot have more than two wrappers, otherwise it will break.” That’s why adding a element to the grid breaks the layout.

A possible way to achieve what you want is:

<div class="group">
    <fieldset />
    <fieldset />
<p class="help" />

Otherwise, if you don’t want the help message to span the whole grid:

<div class="group">
    <div> <!-- First column -->
        <fieldset />
        <p class="help" />
    <fieldset /> <!-- Second column -->

Notice that, in this second example, the grid sees div and fieldset as columns. It’s the only way to keep backward compatibility with existing extensions while providing developers with a flexible to build complex layouts.

I’m available for writing a tutorial if necessary. I’ll talk to Craig and the others about that.

Remember that in a two-column grid it’s the first two nested HTML elements pandora poland that act as columns. The same holds true for the three-column grid. Moreover, “in this pandora sale two-column grid, you pandora wood beads >cannot have pandora chainsmore than two wrappers, otherwise it will break.” That’s why pandora bracelet adding a element to the grid breaks the layout.

Create an account or sign in to comment.

Symphony • Open Source XSLT CMS

Server Requirements

  • PHP 5.3-5.6 or 7.0-7.3
  • PHP's LibXML module, with the XSLT extension enabled (--with-xsl)
  • MySQL 5.5 or above
  • An Apache or Litespeed webserver
  • Apache's mod_rewrite module or equivalent

Compatible Hosts

Sign in

Login details