Standardized Plugin Help

Gocom · 2012-04-10 19:49:15

ruud wrote:

How does the suggested template aid in providing better plugin styling that works consistently across all themes?

Coins have faces too. How does styles provided by a plugin work consistently across all admin themes? That margin of 15 pixels look like nothing when the theme uses text sizes of 14px, and spacing relative to it. The plugin’s paragraphs/attribute lists lines are literally connected together.

Best help files I’ve come around have had background or text color set. Black on dark blue. I like that. And those yellow code blocks look so good on this textured sand background. That blue border from the theme, that yellow from plugin and that sand background.

Which ids/classes/styles can we rely upon to exist and be styled as expected in every admin theme? Is there some kind of “warning” class (bright red text, non-blinking though).

True. Textpattern needs something along the lines of CSS framework. Something that has different type of elements and selectors everyone can use, and provide consistent look/feel. This framework would then be forced by core and loaded no matter what admin-side theme is used. Themes could change certain aspects of it on selector basis, but there always would be a consistent framework to developers relay on.

Something along the lines of Twitter bootstrap, not necessarily by the looks, but functionality. The less styles everyone writes, the better.

There has to be way to put the attributes in a list (ol/li!). Using paragraph tags doesn’t make sense.

I like to use paragraphs for attributes. Because of, well, spacing. Single attribute description can get long, and without proper spacing the content is hard to read. While to some it makes sense that visible is a boolean, others don’t even know what boolean means. Giving that origins story on bool is going to take few words.

Last edited by Gocom (2012-04-10 19:51:48)

philwareham · 2012-04-10 20:31:40

Yes, Ruud this thread was started four years ago and yet until I hooked that page into the wiki last week it was effectively buried out of sight and unused. I’m not saying it’s a perfect solution, far from it, but we need to take some initial steps to bring some order to the admin area. Feel free to amend it in the wiki if you see some improvements that need to be made.

I’ve already started documenting some design patterns for structural changes and a UI toolbox, but it’s going to take months of work – years maybe. So in the meantime I’m putting together a theme for use in Textpattern 4.5 that goes as far as I’m able to to improve UX within the structure we have right now. Jukka has been providing some really useful feedback on it and Stef has made some handy improvements to the admin code structure that help me get this theme made too.

Our users are going to expect Textpattern to work on their ‘post PC’ devices (sorry to use that phrase) going forward and the plugins inline styling we have now contain some huge barriers to that. The help pages seemed like a good place to start since some documentation already existed and it doesn’t rely too heavily on new UI elements being created.

ruud · 2012-04-10 22:28:23

Gocom wrote:

How does styles provided by a plugin work consistently across all admin themes? That margin of 15 pixels look like nothing when the theme uses text sizes of 14px, and spacing relative to it. The plugin’s paragraphs/attribute lists lines are literally connected together.

Exactly. Having an admin theme that makes it possible to create a pretty plugin help is a good thing. The reason I’ve used inline CSS wasn’t because I could, but because the default CSS resulted in lots of ugly (which, I admit, is highly subjective). I would’ve used the CSS provided by an admin theme if it were useable.

I like to use paragraphs for attributes. Because of, well, spacing. Single attribute description can get long, and without proper spacing the content is hard to read. While to some it makes sense that visible is a boolean, others don’t even know what boolean means. Giving that origins story on bool is going to take few words.

Spacing is style. A list of attributes is a list. You use paragraphs because the default styling of paragraphs gives you the visual effect you desire, while using an unordered list does not. Provide some nice styles for attribute lists and it will look just as nice (and makes a lot more sense semantically).

philwareham wrote:

Our users are going to expect Textpattern to work on their ‘post PC’ devices (sorry to use that phrase) going forward and the plugins inline styling we have now contain some huge barriers to that.

And it also causes problems if anyone ever wants to make plugin help accessible through textpattern.org.

