New admin-side theme

Destry · 2011-06-28 21:40:59

Nice looking theme, Phil.

philwareham wrote:

Trouble is, there is currently no hard guidelines on how to structure HTML in the admin area so many plugins have their own structures and even their own styling. Even the core admin area has lots of inconsistency in how it’s laid out – it was not until I started theming that I found that out.

Forgive this theming dilettante question, but are there “hard guidelines” for the default front-end themes, because I think I have something to share, but I’m not sure where I should go to share it, or if it might have been talked about before.

philwareham · 2011-06-28 22:46:15

@Destry

I’ve personally not seen any guidelines for either front-side themes or admin-side themes, though there may be somewhere that I’ve missed.

@Bloke

Cripes, where to start? In the short term regarding your plugins I’ve been fixing up each as requested by users, and putting any plugin specific CSS in the theme’s ‘custom.css’ file. So if you could list the ones that are looking bad I’ll look at them as a case by case basis.

Long term, IMHO the whole admin area HTML, ID and class structure pretty much needs to be rewritten from the ground up for TXP5 as well as providing a well documented series of UI elements and naming conventions for id/class to plugin authors that they can bolt together in their work without compromising the HTML with inline CSS and not borrowing bits from other parts of the admin structure that ‘roughly’ fit their needs. That will mean quite a shake up for existing plugins but if they are important and popular enough then eventually they’ll fall in line, and be all the better for it.

I started simplifying the write page here a while back, got bored and left it half done (felt there was no point going any further since I don’t know what the write page will contain as of TXP5 and beyond, or even if there will be a write page as such in it’s current form). Maybe it’s another one for a Github project.

Last edited by philwareham (2011-06-28 22:50:48)

maverick · 2011-06-28 23:21:20

Bloke wrote:

Unfortunately, things like the wet_quicklink button and jmd_img_selector show up sandwiched between the Textile and Advanced Options (due to the position of the callback) but they’re not rendered uniformly because they’re not ‘twisty’ blocks.

w/ regards to wet_quicklink and other plugins that add a single element that lack “twisty blocks”, I don’t care for how they look either in some of the themes. So I’ve altered them so they are in blocks.

example for wet_quicklink – I have replaced wet’s elegant code with this clunkish version for adding the menu entry

/**
 * Insert a menu entry in the first sidebar
 */
function wet_quicklink_menu()
{
	// add a link in left column to launch the overlay
	return '<div id="insert_group">
   <h3 class="plain lever">
      <a href="#insert">Insert</a>
   </h3>
   <div id="insert" class="toggle" style="display:none">
      <p class="wet_quicklink">
         <label for="wet_quicklink">Insert Article Link</label>
         <a target="_blank" href="" onclick="popWin(this.href); return false;" class="pophelp">?</a>
         <br/>
         <a href="#insert-link" id="insert-link">'.gTxt('Insert Link').'</a>
      </p>
   </div>
</div>'.n;
}

which looks like this:

fwiw

Bloke · 2011-06-28 23:44:40

philwareham wrote:

a well documented series of UI elements and naming conventions for id/class

Note to self: write the document on the naming convention, that I promised after 4.3.0 was released (well, convention as much as I could, given the higgledy piggledy mess of names that have plagued the 4.x branch).

The plan is/was to try and keep the classes and IDs as close as practical to what they are now (to avoid huge amounts of plugin and theme rework) but remove the crappy markup so things like unnecessary tables will be replaced by HTML 5 sections and divs, etc. Thus if you target .date widgets in your theme/plugin then you should still be good to go under TXP 5. But if you use div.date, table tr td.date or any other such chains, you’re in for a bumpy ride.

Unfortunately a lot of the admin-side still has inline style attributes. My goal is to eradicate all of it, because it’s a nightmare for plugin authors and themers alike.

This ties in (a bit) with the value/philosophy document that I should also write; something that Destry touched on earlier today. The core needs to stay light and airy — which includes the core CSS and markup — with a heavy reliance on an API that allows plugin authors and theme builders to meld the admin side to suit.

