Crud View
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.
Background
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:
- Support for a few thousand entries
- Sorting
- Searching
- Pagination
- Progressive enhancement
Copyright and License
Please make sure you have a license notice at the top of your source code file.
Dependencies
Load any dependencies required by your view. The dependency list will typically include:
- One or more translations sets
- Library/Helper dependencies
/////////////////////////////////////////////////////////////////////////////// // Load dependencies /////////////////////////////////////////////////////////////////////////////// $this->load->language('dns'); $this->load->language('network');
Headers
An array defining the table headers is required for the Summary Table widget.
$headers = array( lang('network_ip'), lang('network_hostname'), lang('dns_aliases') )
Anchors
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/'));
Items
Summary
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:
- A simple title
- A single action link (edit)
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;
Title
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.
Action
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 control panel type of interface
- A summary table that links the first item; for example a user manager could hot link the username
Anchors
A typical CRUD table has an Edit and Delete button (The UD of CRUD), but other actions are common:
- Enable / Disable
- Block / Unblock
- Lock / Unlock
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) ) ); }
Details
The details of an item should match the information in the Headers definition.