I’ve already started documenting some design patterns for structural changes and a UI toolbox, but it’s going to take months of work – years maybe. So in the meantime I’m putting together a theme for use in Textpattern 4.5 that goes as far as I’m able to to improve UX within the structure we have right now.

Perhaps I’m misunderstanding, but these plugin help guidelines are not about improving style within the existing structure (because the existing structure is what plugin authors have put in the help part so far), but about defining how it should be structured. That’s fine. And makes sense, but if the main problem you’re trying to solve is to get rid of inline styling, then it requires a theme that fits with that structure and to be able to use that theme I expected to see some specific classes or other style stuff in the suggested structure for the plugin help. I do not see them.

If you’re saying the 4.5 admin theme will make plugin help look pretty, provided you stick to a proposed structure, then that would be a good reason to stop using inline styles (if the structure makes sense, semantically). But if it takes months/years before we can have some plugin help styles that work out of the box, then these plugin help guidelines seem premature and a step backwards from what is possible now with some naughty inline styling. Perhaps the Wiki should indicate to which future TXP version the guidelines apply to and that they’re a work in progress (for someone visiting the Wiki, it appears to be finished documentation).

philwareham · 2012-04-10 22:58:08

Why would you need to see specific classes defined in the plugin help page? Surely if the structure kept to basic HTML elements such as lists, headings, paragraphs, pre boxes, code tags etc. and then those elements were also catered for in the theme’s stylesheet, you would not need to start adding classes to them at all.

The UI elements that plugin authors would use elsewhere is a different matter – that would definitely need some classes defined and suchlike. We need to come up with a wishlist of those to start with and progress from there.

For example, off the top of my head:

Containers
Tabs and pills
Tables
Accordions
Form elements
Single buttons and button groups
Dropdowns
Inline labels
In-page navigation

What else do plugin authors need in their toolkit, let me know?

Last edited by philwareham (2012-04-10 22:58:45)

Gocom · 2012-04-11 01:23:55

philwareham wrote:

What else do plugin authors need in their toolkit, let me know?

Containers + grids, groups, boxes, sets. Three columns, four columns etc.
Modern (actually usable) pagination, multi-edit controls and list view controls.
Search forms, auto-complete, live search suggestions.
Modal windows, popups. Depending on JavaScript native alert and confirm (as TXP does now) is not a good thing. If anything, they just get blocked by browsers.
In addition to labels, color sets / control types. If a div has class disabled, it looks disabled. If table row has class active it looks active.
General tool icon set. Icons for editing, options, info etc. Best bet might be to go with an existing open webfont(?).

philwareham · 2012-04-11 06:54:54

Some of the above could be added to my theme work pretty quickly. Icon sets, labels/colour sets, grids could be done in a matter of days. Others will need some extensive structural changes in the HTML.

I’ve already done some investigation of responsive modal boxes and got some workable solutions – for AJAX injected content it works fine in iOS devices (not got any andriod devices for testing yet) but I’m having some issues with cross-domain content via modals such as the pophellp pages. iframes are almost totally unusable in iOS due to scroll issues so can’t use that as a solution – I dislike iframes anyway.

Gocom · 2012-04-11 08:39:35

Ideally the help content on rpc.textpattern.com could be provided using JSON. I.e. requesting:

GET http://rpc.textpattern.com/help/?item=body&language=en-gb&type=json

Would give out a nice JavaScript object, e.g.

var _txp_help = {
	'title' : 'Article Body',
	'lang' : 'en-gb',
	'description' : 'The main content of an article is contained within the article body.\n\nWhen composing or readying articles for publication in Textpattern, you can switch between three views of the article: plain text, XHTML (the code with which a web browser renders the article), and a rendered preview.'
};

Which allows using the content for anything. From any programming language including client side JavaScript. And no cross-domain restrictions.

Likely isn’t that hard to make even. Just a different display mode to the current help item pages.

Last edited by Gocom (2012-04-11 08:40:43)

ruud · 2012-04-11 17:18:31

philwareham wrote:

Why would you need to see specific classes defined in the plugin help page?