Slightly OT (sorry) but things like complete user/rights management is not in my plan for TXP 5. Regardless that “every” other CMS has it as standard, the number of people that actually need it out of the box is simply too small to cater for. BUT, I want the privs and groups out of static files and into the database. I want functions for adding/removing/checking privs, areas, groups, etc such that various flavours of management plugin can spring up to permit every possible functionality we could dream. One person might want to just rename the groups; someone else might want to create completely new users and groups, with custom priv management.

Having just been through the pain of writing exactly this type of plugin I can say that if TXP had such an API, the plugin code would be roughly half what it is today. As it stands I’ve had to copy and tweak huge chunks of the core to make the plugin do what I want, which is not in the spirit of reuse and is part of the desire to rewrite the Textpattern code base in a more extensible manner.

Anyway, back on topic, I’d far rather you cast your eye over plugins such as smd_featured and told me where I was going wrong in the markup for it to render so oddly under your theme compared to the others (noted above) I have installed, than for you to go to the trouble of writing exceptions for each plugin. If we can meet in the middle somewhere, perhaps by you relaxing some of your CSS rules and me sticking to a better markup system, we’ll both save ourselves some work down the road.

For example, it seems like you have rules for each admin panel individually, each prefixed with the page name. That’s one way to approach it — micro control down to the nth detail, with a reset.css and everything for pixel-perfect results — but I went to some lengths in TXP 4.3.0 to attempt to standardize the class names across tabs (as much as I could while trying to maintain backwards compatibility, which is actually pretty tough). A date is a date is a date. An ID is an id is an id. An action column on one tab is an action column in another, and so on. Only where I had to deviate for b/c did I (reluctantly) do so.

The upshot is that you should (ha! in theory) be able to write one or at most two rules to affect all similar widgets on all tabs. Then, if any plugins comes along and render such widgets, your theme picks them up and renders them consistently. If you’re always targeting individual tab names, plugins won’t see your rules and you’re forced to write an exception.

I feel bad that I’ve not written the guide for all of this behind the scenes stuff. I apologise profusely — I did promise it ages ago — and will endeavour to cobble together something that can be refined over time which should help us all to coexist with the minimal amount of hassle until something approaching Nirvana arrives.

maverick

Sure, that’s the sort of thing we can do as plugin authors: put markup around our buttons to make them appear like the other twisty items.

The only thing that stops me doing that kind of thing right now is the fact that it looks OK in classic1&2, Remora, Emporclo Cool, Inspired, Sand space, Air, Vitraux and (almost) Din, Slim Orange, Stung and Prometheus. The only one it looks strange in is Hive. I’m not saying the markup in those plugins is perfect — if it can be improved for the good of everyone we should look into it — but the fact they render passably in 12 themes and poorly in 1 theme might indicate that the Hive theme itself could be tweaked as the path of least resistance. *shrug* I’m no designer and my CSS is worse, so take my views with a mountain of salt!

Last edited by Bloke (2011-06-28 23:45:25)

philwareham · 2011-06-29 06:55:35

I’d far rather you cast your eye over plugins such as smd_featured and told me where I was going wrong in the markup for it to render so oddly under your theme compared to the others (noted above) I have installed, than for you to go to the trouble of writing exceptions for each plugin.

Sounds like the best course of action, if you could let me know the ones that are currently the most problematic via a PM then I’ll reverse engineer them here and see how we can both improve our code with the least amount of effort/disruption.

For example, it seems like you have rules for each admin panel individually, each prefixed with the page name. That’s one way to approach it – micro control down to the nth detail, with a reset.css and everything for pixel-perfect results.

I’m sure the CSS of this theme can be tuned to be more global over time, but the problem I’ve found is that unexpected parts of the admin area reuse CSS classes and layout when they should not – especially the .edit class and #edit id which seems to be used all over the place for various unconnected tasks (though that might be down to lack of documentation). Hence I’ve made some of the CSS page specific. I will eventually need to systematically go through the whole CSS file and work out where I could make it less targeted but that is a fairly large task.

…but the fact they render passably in 12 themes and poorly in 1 theme might indicate that the Hive theme itself could be tweaked as the path of least resistance.

