Using the "category" Directive to Place Actions in the Xataface UI

Actions are a core concept of Xataface.  They can be viewed from two perspectives:

1. An action can be manifested as a button or link in the user interface.  E.g. The "New Record" button is an action as it is rendered in the user interface.
2. An action can be thought of as an HTTP request handler.  E.g. When the URL's query parameters include -action=new, the new record action is called upon to handle the request.   This will render a new record form or process the input from a previously rendered new record form depending on the other parameters of the HTTP request.

In this tutorial, I want to focus on the first aspect:  how and where actions are rendered in the Xataface UI.

Creating an Action

To start out, we'll need to create a new action.  

Steps:

1. Create a file named actions.ini inside the main directory of your application (if it doesn't already exist).
2. Add the following anywhere inside the actions.ini file:
   
3. Now try opening your application and notice the "Hello" button appear along with the other table actions. 

   

   After adding the hello action to the table_actions category, it appears with other buttons in the table actions (upper left).  This example shows the button using the g2 theme.  It would appear differently in different themes.

The placement of the action (in the upper left) was dictated by the category directive.  I chose to place the action in the "table_actions" category.  This category is intended to be used for actions that don't pertain to a specific record, but may be accessed at any time for a table.  Some examples include:

• The new record action
• The Import action

Currently clicking on the "Hello" button doesn't actually do anything because we haven't assigned it a URL (the url property).   At this point I just want to demonstrate how to show, hide, and locate the action buttons.  Future articles may discuss other aspects of actions like how to specify the URL that they point to.

Alternative Action Placement

You may be wondering what other possible positions are there for an action.  We've already seen the "table_actions" category, but there are many others.  In fact you can even create your own categories and embed actions inside the Xataface UI using your own custom templates.

Some other built-in categories include:

• result_list_actions
  This category is intended for actions that operate on records in the list view.  They are rendered at the top and bottom of the list view.
  
  
  
• record_actions
  This category is intended for actions that operate on the current record shown in details view.  They are rendered along the top bar of the record details view (which is used for rendering the output of most actions that pertain to a single record).
  
• related_list_actions
  This category is intended for actions that operate on a list of related records.  They are rendered at the top and bottom of a related list.  This is very similar to the result_list_actions category, except that it is used for related lists.

  

  Notice that the "hello" action is rendered inside the "More" menu.  This drop-down is automatically created by Xataface to house excess actions in the case that there are too many actions in the category to fit the space nicely.

• find_actions
  This category is intended for alternative "find" actions.  When a user enters a search in the top search field, they will be sent to the list view by default with a filter on the results.  You can provide optional responses to the search if you like, but creating your own custom search actions.
  
• history_record_actions
  These are actions that are intended to operate on history snapshots of a record.  This is only relevant if your application has history enabled.  It will appear next to the record version in the history tab for the record.

  

  Notice the "hello" label appears next to the history snapshot ID 3.

• personal_tools
  This category is intended for actions that pertain to a user's personal preferences or account.  These will be rendered in the user's personal menu in the upper right  along with actions like "Edit Profile", and "Log Out". 
  
• management_actions
  This category is intended for actions that help administrators manage system settings.   They are rendered in the upper right in the "Control Panel" menu.
  
• top_right_menu_bar
  This category is intended for actions that have global significance.  They are rendered in the top right on every page.  The only actions that are rendered here by default are the personal tools menu and the control panel menu. (g2 theme only)
  
  
  
• top_left_menu_bar
  This category renders the action in the top left menu bar of the application, along with the list of tables in the app.   It is a convenient way of adding additional options to the tables menu.
  (g2 theme only).

  

  Action added to the top_left_menu_bar category.  Because there are already a lot of actions in this category, it has been added to the "More" drop-down menu.  Had there been fewer existing actions, this would have been rendered in the top menu bar directly.

• list_export_actions
  This category is intended for actions that export the current result list in a different format.  It will be rendered inside the "Export" drop-down menu above and below the list view, along with actions like "Export CSV" and "Export XML".
  
• record_export_actions
  This category is intended for actions that export the current record (shown in details view) in a different format.  It will be rendered in the "Export" drop-down menu of the record details page, along with actions like "Export CSV" and "Export XML". 
  
• related_export_actions
  This category is just like the list_export_actions category except it is for actions that export the current related record list in a different format.  It is rendered in the "Export" menu of the related records view.
  

There are more actions than just these.  A good way to discover what action categories are available to you is to open the Xataface actions.ini file and the g2 module actions.ini file and see what categories are used in the existing actions.

More information about actions

This is just the tip of the iceberg for Xataface actions.  This post has likely created as many questions as it has answered.  There is more information about actions in the Xataface wiki and in the Getting Started guide.  E.g.

• actions.ini file directives (reference)
• Getting Started With Actions