Monday 05 July 2010 by

Txp 4.2.0 and earlier has a predominantly table-based admin side. In some places tables make perfect sense when displaying tabular data; on list pages, for example. In other places (e.g. Images tab, Write tab) it’s a bad use of space and very restrictive for plugins and themes.

The good news is that where 4.3.0 is hamstrung by tables, Txp 5 will not be. The admin side will be remodelled wherever it makes sense with a more semantic markup system (perhaps HTML 5 if it’s accepted by then).

To that end, we need a way to bridge the gap between today’s Txp admin side and tomorrow’s Txp 5 that won’t break huge swathes of plugins and admin-side themes. Txp 4.3.0 is that bridge.

If Txp 5 launches without a solid user base of plugins and themes, adoption will be slow and upgraders will, quite rightly, not move forward without their arsenal of plugins. This is largely based on a gut feeling and some anecdotal evidence that plugins are the backbone of many CMSs.

Come with me if you want to live

The idea is to introduce new classes, IDs and wrappers in the 4.3.0 release that plugin authors and admin theme designers can begin to use. The crucial factor is:

even if the tables or other markup falls away, the class names and IDs will prevail in the new markup wherever possible

This means, to all intents and purposes, more plugins and themes are likely to work out of the box in future Txp versions if we all start to use these new selectors from 4.3.0 onwards.

The history of things to come

Under 4.3.0, virtually every admin-side widget / logical group of widgets can be directly accessed without chains of descendent selectors or back-and-forth jQuery manipulation. The hope is that the underlying markup can be changed without affecting plugins and themes too much. Of course there’ll be casualties, but we hope to mitigate these.

Getting to r3372 has been anything but a smooth ride because the current names, IDs and classes leave a lot to be desired in places. To preserve backwards compatibility in the 4.x branch, we can only add stuff, not rename existing entities.

The sections below give some idea of what’s going on beneath the 4.3.0 admin side — which looks fairly similar to 4.2.0 to the untrained eye :-) If you have Firebug installed, feel free to browse around the new names and become acquainted.

Beneath the hyper-alloy combat chassis

There are a number of guiding principles behind the changes:

  • Remove the need to prepend DOM node selectors with HTML tags; make every element (wherever possible) or group of related elements directly, independently addressable
  • Multi-word classes use a hyphen between words because IDs have (usually) used underscores in the past. The hyphen is a tradition that some tabs already employ so it made sense to continue it
  • If a control didn’t have something to group it (e.g. there was no containing div, like the left sidebar of the Write tab around ‘Advanced’ or ‘Textile help’) then it now has one so the entire block can be switched on or off or moved with comparative ease. The id of the containing block has _group appended to it (e.g. id="advanced_group")
  • Where a control already had a unique ID, a class has usually not been employed. A class may be added at some point if necessary; only time will tell
  • Semantically-named wraptag elements have been added (usually as a <div> inside the tables) so that when/if some tables are phased out, the new wrapper names can be used in future admin-side markup. See below for a concrete example
  • The pages themselves have a class named after their primary navigation tab. So, for instance, all the pages under the ‘Content’ tab have class="content" on their <body> elements
  • The class names are uniform across tabs to give flexibility in targeting rules at varying scopes with minimal rule sets. If you only want to target stuff on a particular page / group of pages without affecting others, you just need to prepend your rules with the ID (or class) of the HTML <body> tag

Regarding the wrapper containers noted above, here’s an example from the Write tab. This is the existing markup:

<td id="article-col-1">...</td>
<td id="article-main">...</td>
<td id="article-tabs">...</td>
<td id="article-col-2">...</td>

New bloaty, class-soup markup in 4.3.0:

<td id="article-col-1"><div id="configuration_content">...</div></td>
<td id="article-main"><div id="main_content">...</div></td>
<td id="article-tabs"><div id="view_modes">...</div></td>
<td id="article-col-2"><div id="supporting_content">...</div></td>

Semantic markup in 5.0.x:

<div id="configuration_content">...</div>
<div id="view_modes">...</div>
<div id="main_content">...</div>
<div id="supporting_content">...</div>

You can see from this how important it is to start using the new names as soon as possible. Any plugin or theme that expects <td> elements to exist, or relies on some implied node order will likely fall over in Txp 5.

There’s a storm coming in

Tables will probably be retained in list-type areas because they contain tabular data. These include the Articles, Files, Links, Comments, Users, Visitor Logs and Plugins tabs. But the markup of the tables has been sharpened now:

  • Header rows at the top of tables are wrapped with <thead>
  • Data rows are wrapped with <tbody>
  • The extra rows at the bottom of the table containing the multi-edit dropdown and any ‘Show details’ checkboxes are wrapped with <tfoot>. The subcells are also individually named (e.g. class="multi-edit")
  • Column classes are named after their column names in the database wherever possible, or after what they represent if the database column is ambiguous / non-standard
  • Columns are also grouped with additional classes where it makes sense. For example, all date-based columns have a date class as well as one of posted (and/or created) and modified. This allows someone to disable/enable or otherwise visually group related columns of data, either with or without the header row
  • Article categories are classed as category1 / category2 and the generic category
  • Sub-items — usually a ul/li set — that appear inside an individual table cell are also classed wherever possible. In the case of the Articles tab, there are action-edit and action-view classes on the ‘Edit’ and ‘View’ links respectively
  • Each row is classed as odd or even so zebra striping can be performed. This is arguably not necessary with nth-child selectors, but is convenient
  • The multi-edit checkbox column has class="multi-edit" the same as the multi-edit controls beneath the tables