The Hive theme started out purely as an in-house tool so that we could be confident that our clients had a clean and modern looking admin area when they add their content. Then I thought it would be something the community would benefit from so released it publically – it’s kind of spiralled from there. Since I don’t use a huge number of plugins if I can help it I’ve only concentrated on plugins I myself use plus any that are reported as broken by users.

I’ve also sent polite suggestions to a couple of plugin authors as to how their plugins could be made more consistent with TXPs structure – arc_twitter being one that springs to mind.

That got me thinking about the whole TXP experience from an end-user’s perspective and thus the front end template project was born. Although even that is a make-do reusing current assets from the default TXP install as much as possible for minimal disruption.

I feel bad that I’ve not written the guide for all of this behind the scenes stuff. I apologise profusely – I did promise it ages ago.

Maybe the real problem is that there is simply too much work involved for a small team of devs – maybe you should invite a keen UX/UI/front-end person (or two) onto the team to take some of this burden away from you? Some of us are probably only too willing to help, after all I’ve invested quite a lot of resources into TXP powered sites for clients so it’s in my best interests to see TXP continue to improve and flourish in the future.

Last edited by philwareham (2011-06-29 06:58:12)

Bloke · 2011-06-29 08:30:00

philwareham wrote:

if you could let me know the ones that are currently the most problematic

Will do, thanks.

unexpected parts of the admin area reuse CSS classes and layout when they should not – especially the .edit class and #edit id which seems to be used all over the place for various unconnected tasks

Ah yes, the pesky edit and list classes/IDs. Splattered without regard throughout the code. When I was going through it all, you wouldn’t believe the number of times I wished I had a digital Uzi with a little button on the back labelled “shred, while retaining backwards compatibility”.

The Hive theme started out purely as an in-house tool so that we could be confident that our clients had a clean and modern looking admin area when they add their content.

That makes sense, and explains the reset.css and the micro control. All perfectly justified in that environment; in a similar way we wrote code specifically for IE on our old corporate intranets of the 90s because that was the only browser we knew would be installed. When the environment is controlled, the tools follow to fit.

I’ve also sent polite suggestions to a couple of plugin authors as to how their plugins could be made more consistent with TXPs structure – arc_twitter being one that springs to mind.

Excellent. That helps us all. And the (currently) fictitious guideline document will help further.

Maybe the real problem is that there is simply too much work involved for a small team of devs

Hehe, maybe. The document in question was going to be stuffed in a suitable place in the wiki anyway — perhaps under Plugin development guidelines. Since the wiki’s open to all, if you want to start that doc, or even write it all, then be my guest! I’ll be on-hand to answer any questions either here or via e-mail.

We’ll be looking for ways to smooth the transition between 4.x and 5.x, and with your experience in HTML 5 and themes (front-side and admin-side), your input on sexifying the interface and laying out/naming stuff in a semantic manner would be invaluable.

Last edited by Bloke (2011-06-29 08:31:55)

philwareham · 2011-06-29 08:57:43

Well, regarding the whole CSS naming conventions, as a start you could add prefixes rules for core and plugin IDs/classes, and prefix-less IDs/classes for global styles.

Such as any core specific (and reserved for core only) ID being:

#txpcore_page-article or #txpcore_image-group

A plugin specific (and reserved for that plugin only) ID being:

#smd_admin_themes_page-theme-select or #smd_admin_themes_theme-list

And a global class (available to all) being:

.edit-form or .accordion-lever

That’s not a million miles away from what’s already there. When I said previously that the admin structure ‘pretty much needs to be rewritten from the ground up’ I meant retain the structure that works well and semantically (such as using fieldsets and legends) whilst discarding and rethinking all the cruft that has built up as a natural evolution of an open-source project worked on by multiple authors over the years.

Last edited by philwareham (2011-06-29 08:58:33)

Bloke · 2011-06-29 09:34:35

philwareham wrote:

add prefixes rules for core and plugin IDs/classes, and prefix-less IDs/classes for global styles.

In principle that works. TXP should be namespaced anyway, if only for the fact it will play nicely with other tools installed alongside it.

