- 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.
- 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.
- Create a file named actions.ini inside the main directory of your application (if it doesn't already exist).
- Add the following anywhere inside the actions.ini file:
- 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:
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.
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).
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.
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.
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.
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".
This category is intended for actions that help administrators manage system settings. They are rendered in the upper right in the "Control Panel" menu.
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)
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).
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".
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".
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.
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.