Why does Gocom prefer using paragraphs for the list of attributes in the plugin help? As I understand it, it’s because the default style for a list doesn’t work well for displaying a list of attributes. That is just one example.

I’ll stick to inline styling for now ;)

philwareham · 2012-04-11 18:57:07

ruud wrote:

I’ll stick to inline styling for now ;)

Or you could help us add the missing components into the project, thus helping everyone in the future.

philwareham · 2012-04-12 12:11:33

Right, I’ve thrown the starts of a UI page together. Mainly for my own benefit with my own admin theme work, but I’ve also rendered the classic (remora extended) theme in it just to see how unusable the current Textpattern UI is:

My theme

Core theme

Urgh. I could beat the classic UI into slightly better shape with a little work, which would go some way to address some of the limitations mentioned previous in this thread (even though I don’t really want to as it’s a bit of a mess quite frankly). Since most admin themes use that as a base starting point I think it would not break backwards compat in any great way.

jakob · 2012-04-12 13:19:19

Right, I’ve thrown the starts of a UI page together

Phil, that’s most helpful! Thank you for persevering so diligently with making improvements. It may take time to be adopted but your action will make a difference, I’m sure.

colak · 2012-04-12 14:12:09

philwareham wrote:

My theme
Core theme

Hi Phil I was looking at your theme and although much better than the classic one, there are still problems with images (on FF11. + on a friend’s ipad). I’m not sure what your approach regarding those might be.

philwareham · 2012-04-12 14:23:55

colak wrote:

Hi Phil I was looking at your theme and although much better than the classic one, there are still problems with images (on FF11. + on a friend’s ipad). I’m not sure what your approach regarding those might be.

Can you be more specific as to what the problem is? I’m constantly testing progress on my iPad and in Firefox and not spotted anything obvious. Post your findings in the Github project. Thanks.

Also bear in mind the theme is for Txp v4.5 (so only works with SVN builds at the mo) and that it is nowhere near finished yet.

Last edited by philwareham (2012-04-12 14:25:36)

colak · 2012-04-12 15:55:49

philwareham wrote:

Can you be more specific as to what the problem is? I’m constantly testing progress on my iPad and in Firefox and not spotted anything obvious. Post your findings in the Github project. Thanks.

Hi Phil,

As I mentioned earlier I’m not sure as to what you are trying to achieve re the images so it is very unfair for me to comment. I’m not a member of github (or know how to use it) but here’s a screen shot of what I see on FF.

>Edit. Took screen shot down.

Last edited by colak (2012-04-13 06:28:03)

philwareham · 2012-04-12 16:01:50

Yes. I’ve not created rules for those image alignments yet. They are purely there as a possible future rule I might add to help admin plugin authors (image alignments are not in the core themes either) – they don’t appear at all in the admin area at present.

Textpattern CMS

Textpattern CMS support forum

#46 2012-04-10 19:49:15

Re: Standardized Plugin Help

#47 2012-04-10 20:31:40

Re: Standardized Plugin Help

#48 2012-04-10 22:28:23

Re: Standardized Plugin Help

#49 2012-04-10 22:58:08

Re: Standardized Plugin Help

#50 2012-04-11 01:23:55

Re: Standardized Plugin Help

#51 2012-04-11 06:54:54

Re: Standardized Plugin Help

#52 2012-04-11 08:39:35

Re: Standardized Plugin Help

#53 2012-04-11 17:18:31

Re: Standardized Plugin Help

#54 2012-04-11 18:57:07

Re: Standardized Plugin Help

#55 2012-04-12 12:11:33

Re: Standardized Plugin Help

#56 2012-04-12 13:19:19

Re: Standardized Plugin Help

#57 2012-04-12 14:12:09

Re: Standardized Plugin Help

#58 2012-04-12 14:23:55

Re: Standardized Plugin Help

#59 2012-04-12 15:55:49

Re: Standardized Plugin Help

#60 2012-04-12 16:01:50

Re: Standardized Plugin Help

Board footer