Currently, for example at the coding level, other open-source projects that use a DB class name (an OO class, not CSS class) will clash with TXP and cause errors. We should be either using TXP_DB or a proper namespace (this also has the side benefit that we could then build a whitelist of available functions and improve tag security. I think Spark/Plug enforces a namespace anyway so, from the coding point of view, we’re covered). The same applies to HTML; we suggest all plugins adhere to a naming convention and perhaps the core should too.

Separating IDs and classes by a prefix is attractive. Core ID’s shouldn’t be reused anyway, though they probably are, so to head for a prefix on all core IDs and no prefix on core classes is appealing.

Having said that, you may notice that — at the request of phiw13 — I employed a txp- prefix for some of the newer class names such as txp-control-panel for the area above lists and txp-container, txp-list / txp-edit for the main content areas depending on the type of action being performed. These are currently on <div>s but they could be HTML 5 <section>s or whatever.

While these are core classes I would not wish to dictate that only core could use them because I might want to mimic the structure of the core in a plugin, e.g. have a control panel area above a list of super-fragilistic whatnots. Using core class names guarantees that any rules a theme has applied (e.g. centering the box, applying padding, float, or bg colour) will be carried over to my plugin: yay!

Usage guidelines should state these facts so people are aware of the consequences of reusing an ID (potential broken themeage), and aware of the benefits of reusing core class names; whether ultimately prefixed or not. You’re right that name misuse by plugins leads to undesirable consequences. I suspect part of that can be mitigated by choosing suitably semantic names — something I’m rather rubbish at, and something the core has not done well to date!

… discarding and rethinking all the cruft that has built up as a natural evolution of an open-source project worked on by multiple authors over the years.

That’s the ticket!

philwareham · 2011-06-29 09:55:23

Shall I lift the HTML structure from the admin-side (minus any styling and javascript for the moment) and place it in a Github project. Then we can collaboratively work on a new schematic for the future of TXP, would that be beneficial?

At the same time we can use that project to kick about out some UI/UX elements and jQuery goodies (I’m thinking tooltips, popuphelp as overlays not new browser pages, accordions – that sort of thing). Find what works and what doesn’t work.

Bloke · 2011-06-29 10:04:08

philwareham wrote:

Shall I lift the HTML structure from the admin-side (minus any styling and javascript for the moment) and place it in a Github project.

Excellent idea. Yes please.

fwiw, current thinking is more reliance on bits of non-intrusive help, and also some jQuery / jQuery UI goodness (although that’ll double the size of the codebase because jQuery-UI is huge!)

For example, using lightbox windows to edit simple data, instead of employing inline editing with confusing multiple Save buttons (Sections tab), separate steps (Files tab) or having the edit form above the list (Users/Links tabs). That thinking is liable to change as we discover what works best from a UI / IA perspective — and it almost certainly won’t work across the board — but it’s something to explore as a starting point.

Last edited by Bloke (2011-06-29 10:04:30)

philwareham · 2011-06-29 10:20:04

From experience, I’m not sure jQuery UI is the right course to take – it’s a bitch to reskin due to the overly complex CSS and would create some nightmares for theme creators. Something like jQuery Tools is probably more suited to TXP. Would have to check the licensing on it though I guess.

I’ll get the structure project underway when I get a spare moment over the next week.

Last edited by philwareham (2011-06-29 10:21:02)

Bloke · 2011-06-29 10:26:39

fwiw, I prefer Tools to UI too even though the feature set isn’t as rich.

Textpattern CMS

Textpattern CMS support forum

#49 2011-06-28 21:40:59

Re: New admin-side theme

#50 2011-06-28 22:46:15

Re: New admin-side theme

#51 2011-06-28 23:21:20

Re: New admin-side theme

#52 2011-06-28 23:44:40

Re: New admin-side theme

#53 2011-06-29 06:55:35

Re: New admin-side theme

#54 2011-06-29 08:30:00

Re: New admin-side theme

#55 2011-06-29 08:57:43

Re: New admin-side theme

#56 2011-06-29 09:34:35

Re: New admin-side theme

#57 2011-06-29 09:55:23

Re: New admin-side theme

#58 2011-06-29 10:04:08

Re: New admin-side theme

#59 2011-06-29 10:20:04

Re: New admin-side theme

#60 2011-06-29 10:26:39

Re: New admin-side theme

Board footer