Module Views

Views provide a table for managing the data contained in a module.

Properties

  • Item Title — Modifies the related Module Action's title (i.e. "Checkers" will make the action become "View Checkers")
  • Description — A message shown above the view for users
  • Preview URL — Enables the action in your view (clicking the icon will take you to the URL provided with the entry's ID appended)
  • Data Table — The SQL table from which to pull data
  • Related Form — The form to use for the action in your view (if there is only one form in your module this can be left blank)
  • View Type — How to present the data (see below for descriptions of each view type)

Types

There are 6 different view types, you can click on the type to view detailed information about the view options for that type:

  • Searchable List — The standard searchable view with sortable columns
  • Draggable List — A view that allows for sorting of its entries via the icon. This view is also searchable. Searching temporarily disables the drag and drop functionality. This view requires a "position" column in INT(11) format in your table.
  • Nested Draggable List — A view similar to the Draggable List but allows for nesting entries as children of other entries. Entries in a Nested Draggable List are sorted relative to their parent entry. This view requires a column that specifies the parent entry in INT(11) format and a "position" column in INT(11) format in your table.
  • Grouped List — A view that separates entries by their grouping column. If the draggable option is enabled, options inside the groups will be sorted relative to the group.
  • Image List — A view that shows thumbnails of images instead of rows of entries. Can be draggable.
  • Grouped Image List — An image list that is grouped. Can be draggable.

Fields

After choosing the view's table, the Fields section will be populated with each non-reserved column. Titles will be inferred automatically from the column's name and may be changed. You may rearrange the fields using the icon (though you're sorting vertically, it represents the order in which the fields will appear horizontally in non-image view types). You can remove a field from the view using the  icon. Fields that are removed are then added to the dropdown menu at the top right corner of the table and can be re-added by clicking the add icon.

Parsers

Parsers allow you to run PHP code at cache-time in order to make the data from your table more presentable to the user. You enter vanilla PHP code to transform the $value variable into what you want stored in the cache for your user to see. In the example below we're going to transform a JSON encoded column in the database into something more presentable:

$data = json_decode($value);
$value = $data->firstName." ".$data->lastName;

In BigTree 4.1+ you are in a distinct function scope and have $value for the column that the parser is being run on and $item for the rest of the columns. Only $value will be returned and modified. In BigTree 4.0, parsers run in a higher scope and can potentially break the caching process.

Inferred parsers

When a view has a related form (either explicitly or through using the same table as the view) an inferred parser may be present. When a column has a database populated list in the form it is inferred that the description from the database populated list is a better fit for the view than the numeric id. These inferred parsers are run after your explicit parsers and will only change the column value if the id still matches an entry in the other table.

Custom Fields

If you'd like to display information in your view that doesn't necessarily correlate to a column in the database you can add a custom field. Choose the "-- Custom --" option from the field dropdown in the top right corner of your fields table and click the add button. You'll be asked for a key and title. The key must be something that isn't used by any of the columns in your table. After saving, your custom field behaves the same as any other field with one exception: it's $value is completely empty. In order to display something in this field in your view you must use a parser to set $value to what you wish to display.

Actions

Each entry in a view has a set of actions that can be performed directly via the view that can be toggled on and off by clicking them when editing a View. They can also be rearranged by grabbing the bottom tab and dragging. Default actions other than edit and delete require special columns in the database table as described below.

  • Edit — Edits this entry's information in the related Form
  • Delete — Deletes this entry
  • Preview — Opens this entry on the front end (Preview URL for the view must be filled out)
  • Feature — Toggles the "featured" column in the database (requires a "featured" column in the table set as CHAR(2))
  • Archived — Toggles the "archived" column in the database (requires a "archived" column in the table set as CHAR(2))
  • Approved — Toggles the "approved" column in the database (requires a "approved" column in the table set as CHAR(2))

Approved vs. Archived

Both approved and archived perform similar functions of restricting what should be shown on the front end of your website. The difference is in the default state of entries. If you want entries to be shown by default after creation, use the archived column and action. If you want entries to require explicit approval before being shown, use the approved column and action.

Custom Actions

You can also create custom actions in your views by clicking the "Add" button in the Actions section. A pop up will appear with the following options:

  • Name — The title that will appear when a user hovers over the action's icon
  • Icon Class — A CSS class that will draw the icon for the action (you should use one of the predefined CSS icon classes or include your own in a custom admin CSS file)
  • Route — The URL to refer to relative to the module's root URL (i.e. "view" will point to http://site.com/admin/module/view/entry-id/)
  • Link Function — If you need logic behind your action's link or it should like to somewhere outside the module, enter the name of a function to call. The only parameter the function should receive is the entry's view data (this is a record from bigtree_module_view_cache, not the actual record from your table — see View Caches for more information).

If you've entered a valid icon class, once you save the "Add" dialog your action should show up in the list where you can edit, delete, and toggle the action on and off. This only applies to the View you are editing — if you wish to use this custom action in another View you will have to add it there as well.