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.

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.

var disqus_identifier = ‘xataface.com/wiki/checkbox’; (function() { var dsq = document.createElement(‘script’); dsq.type = ‘text/javascript’; dsq.async = true; dsq.src = ‘http://xataface.disqus.com/embed.js’; (document.getElementsByTagName(‘head’)[0] || document.getElementsByTagName(‘body’)[0]).appendChild(dsq); })(); blog comments powered by Disqus

//<![CDATA[ (function() { var links = document.getElementsByTagName(‘a’); var query = ‘?’; for(var i = 0; i < links.length; i++) { if(links[i].href.indexOf(‘#disqus_thread’) >= 0) { query += ‘url’ + i + ‘=’ + encodeURIComponent(links[i].href) + ‘&’; } } document.write(‘