Agora/Engineering

Munaf, spage, and Trevor talked about Agora, CSS, Userlogin and VE in November 2012, and again in 2013.

What is Agora?

Everyone so far has rolled their own blue buttons: AFT, VE, and E3, etc.

Agora provides consistent CSS for buttons, forms, and other user interface elements. Trevor has mostly focused on the button look, but Agora encompasses the cleaner forms and different typography that Munaf has developed for the E3 team.

CSS approach

If a page element has new style mw-ui-button, then it gets the new-look button appearance; "mix-in" styles such as mw-ui-constructive and mw-ui-destructive make the button green or red. There is a patch to add these styles to buttons throughout core.

Similarly, if a form or div has new style mw-ui-vform, then labels and input fields in divs within it are styled in a compact vertical stack.

Agora is decoupled from the user's skin; code can opt-in to the Agora styles and it'll sort-of work in other styles besides Vector. MediaWiki's Resource Loader uses skinStyles to send either 'mediawiki.ui.vector.css' or 'mediawiki.ui.default.css' to the client, usually minified in together with other CSS.

Working with the Compass code

We use Compass to build the Agora CSS files from .scss "Sass" files. Sass is more compact and expressive than repetitive CSS, e.g. for the label color you can write darken($agoraGray, 30%).

To hack on Agora

install Compass
fetch latest mediawiki/core (see "Get the code" in Gerrit/Getting started, or use a MediaWiki Vagrant box)
cd resources/mediawiki.ui
look at the .css files, they have comments explaining where rules and values come from
modify the underlying sccs files in the sourcefiles/scss subdirectory
in the sourcefiles subdirectory, enter make. This will rebuild the .css files
if you have your own MediaWiki test instance, shift-reload pages to see your change. Otherwise ask an engineer to copy the new file to a labs test instance.
submit your change to gerrit (see Gerrit/Tutorial), alert the design mailing list so people can review it

Manual:Coding conventions/CSS has good advice for CSS, much of which applies to .scss files. http://css-tricks.com/sass-style-guide/ is a reasonable style guide for Compass.

How mw-ui-vform affects existing CSS and HTML

Labels and input fields in the new "compact vertical stacked form" automatically get a certain styling (gray small label text, full-width input fields, etc.) due to selectors such as .mw-ui-vform > div label. If you have elements in a vform to which you don't want these styles applied, you can move them one level down; for example nest them inside a <section> tag.

Account creation user experience/Engineering suggest how wikis can adapt to changes specific to the new login and create account forms.

Delivery

In MediaWiki 1.22 (the version installed on all WMF wikis as of mid-2013), Agora is in core MediaWiki.

For earlier releases we may either backport the files to a new dot release, or you could rely on the separate Extension:Agora where we originally developed the code.

Changing HTMLForm

spage has Gerrit change 65346 that adds a new display format to class HTMLForm. Clients like SpecialPasswordReset.php can simply:

     $form->setDisplayFormat( 'vform' );

This builds off the 'div' displayFormat (form elements in divs, not table rows). It

adds the Agora class 'mw-ui-vform' to the form
- form gets 290px wide, input fields go wide, 'error' class gets Agora styling
adds 'mw-ui-button mw-ui-big mw-ui-block mw-ui-primary' to the form's default submit button

HTMLForm issues

The HTMLForm framework defaults to two-column table layout, with labels on the left and input fields on the right. Gerrit change 65346 adds a 'vform' displayFormat to HTMLForm that makes it use Agora button styles and the Agora "vform" compact vertical format. It's straightforward to change each special form based off FormSpecialPage to use this new format, the change to Special:PasswordReset is only two lines.

Some problems:

HTMLForm wants to draw a border-line surrounding the form with a label. vform turns off the default one, but
1. FormSpecialPage's getForm method creates a hardcoded HTMLForm before it calls alterForm() where a form can change the displayFormat to 'vform'!
2. many forms call WrapperLegend to make their own, this has to be removed on a case-by-case basis.

