Home | SourceForge | Documentation | FAQ | What's New | To-Do List | Forums | Download | Contact

Sparse - Enumsets

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.

<enumset id="yesno">
  <enum key="y" value="yes" />
  <enum key="n" value="no" />

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:

<select name="parttime">
  <option value="y">yes</option>
  <option value="n">no</option>

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 sqlinclude tag 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.

Previous: Quick Templates | Enumsets | Next: Referencing Tags