Say… that’s a nice bike

While the tables remain in some areas, other places will get a make-over. Most of the details pages have been positioned so the tables can be removed to leave behind the sleeker markup. Specifically:

  • The class names of the relevant items from the database are the same as on the list pages
  • Groups of controls usually take the prefix of the item they represent, e.g. on the Files tab, the three rows that give file information are class="file-info"
  • The centre pane in the Write tab now has div wrappers around each of the three views — Text, XHTML amd Preview — so each can be targeted individually
  • Text labels are put in a <label> wherever possible or inside <p class="label">...</p> if not
  • Sidebar content such as tag builder lists have a wrapper div/class on each group so they can be accessed individually if required (e.g. to place a new item above/below a specific existing group). The expanded state of each group is now remembered
  • Each item in the tree on the Category tab has its ‘level’ inside its class, e.g. class="level-0" for root nodes, level-1 for immediate children, and so on. If the category tab is laid out in something other than a tree, this allows the hierarchy to be maintained visually through CSS
  • Status radio button groups have multiple class definitions for convenience: the whole group is class="status" and each individual radio button has two classes: its name (Draft, Hidden, etc) and its numeric status identifier (status-1, status-2, etc)
  • An ‘active’ class is employed for the currently selected radio / checkbox items and their containers. In the Write tab’s status box, this leads to the comical class="radio active" :-)

Other CPU upgrades

  • The Advanced Options node on the Write tab has been split out into a set of logically grouped twisties; the state of each is remembered:
    • Advanced Options contains Article/Excerpt markup and override form
    • Custom fields get their own node — if there are no custom fields defined, the group heading remains but has class empty added to it. This preserves the node for those plugins/themes hooking into it (and preserves the callback) but allows a theme/plugin to hide it if desired. To this end, a CSS rule has been added to the classic theme with .empty {display:none;}
    • Article image has its own node
    • Meta info (keywords/url-only title) have their own node — still not convinced that ‘Meta’ is the right sort of label here. Anybody have any suggestions?
  • The Pages tab has a Create new page link
  • The Forms tab has You are editing form nnn above the textarea. The list of Forms on the right are now in collapsible groups which saves a little horizontal space so the edit area can be wider
  • The Style tab has You are editing style nnn above the textarea and the Create new style button is above the list on the right hand side. This means the left column is redundant so it has been removed in favour of widening the stylesheet textarea
  • Each column on the Pages, Forms and Styles tabs have the following IDs:
    • tagbuild_links (where appropriate) for the left column
    • main_content for the central column
    • content_switcher for the right column

Uzi 9mm required (a.k.a. I’ll be back)

Two tabs that still pose problems are the Sections and Preferences tabs. Sections are just a complete nightmare to handle elegantly and need significant brain power devoted to them.

For the Prefs tab, current thinking is:

  • Move Languages to its own tab (i.e. Admin->Languages). Even though it is a preference of sorts, it kind of transcends a basic pref setting due to the language management system
  • Remove the remaining 3rd tier navigation items so that Admin->Preferences becomes a sole tab, thus there is no more ‘advanced’ and ‘basic’ distinction, just a single page of collapsible nodes containing all prefs, plus a save button
  • Consolidate the existing prefs into better groups. Obvious candidates are to combine the commenting prefs into one group instead of splitting them between basic/advanced panes
  • Add a ‘Plugin’ node on the Preferences tab. Beneath this, a plugin that has registered its preferences intent has its own entry. When the plugin’s name is selected, its prefs are displayed directly on the Preferences pane like any other Txp prefs. Plugin authors would of course still be free to insert prefs anywhere else in the structure — or write a custom tab to handle them — but for simple settings this would be a convenient shortcut and may help reduce clutter on the Extensions tab

The future is not set

That pretty much covers the ethos behind the changes. Now and over the coming weeks, please take a look under the hood of the new admin side and if you like what you see or have any thoughts on how things could be done better — or perhaps have some better naming convention — speak up now! Once 4.3.0 is out, we’re stuck with it.

It would be remiss not to mention the fine folk who have kindly assisted with guidance, mods, feedback, suggestions and all important road testing so far while this has been in development over the past six months or so. In no particular order: jakob, renobird, phiw13, redbot, jstubbs, maxvoltar, net-carver, squaredeye, masa, and Sam (brown). You’re all oceans of awesome.