Formatted text selection

The widget a formatted text field is edited with, in the four states it comes in: a field allowed one format, a field allowed several, a field on a format with no text editor behind it, and a field whose stored format is not one it allows any more. Every one is the same element, and what differs is what the site has told it. Three of the four are altered by mantra_field, which fills the gaps core leaves when a field allows only one format: core hides the selector, so the editor is never told what the text is saved as, and mantra_field names the format in a read-only cell where the selector would have been; core drops a stored format the field no longer allows, which forces a conversion nobody asked for, and mantra_field keeps it selectable; core weights the 'About text formats' link above the control it explains, and mantra_field puts it back underneath. Nothing is saved, and what the page shows depends on the formats the account reading it may use -- a visitor who may not use Full HTML gets core's disabled widget on the fields that store it, which mantra_field deliberately leaves alone.

One format, named rather than chosen

A field restricted to a single format, which is how most fields on a site are configured. Core hides the selector as soon as only one format is available -- it sets the access of the select from the number of formats, so with one there is nothing to choose -- and an editor is then given no indication of what the text is saved as. mantra_field states it instead: the cell reading "Format: Full HTML" under the field is a read-only element it adds in place of the selector, at a weight that puts it where the selector would have been. It is a span rather than a label on purpose, because there is no longer a form control for a label to belong to: with a text editor attached the only thing left of the format is a hidden input, and without one there is nothing at all.

Rich text field, edited with the text editor of the format.

Several formats, and a selector to choose between them

The same element where the field allows more than one format, which is the only case core shows a selector for. Nothing here is named by mantra_field -- a visible selector already says what the format is -- but the order of the three things under the field is its doing: core weights the "About text formats" link above the selector, and mantra_field weights the selector back over it, so the link follows the control it explains rather than introducing it. That has to be done while the element is processed rather than in a preprocess function, because the children of the wrapper are sorted and rendered into a string before a template ever sees them.

Rich text field, offered in two formats.

One format, with no editor behind it

The same single format case again, on a format that has no text editor, and it is worth its own field because it is the only way to see the guidelines. The editor module hides the guidelines of any format that has an editor -- they say little that a toolbar does not -- so the tips below are markup a themer never meets on a site whose formats all use CKEditor. The format is named here exactly as it is above, which is the point of naming it at all: the two fields differ in what they can do and say so in the same words, in the same place.

About text formats

Plain text

  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.
Restricted to the fallback text format: no text editor, so the guidelines of the format are displayed.

A stored format the field no longer allows

The case mantra_field exists for, and the one that is easy to create by accident: the field allows Plain text, the text in it was saved as Full HTML, and something has to give. Core drops the stored format from the options, and what happens next depends on who is reading -- an editor who may administer filters is handed a required selector with nothing selected, and so a conversion they never asked for; everyone else gets the widget disabled with a line about insufficient permissions. mantra_field appends the stored format to the allowed ones before the selector is built, so what should be here is a selector of two with the stored format already chosen. It only does that where the account may use both formats, so a visitor who may not use Full HTML sees core's disabled widget instead -- which is the right answer, and the reason this section reads differently depending on who is signed in.

Allowed one format, stored in another.