Enumsets are a mechanism that has two purposes. The first is to
"prettify" the values that are displayed, and the second is to populate
fields with data (generally the two purposes interact).
Let's take a quick look at what an enumset tag looks like.
Enumsets are an XML way of defining key/value pairs. Essentially, if
you were doing PHP, it'd be similar to writing this:
$yesno = array('y' => 'yes', 'n' => 'no');
However, by defining it inside your template, you allow
yourself to use it in sqlfields. Let's say
that your good ol' employees table has a field called "parttime",
whose type is enum('y','n'). Sparse will grab
those values and put them in a select box. However, the select box will
look like this:
Not that pretty, is it? You can use enumsets to change this. The following tag:
<sqlfield name="parttime" enumset="yesno" />
...will result in this baby:
The generated HTML code for the above would look like this:
As you can see, the "key" of the enums is set as the value of the
options, and the "value" is set as the displayed text. This ensures
that Sparse will get the correct value (via the value attribute) but
the user will see the pretty text. Similar things happen if the type of the sqlfield is set to checkbox, radio, or selectMultiple. You can tell the enumset to be case-sensitive or not via the ignoreCase attribute.
You can also use enumsets even for plain old (non-editable) text. In
that case, it will simply check the entered value, and if it finds it
in the enum keys, it will replace it with the resulting value. Note that this will not work for text boxes or textareas, because when the user enters the value it'd have to be changed back
to the key when updating, which isn't always the desired behavior. Text
boxes aren't a good solution when you want only a small set of values
to be entered.
Important note: Using enumsets will replace the entire contents of the enum/set type of the field (if it exists). Make sure to have an enum tag for every option you want displayed.
Enumsets From Data
All the foregoing is great if you know in advance what you want your
data to look like. But what if you want to generate it on the fly - for
example, if you want to populate your select box with all the names of
the managers in the manager table - guess what? You can still do it.
8-) Simply use the query attribute, like so:
<enumset id="manager_names" query="SELECT id, name FROM myDB.managers ORDER BY name" />
Note that the table is identified with a database name; if you want to avoid that, you can use the database attribute. Et voila, you can use this enumset just like a regular one!
Default Enumsets
If you want, you can avoid having to actually specify an enumset by
simply having one defined with the same name as your field. (Note that
by "name" I mean the resolved name, so if you've used an alias, the
enumset must have the same name as the alias.) This allows you to use
enumsets with quick templates.
Referencing External Enumsets
You can also define a completely separate file to contain enumset information. You can use the sqlincludetag in a similar way to the HTML style tag:
<sqlinclude src="myEnums.xml" />
This will read in the referenced file and add all the enumsets found
there to the ones on the current page. If two enumsets have conflicting
id's, the one on the current page will overwrite the referenced one. You can also use sqlinclude for tag referencing.