checkbox

[Permalink]

The checkbox widget

In the fields.ini file you can specify a field to be edited using a checkbox widget by setting widget:type to checkbox. A checkbox widget can function in 2 different ways depending on the parameters that you assign to the field.

Table of Contents The checkbox widget Example 1: A TinyInt (boolean) field Example 2: A repeating field (multiple checkboxes for one field Example 3: Using a "Categories" relationship Related Parameters

Example 1: A TinyInt (boolean) field

Suppose our table has a tinyint field named "Active" which specifies whether the record is currently in use. This field will store a value of either 0 or 1. So we configure this field in our fields.ini? file to use a checkbox widget as follows:

[Active]
  widget:type=checkbox

Results:

Example 2: A repeating field (multiple checkboxes for one field

Checkboxes can store multiple values in a single field by setting the vocabulary? directive and applying it to a varchar or text field. In this case there will be one value saved per line.

In this example, suppose we have a varchar field named categories which uses the categories valuelist? to specify the different categories that can be checked at any given time. Our valuelists.ini file might look like:

[categories]
    __sql__ = "select id,name from categories"

And our fields.ini file looks like:

[categories]
    widget:type=checkbox
    vocabulary=categories

• Note that you don't need to name the field the same as the valuelist. It just worked out this way.

Now if we save a record with categories 1, 3, and 5 checked, then the categories column of our row in the database will store something like:

1
3
5

i.e. one category id per line. Note that using this method, your database will not be normalized because you are storing multiple values in a single field. However in many applications this is sufficient.

Results:

Example 3: Using a "Categories" relationship

"""(Note: This example requires Xataface version 1.2 or higher)"""

Example 2 above shows how we can easily add and remove a record from multiple categories using checkboxes. However it required multiple pieces of information to be stored in a single database field which may or may not be advantageous for your database design. If you're looking for a more normalized database schema you would probably design your database as follows for this case:

1. Books table - Stores all of the books.
2. Categories table - Stores all of the categories
3. Book_Categories table - Stores mapping of books to categories.

With out table structure we will first want to define a relationship from Books to Categories to reflect the connection between books and categories. The relationships.ini file for this might look like:

[categories]
    Books.Book_ID="$Book_ID"
    Book_Categories.Category_ID=Categories.Category_ID

And our fields.ini file for the Books table might look like:

[categories]
    widget:type=checkbox
    transient=1
    relationship=categories

• Note that there is no need for our field to be named the same as our relationship. It just turned out this way. Also note that we used the transient=1 flag here because the Books table no longer has a categories field in the database. This field is defined purely for the benefit of the edit form so that we will get a checkbox group to select the book's categories.

Results:

Related Parameters

1. vocabulary? - Assigns a valuelist to be used as the options for this checkbox group.
2. repeat? - A boolean value indicating whether this field should be treated as a 'repeating field'. A repeating field is one with multiple checkboxes. By default the checkbox widget operates as a single checkbox that controls a boolean value.
3. relationship - (Only applicable to transient? fields). If the relationship directive is set then this field can be used to add/remove records from a relationship.

blog comments powered by Disqus