Publishing Reports for Other Users

See also:

Getting Started

So far we have refrained from saving our report and have instead just been using the report preview function. This is not because saving a report template is complicated (it's not - you just click save). It is rather because I want to go over what each of the fields on the template creation form does.

Overview of How Publishing Works

The HTML Reports module makes use of Xataface's Dataface_ActionTool class to help embed reports into the application's user interface. Dataface_ActionTool keeps an inventory of all of the actions defined in the application (via actions.ini files) and makes these actions available in different contexts. Ultimately most of these actions are manifested as buttons or links somewhere in the user interface of the application.

See also:

http://xataface.com/documentation/tutorial/getting_started/dataface_actions "Xataface Actions: The Basics"

http://xataface.com/documentation/tutorial/getting_started/dataface_actions_2 "Xataface Actions 2"

http://xataface.com/wiki/actions.ini_file "actions.ini file reference"

Action Categories

Actions can be grouped by their category directive. This simple directive allows the Action Tool to determine which actions should show up in which section of the user interface. For example, actions with the table_tabs category, will appear as a tab along with details, list, and , etc... whereas if an action has a category of "result_list_actions", it will be displayed in the upper right of the list view along with the "Export CSV" and "Export XML" actions.

Some of the more common action categories and their corresponding purposes are listed below:

Category	Render Location
table_tabs	The tabs wrapping around the table options. E.g. find, list, .
table_actions	The links/buttons that appear just below the table tabs. These actions generally operate on the table or the entire found set. E.g. "New Record", "Update Set", "Delete Set", etc..
result_list_actions	Displayed before and after the list view. These are intended to either operate on the result set or present a different view of the data presented in the result set. E.g. "Export CSV", "Export XML", "RSS Feed", etc..
record_actions	Displayed just under the record tabs in the Details tab. These are intended to operate on a single record or present a different view of the current record. E.g. "Export Record as XML", "RSS of Current Record"
related_list_actions	Similar to the result_list_actions except these are displayed before and after related record lists.
record_tabs	The tabs that are displayed in details mode for each record. E.g. View, Edit, and the relationship tabs.
personal_tools	The personal management links accessible to the user. Usually displayed in the top right corner of the interface. E.g. "My Profile", "Control Panel", etc...
management_actions	Actions that appear in the control panel.
selected_result_actions	Actions that can act on selected rows in list view. E.g. "Update Selected", "Delete Selected", "Copy Selected", etc... Note: As of version 0.1 HTML Reports reports cannot be used with this category. If you set a report to this category, it just won't work correctly. Future releases will support this category.
selected_related_result_actions	Similar to selected_result_actions except that this operates on related lists.

Setting the Report Name

The "Report Name" field is where you specify a unique ID for this report (as far as the Action Tool is concerned. This should contain only letters, numbers, and underscores (i.e. no spaces or special characters). If you do not specify a report label, then this value will be used as the label also.

For our continued "Hello World" example, we'll just insert "hello_world" here.

Setting the Report Label

The "Report Label" field stores the human readable label that will be associated with your report. This is what will be displayed in the user interface for your report. This value is not subject to the same constraints as the "Report Name" field. It can contain any character.

For our example, we'll enter "Hello World" here.

Setting the Report Category

The "Report Category" field is where we specify the action category for our report (i.e. where it will be displayed in the user interface). For this example, let's select "table_actions".

Setting the Default View

There are 3 possible formats that can be used to render reports using your template:

1. List - Will render the template once for each record in the found set. Records are displayed one after another as a list.
2. Table - Doesn't use the template per se. It renders a table using the columns that are involved in the template - one row per record in the found set. Columns are arranged in the order in which they appear in the template.
3. Details - This is the same as the List format except that it only displays a single record at a time.

For our initial example, we are going to select List

Saving and Testing

Finally we can save our report. Simply click the Save button at the bottom of the form.

Now we can navigate to the table in our application that we chose in the "Tablename" field of our report template. You should notice a new option amongst the table actions (next to "New Record") called "Hello World".

Click on this link, and you should see the current found set rendered using the template we just created.

What's Next?

See also:

Getting Started

Advanced Template Creation