There are three main styles of forms/controllers found in ClearOS. This document provides information on the basic structure of a CRUD (Create, read, update and delete) view. You can find more information about the other two styles of view:
You can also find the complementary form controller for this view here.
The ClearOS developer framework provides a Summary Table widget for displaying information in CRUD-like applications. The screenshot below shows a pre-alpha view of the Local DNS server configuration tool.
The Summary Table is generated by the theme developer and provides the following features:
Please make sure you have a license notice at the top of your source code file.
Load any dependencies required by your view. The dependency list will typically include:
/////////////////////////////////////////////////////////////////////////////// // Load dependencies /////////////////////////////////////////////////////////////////////////////// $this->load->language('dns'); $this->load->language('network');
An array defining the table headers is required for the Summary Table widget.
$headers = array( lang('network_ip'), lang('network_hostname'), lang('dns_aliases') )
Typically, an Add anchor needs to be placed somewhere in a summary table. Other anchors can be included if you wish.
/////////////////////////////////////////////////////////////////////////////// // Anchors /////////////////////////////////////////////////////////////////////////////// $anchors = array(anchor_add('/app/dns/add/'));
A CRUD view requires looping through a set of items of course. Before digging into the requirements for the Summary Table widget, take a look at the screenshot from a mobile view of the Local DNS Server configuration. With limited real estate on a mobile, a summary table is made up of:
Unlike a full desktop view, there's no room for multiple actions (Edit, Delete, Enable, etc.) Instead, those actions are handled on the target page (typically the Edit page in the case of ClearOS). To maintain this kind of flexibility, every item in a summary table must provide the information described in the following table:
Item | Description |
---|---|
title | a short title and unique (think mobile friendly) |
action | an anchor that defines the default action (again, think mobile) |
anchors | an array of anchors related to the item (edit, delete, enable, etc.) |
details | summary of information to display in the summary table |
We will go through each of the following in the next few sections.
/////////////////////////////////////////////////////////////////////////// // Item details /////////////////////////////////////////////////////////////////////////// $item['title'] = $ip . " - " . $hostname; $item['action'] = '/app/dns/edit/' . $ip; $item['anchors'] = $detail_buttons; $item['details'] = array( $ip, $hostname, $alias ); $items[] = $item;
Going back to the mobile screenshot, you can see that every item needs to have a title that uniquely identifies it. In a desktop view, the item details are usually shown instead of the simple title.
Every item in the Summary Table has a default action and this is almost always the Edit action in ClearOS. Again, going back to the mobile example, the summary table is a list of clickable items. Other example GUIs that can use this default action:
A typical CRUD table has an Edit and Delete button (The UD of CRUD), but other actions are common:
In the example below, we have removed the 127.0.0.1/localhost entry from the Local DNS Server summary table. This is an example of doing a little bit extra for improved usability.
/////////////////////////////////////////////////////////////////////////// // Item buttons /////////////////////////////////////////////////////////////////////////// // Hide 127.0.0.1 entry if ($ip === '127.0.0.1') { continue; } else { $detail_buttons = button_set( array( anchor_edit('/app/dns/edit/' . $ip), anchor_delete('/app/dns/delete/' . $ip) ) ); }
The details of an item should match the information in the Headers definition.