Formatted text selection

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.

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.

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.

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.