"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
andindex
, that are preferred toform
andtable
. - Call-to-action buttons like "Change Password" need a parent
span
element with classframe
. - 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).
Comments
Thanks Simone, great overview and documentation!
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?
@designermonkey: if you want nested fieldsets to be placed inside a two-column grid you have to do the following:
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
p.help
element to the grid breaks the layout.A possible way to achieve what you want is:
Otherwise, if you don’t want the help message to span the whole grid:
Notice that, in this second example, the grid sees
div
andfieldset
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 p.help element to the grid breaks the layout.
Create an account or sign in to comment.