Seb Duggan

As of release 1.3 of Mango, the HTML structure of forms on the admin pages has changed, in an attempt to make them easier to design and maintain. This does however mean that admin pages for existing plugins will need to be updated (although they should continue working, albeit not perfectly laid out).

We have also added in jQuery behaviours and validation; but you shouldn’t need to write any JavaScript to take advantage of this.

Below you will find some basic instructions of how to write admin forms in the framework that’s been set up. You can also look at some of the built-in forms to see how they work…

The complete form

<form method="post" action="">

	<fieldset>

		<legend>User</legend>

		<!--- A basic text input --->
		<p>
			<label for="name">Name</label>
			<span class="hint">
				User's name as it will appear in posts
			</span>
			<span class="field">
				<input type="text" id="name" name="name" value="" size="30" class="required"/>
			</span>
		</p>

		<!--- A simple textarea --->
		<p>
			<label for="shortdescription">Short Description</label>
			<span class="field">
			  <textarea cols="40" rows="4" id="shortdescription" name="shortdescription"></textarea>
			</span>
		</p>

		<!--- A rich text textarea  --->
		<p>
			<label for="authorDescription">Description</label>
			<span class="hint">
				Text to show in author's page
			</span>
			<span class="field">
				<textarea cols="60" rows="10" id="authorDescription" name="description" class="htmlEditor"></textarea>
			</span>
		</p>

		<!--- A select box --->
		<p>
			<label for="role">Role</label>
			<span class="field">
				<select id="role" name="role" class="required">
					<option value="1">Role 1</option>
					<option value="2">Role 2</option>
					<option value="3">Role 3</option>
					<option value="4">Role 4</option>
				</select>
			</span>
		</p>

		<!--- A simple checkbox with label --->
		<p>
			<input type="checkbox" value="1" id="active" name="active"/>
			<label for="active">Active</label>
		</p>

	</fieldset>

	<p class="actions">
		<input type="hidden" name="id" value="1"/>
		<input type="submit" name="submit" value="Save"/>
	</p>

</form>

Let’s break this down a piece at a time…

Fieldsets

You don’t need to put your fields within a fieldset, but by doing so and adding a legend you’ll get a group of fields nicely grouped together on the page.

Text input fields

<p>
	<label for="name">Name</label>
	<span class="hint">
		User's name as it will appear in posts
	</span>
	<span class="field">
		<input type="text" id="name" name="name" value="" size="30" class="required"/>
	</span>
</p>

This shows the basics of the form layout. Each field sits in its own paragraph. A label is required, and the for attribute should match the actual field’s id attribute.

After the label is a hint, contained within a span with a class of hint. This is optional and may be omitted. This will be hidden when the page loads, replaced by a help icon – clicking on the help icon shows and hides the hint. With more than one hint on a page, you’ll also see an option at the top of the page to show/hide all hints.

Next comes another span, with a class of field. This contains the actual input field, plus any prefix or suffix text (for example, you may want to put a unit such as “pixels” after the field, but connected to it – this would be placed within this span.

A simple textarea

<p>
	<label for="shortdescription">Short Description</label>
	<span class="field">
		<textarea cols="40" rows="4" id="shortdescription" name="shortdescription"></textarea>
	</span>
</p>

Very similar to the text input; note that here we do not have a hint.

Rich text input (tinyMCE)

<p>
	<label for="authorDescription">Description</label>
	<span class="hint">
		Text to show in author's page
	</span>
	<span class="field">
		<textarea cols="60" rows="10" id="authorDescription" name="description" class="htmlEditor"></textarea>
	</span>
</p>

Identical to the basic textarea, except that we’ve added a class of htmlEditor to the textarea. This tells Mango to replace the textarea with a JavaScript-based rich text editor (tinyMCE).

It will also generate an icon which, when clicked, will switch between rich text entry and the basic underlying textarea – sometimes useful if you don’t want your code “tidied up” at all…

Select box

<p>
	<label for="role">Role</label>
	<span class="field">
		<select id="role" name="role" class="required">
			<option value="1">Role 1</option>
			<option value="2">Role 2</option>
			<option value="3">Role 3</option>
			<option value="4">Role 4</option>
		</select>
	</span>
</p>

Again, much the same as the basic text input.

Checkbox

<p>
	<input type="checkbox" value="1" id="active" name="active"/>
	<label for="active">Active</label>
</p>

Here, we have a single checkbox followed by its label.

Submit actions

<p class="actions">
	<input type="hidden" name="id" value="#id#"/>
	<input type="submit" name="submit" value="Save"/>
</p>

Any submit buttons should be placed at the end of the form in a paragraph with a class of actions. You may also put any hidden form fields in here.

Validation and required fields

You’ll have noticed that some of the form fields have a class of required. This is all you need to do to set that field as required – it will be checked on form submission, and an error displayed if it’s found to be empty. There will also be an automatically generated prompt added to the field’s label to show that this field is required.

You can also add other classes to the form field to require data validation. Some common examples are:

• email – checks that a valid email address is entered
• url – checks that a valid URL is entered
• number – checks that a number is entered (allows decimals)
• digits – only allows digits to be entered

More complex validation is also available by enetering metadata into the class attribute. This takes the format of name-value pairs, separated by commas, surrounded by curly brackets {}. For example:

<input type="text" class="required {maxlength:10,minlength:5}"/>

…would generate a required text field which must have between 5 and 10 characters.

For more information on what you can do, check out the documentation of the Validation plugin.