ClearOS Documentation

×

Warning

301 error for file:https://clearos.com/dokuwiki2/lib/exe/css.php?t=dokuwiki&tseed=82873f9c9a1f5784b951644363f20ef8

User Tools

Site Tools


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.

ClearOS Developer Framework - CRUD Summary Table

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

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

ClearOS Developer - CRUD in Mobile View

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:

ItemDescription
titlea short title and unique (think mobile friendly)
actionan anchor that defines the default action (again, think mobile)
anchorsan array of anchors related to the item (edit, delete, enable, etc.)
detailssummary 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.

content/en_us/dev_framework_reference_guide_crud_view.txt · Last modified: 2015/03/01 20:14 (external edit)

https://clearos.com/dokuwiki2/lib/exe/indexer.php?id=content%3Aen_us%3Adev_framework_reference_guide_crud_view&1558287431