most form labels include a colon, but we don't want this in the vertical layout, so we have to create new messages or hack the removal of trailing ':'

wide drop-down selects exceed the form width.

radio buttons, multi-selects, etc. haven't been designed in Agora yet.

how to cleanly do two-part labels with a right-aligned link? e.g.
"Password _Reset your password?_"
- could supply raw HTML in the 'label' property.

HTMLForm does default form field validation in PHP on the server (see screenshot).
- Alignment off
- We'd prefer a single error message above the form contents, and a red highlight on the erroneous field(s)
  - On form error, HTMLForm adds .mw-htmlform-invalid-input to the td, there's a style for '.mw-htmlform-invalid-input td.mw-input input' that makes the input field's border red. May be broken in div layout.

If we were to convert login and Create account to this new form
- the language links shouldn't be part of the form, unclear how a special form can output stuff outside the form area.
- how to add the "[Join Wiki]" CTA? probably use an 'info' field and supply its raw HTML, or insert in the footer.

...

What's working:

when a checkbox or radio button is in a vform, need to detect and output the inverted label within check.
the vform display format turns off the form display border for you (perhaps should only do this when using Vector skin?)
doesn't output an empty div for checkbox labels.
HTMLForm divs are crazily nested, so the margin-bottom on .mw-ui-vform > div to space each div out doesn't fire, so vform adds a .mw-ui-vform-div selector to Agora and applies the class to divs in vform.

Meeting notes from November

rollout

Trevor was thinking of rolling Agora extension out in the new year, due to him working on VE stuff in his real job.

To actually see the new buttons across all MediaWiki pages there would be a monster platform commit that applies the style to buttons everywhere. Gerrit change 52169.

E3's Userlogin enhancement will depend on this extension
If E3 deploys the extension, then VE will require it as well instead of their own CSS

E3 wants to roll out new Userlogin form with button changes to every wiki.

If/when we're confident it does the right thing we can change all existing styles.

the Agora extension could add a .agora style to the <body> tag of all pages, thereby changing all pages where the Agora CSS changes existing styles.
or we simply remove .agora from CSS selectors in agora.css, thereby changeing all pages.

The extension could make its addition of the .agora style to pages dependent on a user pref, so that users can opt out of it. Trevor thinks this is easy to do, he's done it before.

Organizing the CSS

Munaf wants to use less. Fine, use a Makefile to build CSS. RL one day could do this for us bug 40964 less or sass? sass has better PHP integration so maybe that.

2013-03: We're using Compass, running make and checking in resulting CSS

Changing core forms

Could choose different templates in the special page, rather than having a conditional in the template itself.

2013-03: Implemented in Gerrit change 55847

PHP implementation

Userlogin and Usercreate don't use HTMLForm, they're just QuickTemplate. HTMLForm is better.

2013-03: We're evaluating HTMLForm, See section above.

Trevor suggestion: Modify the template to optimize for Agora but have a mode where CSS changes make it look like the old version.

this would be hard, have to add spans and divs within the <li> elements and then table-ize them.

CSS naming

Should the new Userlogin/Usercreate form layouts add meaningful mw-form-stacked, etc. class names similar to Trevor's Agora mw-ui-button class, and when Agora is loaded these trigger the new appearance?
Or should the Userlogin/Usercreate form layouts just apply .agora style to an enclosing div, so that when Agora extension is loaded everything picks up Agora styling?

Munaf leans towards the latter. It makes it possible to transition site over to new style and/or eventually remove the .agora

2013-03 update: Agora adds mw-ui-vform that triggers vertical (block, width:100%) layout for its contents; the core forms also use a 'mw-ui-content' area and have selectors within that to turn off Vector's h2 underline, remove Vector's border on forms, etc.

Reviewers

Reedy or Chad on platform should review, or Timo/Krinkle. Need to socialize

Examples