Xataface Definitive Guide

Most applications that I was building for the faculty had two parts:

The public front-end would usually be created using HTML, CSS, and standard PHP, to fetch data from the database and display it. Quite often, the website would already have a template, so it would just be a matter of fetching data from the database and rendering it inside the site’s template. For this portion of the application development, I was happy with the state of existing tools - i.e. vanilla PHP and MySQL to get the job done. Each project was sufficiently different as to not benefit from a standardized framework.

For the administrative back-end, however, the work was tedious. You needed to write forms to add new, edit, view, and delete records from each table. The user interface needed to be friendly for non-technical users, since it would be used by regular folks - secretaries, faculty members, receptionists, etc.. You couldn’t just set up a database administration app like PHPMyAdmin.

It seemed to me that, for this type of application, the database schema already included all of the information needed to generate the user interface. You could look at a table and see exactly what the form would need to look like for editing records on it. VARCHAR fields should use a text field, TEXT fields should use a textarea, DATE fields should use a date or calendar widget etc…​ If we needed to provide additional configuration, such as explicitly choosing a different widget, or adding validation rules, the developer could create config files using a logical naming convention.

The first goal with Xataface was to see how much of the administrative back-end requirements could be achieved using only the database schema. No configuration files, or custom PHP.

Of course, the first goal cannot be achieved 100%, so, the second goal of Xataface was, to the extent that the first goal cannot be achieved, how much of the administrative back-end requirements could be achieved using only the database schema, and some simple, human-friendly configuration settings.

Unfortunately, the second goal cannot usually be achieved 100%, so, the third goal of Xataface was, to the extent that the second goal cannot be achieved, make sure that the administrative back-end requirements can be fulfilled using as little custom PHP as possible.

The third goal can, in general, always be achieved.

After each application I develop using Xataface, I do a post-mortem to identify:

The ultimate goal is to move everything into the first goal, but this will likely never fully occur as there will always be some features that can’t be automatically derived from the database schema - though with the advent of machine learning, I suppose anything is possible.

At the time that I was developing the first version of Dataface, we were using the Plone content management system for the faculty’s website. If you’re familiar with Plone (circa 2005) you’ll recognize the tabs, lists, and navigation menus from the GCMS screenshots. That’s because I used the plone stylesheet as a basis for Xataface’s styles. I really liked the way Plone looked, and the stylesheet had many of the UI elements that I needed for Xataface. I needed tabs - Plone had nice looking tabs. I needed tabular lists. Plone has nice looking sortable lists. I needed navigation menus. Etc…​ Some of these elements have persisted to present day. Xataface 2.0 included a new default theme, "g2", that introduced a totally new stylesheet, but developers could still "opt out" of the "g2" theme and use the original plone theme. Xataface 3.0 finally eliminates the original theme (nearly) entirely, but if you dig you can likely still find some elements of that original Plone theme.

Aside from the stylesheet, Plone also inspired some other aspects of Xataface’s design. In particular, Xataface’s use of actions (e.g. the actions.ini file) to inject menus, buttons, and functionality into the UI are directly pulled from Plone.

I’ve already discussed the fact that FileMaker was a key inspiration for Xataface. I liked the way that FileMaker allowed mere mortals to both create and manage relatively complex databases. It was impressive that an office assistant, with no programming skills whatsoever, could build a fully-functional database application with a nice user interface in a few hours. To do the same thing with PHP and MySQL would take a software developer weeks, and it likely still would have been missing features that the FileMaker app provides out of the box.

The Xataface "Details", "Find", and "List" tabs were an answer to FileMaker’s "Details", "List" and "Find" modes.

The one mode that Xataface didn’t provide an answer for is the "Layout" mode, which is the mode of FileMaker that allows users to design their own forms using a drag and drop palette of widgets and a canvas. Xataface, instead, just used HTML for its views.

One day, I’d like to add such a tool to Xataface, but, frankly, it’s difficult to do well, and time is almost always better spent extending Xataface’s other features.

At the beginning, Xataface was just intended to be an open source alternative to FileMaker. It didn’t take long, however to start growing in its own direction. Today it has become a full-featured platform on which arbitrary data-driven web applications can be built.

Early on, I added support for modules, custom actions, and pluggable authentication. These foundational elements enabled grown into application types not originally envisioned.

Xataface was being downloaded thousands of times per week from SourceForge, and developers were contacting about a diverse range of applications that they were building. Over the next few years, I used Xataface as the foundation for many side projects including:

Over the years, Xataface has added countless features that improve the developer and user experience alike. I have enjoyed building it, and I sincerely hope that you enjoy using it to build your own creations.

Identify the data that will need to be stored for a web site.

Design the database using your favorite database administration program (e.g., PHPMyAdmin)

Tell Xataface some DB connection info, and voila! You have an application:

Some simple examples similar to those that are frequently encountered by web developers, and how dataface can be used to acheive a solution.

As a web services developer would frequently getting requests to build websites that were manageable by the site owner. Most of these requests also specify certain types of content that must be stored on the website, and much of this content needs to be n-ary (i.e., there will be multiple instances of each type of content). Let me give you an example.

Before you install Xataface, you should have a PHP and MySQL installed. I recommend XAMPP

The output of this script will look like:

This installs the xataface CLI script at ~/xataface/bin/xataface.

Xataface provides an installation of PHPMyAdmin to assist you in building a database for your application. You can access PHPMyAdmin at the URL: http://localhost:9090/phpmyadmin

Open a new browser tab with this URL, and you should see something like:

The database for this app is named "hello-world", and it is listed in the left-hand menu for PHPMyAdmin. Click on that node to expand, it, then select "New":

Let’s add a table called notes, by filling in the new table form as follows:

Press "Save" when done.

Now we want to tell Xataface to use this table in our application. Open the www/conf.ini.php file in our app. The contents will look like:

The [_tables] section is used by Xataface to generate the top menu in your application. Let’s tell it to use our new "notes" table by adding the following:

Save this file and reload the application in the web browser.

You should now see a "Notes" tab on the top.

Click on this tab, then press "New Record" to see our form for adding records. You should see something like:

This form includes inputs for all of the columns in our table, except the "note_id" column. This is because "note_id" is an auto-increment field and doesn’t require user input.

Each field uses a different type of widget according to the type of the underlying database column. E.g. the "Title" field is a text field because it is a VARCHAR column. The "note_content" field is a text area because it is a TEXT column, etc…​ You can override the widget that is used to edit any field very easily by editing the "fields.ini" file for the "notes" table, which we’ll do in the new section.

For now we will use this application as is while we explore the application interface.

Enter some dummy data into this form and press "Save". Then press "New Record", and enter another new record. Create 3 or 4 notes with different content so that we have something to play with.

Once you’ve entered a few notes, click on the "Notes" tab to return to the "List" view of the "notes" table. My app looks like the following screenshot, as I’ve entered 3 notes:

At this point we have a fully-functional database application, and you didn’t have to write a single line of code. Let’s pull the curtain back a little and see what’s going on in our application under the hood.

The "hello-world" directory that was created by xataface when we ran "xataface create hello-world" contains the following folders:

This root directory comprises a mini development environment for our application. The application itself is entirely contained inside the "www" directory, and when it comes time to deploy the app to production, we will likely only be uploading this directory to the web server.

The subdirectories in this folder include:

Out of the box, Xataface will assign appropriate labels to its form fields based on the underlying columns. However, you can override these labels very easily.

To customize labels for the "notes" table we need to create a file at www/tables/notes/fields.ini.php

The xataface CLI script will generate this file for us via the command:

As the output indicates, this created a file at tables/notes/fields.ini.php. Let’s open it up to take a look at the contents.

It has generated empty sections for each field in the "notes" table. All configuration options for a field should go in its section.

Now let’s customize some field labels and descriptions. We can set a field’s label using the "widget:label" property, and we can add some "help" text using the "widget:description" property. Let’s customize the labels and descriptions for this form by adding these properties.

After making a few changes, my fields.ini file now looks like:

Now, open your browser again and try to add a new note. You’ll notice that the form has changed:

Xataface provides sorting out of the box without the need for any configuration, but it is recommended that you configure the sorting behaviour explicitly for each table of your app. In many cases you may only want to provide sorting on a few key columns. You can use the "sortable", "sortable-", and "sortable+" fields.ini directives to explicitly mark a field as "sortable". If no fields in your table are explicitly marked as sortable, then Xataface will make a best guess. If it finds at least one field that is marked as sortable, then it will simply hand the reigns over to you (i.e. it won’t make any fields sortable that you haven’t explicitly marked as sortable, in this case).

Example:

If sorting on individual fields doesn’t provide you with enough flexibility, then you can also define actions in your actions.ini file using the "sort_actions" category.

TODO: Add documentation on using "sort_actions" category for sorting.

Xataface supports a few different filter types. Use the "filter.type" fields.ini directive to specify the filter type to use for a given field. If you do not specify this, then Xataface will try to choose the most appropriate filter to use based on the type of field. The following filter types are supported:

The following are some of the configuration options related to filtering that you can define in your fields.ini files.

As with everything else in Xataface, you can configure your RSS feeds to appear just as you want them to. The following delegate class methods are available to be defined in the table delegate class for your feed:

See RSS Configuration Directives for available configuration directives and delegate class methods related to RSS feeds.

There are 2 parts to configuring your RSS feeds:

Configuring the Feed as a whole

For configuring the feed as a whole, we have 2 options. We can specify the title, description, and link for the feed in the [_feed] section of your "conf.ini" file. This is sort of a "one size fits all" approach where all feeds generated from your application will share the same title. E.g.

However, if we want our feed’s information to depend on the user’s query (e.g. what the user was searching for, or which table the feed is generated on, we have more flexibility if we define the getFeed method in either the application delegate class or the table delegate class. E.g.

Notice that I don’t need to define all possible parameters. Any parameters that I don’t define will be provided automatically by Xataface, or it will simply use the values specified in your [_feed] section of the "conf.ini" file.

Configuring Feed Items

Configuring the feed items is quite important for ensuring that subscribers are seeing what you want them to see in the RSS feed. Xataface tries to guess appropriate content for your feed items if you don’t specify it explicitly, but you’ll likely want to tweak it a little bit to make the feed look more polished for your purposes.

Use the getFeedItem delegate class method to specify how a feed item behaves (e.g. the title, content, date, author, link). E.g.

Once again, notice that we don’t need to specify all available options. Only those options that we want to override. In this case we want the description of the feed item to simply display the body of our news item. The description of an RSS feed item is effectively the body text that the user sees why they click on an item in their news reader, so this is quite important.

You want to use a material icon for a menu-item in your application, instead of an image.

The default theme of Xataface includes the material icons web font, so you can use any icons in that font on your actions via the materialIcon directive in your action. For example, suppose we want to add a "Play" button to the rows of our table in list view. We define our action as follows:

You can browse the available material icons here.

The label below the icon is the name of the icon, that you would use for your materialIcon directive. If the lable is truncated, you can click the "Selected Icon" button in the lower left to get a more detailed view.

You want to trigger a Javascript function when the user clicks on an action.

Use the onclick directive for the action definition in your actions.ini file. The javascript you specify here will be executed when the user clicks on the action. Perhaps the "hardest" part of this recipe is simply knowing where to put the javascript function that you wish to call. There are many ways to include custom Javascript into your application. My preferred way is to use the xf_script($scriptpath) inject your Javascript file.

I’ll illustrate this process by way of an example. I’m going to create a simple action called "hello_world" that pops up an Alert box that says "Hello World".

Step 1: Create a Javascript File

If you don’t have a "js" directory in your application yet, create it now. This is where you will place all Javascript files in your application.

Now create a file inside the "js" directory named "hello.js", with the following contents.

Step 2: Include the Javascript File

You can include this Javascript file into your application by calling:

Where you choose to call this code depends on when it will be needed. If your Javascript file is only needed inside a particular page of your app, then you are probably best to call this inside the action for that page, or inside a block which only appears on that page.

If you want it to be included application-wide, then you should call this inside a method that will be called for every request. I usually place all "global" stuff inside the beforeHandleRequest() method of the Application Delegate class.

In this case, I’m not sure yet, which pages will be displaying the menu item for my "hello" action, so I’ll include it inside the beforeHandleRequest() method:

Step 3: Defining the Action

Now that we have our script included, we can define our action:

Now, we can click on our "Hello" button to see the pay-off:

Things never work the first time. There are a couple of things that can go wrong in setting up this recipe for the first time:

My "hello" Action doesn’t appear in the menu

Things to check:

Nothing happens when I click on my "hello" Action

Things to check:

You want to customize the label for an existing action

If you want to customize the action for all tables, you can simply override the action in your app’s actions.ini file, and set the label property.

Alternatively, you can use Xataface’s internationalization support to override the label. E.g. in your app’s "lang/en.ini" file (which contains your English translations), you can define the key "actions.[ACTION_NAME].label". E.g.

The above examples would override the action label in the entire application. If you want to specify the label in a particular table, you can define the "tables.[TABLENAME].actions.[ACTIONNAME].label" proeprty in your language file (e.g. lang/en.ini).

You want to customize the options in the navigation menu

Define actions in the _tables category. These will be used instead of the tables listed in the _tables section of the conf.ini to form the tables navigation menu.

The top-level navigation menu in Xataface allows you to select which database table you with to work with. By default, it is generated from the [_tables] section of the conf.ini file.

For example, given the following _tables section:

Xataface will generate a menu that looks like:

In some cases, you may want to generate your own custom menu. For example, you may want to group some tables together into a single drop-down menu. You can do this by defining actions inside your actions.ini file in the _tables category.

For example:

In this case we have defined two top-level menus in the _tables category: "menu_students" and "menu_setup". The "menu_setup" action has uses the "subcategory" property to assert that it is a drop-down menu. Any actions in the "_tables_setup" category will be included in this drop-down menu.

The resulting menu for this setup would be:

If you hover over the "Setup" menu, it will expand:

You want your action button to trigger an AJAX (background) request rather than linking to another page. Additionally you would like to provide some UI feedback to inform the user that the action is in progress. And finally, when the action completes, you would like some UI feedback to the user to indicate the result of the action, and handle errors and failures gracefully.

There are two parts to this problem:

For the Server-side, let’s create a simple action that outputs JSON. In your app’s "actions" directory, create a file named "hello.php" with the following contents:

I’ll discuss two different solutions for the client side:

See Triggering Javascript Function with Action for details on triggering a Javascript function using an action. After setting up your action, you’ll have a definition in your actions.ini file like:

Once you have your action linked up to your Javascript function you can use the jQuery.post() function to trigger your action handler as follows:

The example above will perform an AJAX request to trigger our PHP action handler. It will then display the result in an alert() dialog.

This example is overly simplistic. You can improve it in a number of ways, including:

Xataface provides a simpler alternative to providing your own Javascript function for triggering your action handler. You can simply specify the ajax=1 directive for our action:

This directive instructs Xataface to treat this as an AJAX action. When the user clicks on the action button, it will issue a POST AJAX request, and it will display the result in a status message.

When the action completes, it will display the contents of the "message" property of the JSON response in a similar status dialog. If the action fails, it will display an error message.

It expects the following properties in the JSON response:

You want to display a progress indicator when the user performs a long-running action so that the user knows that the app is doing something.

Use the xataface.showInfiniteProgress() Javascript function to show an infinite progress indicator, and xataface.hideInfiniteProgress() to hide the indicator when you are done.

Example

The above example shows the use of showInfiniteProgress() to show a progress indicator when the user initiates a network request. It calls hideInfiniteProgress() when the request completes or fails.

You want sort the related record tab on a particular column by default.

Use the table.default_sort.RELATIONSHIP_NAME fields.ini directive.

Suppose we want to sort our "posts" relationship by date posted in descending order (i.e. newest first). Then we would add the following directive to the beginning of the fields.ini file.

Xataface comes with authentication ready to roll out of the box. With a couple of configuration options in the conf.ini file, you can activate the default authentication scheme which uses a table (of your choice) in the database to authenticate against. It supports password encryption, and even includes a registration form if you choose to allow registrations for your application.

In addition Xataface’s authentication is pluggable, meaning you can write your own plug-ins to integrate your application with any authentication scheme you choose. Some authentication modules that already exist include:

By default, there is no way for users to create an account themselves. A user account would need to be set up by the system administrator first. If you want users to be able to register for accounts themselves, you can add the allow_register=1 directive to the _auth section of the conf.ini file.

E.g.

With these settings, the login form will now contain a "Register" link as shown below:

If the user clicks on this link, they’ll be taken to a registration form, which is basically a "new record" form on the Users table.

The difference between the registration form and the New record form is that the registration form doesn’t immediately add records into the database. When the user submits the form, it stores the data in a special registrations table, and sends the user an email with a link to confirm their registration. If the user clicks on this link, it will then copy the registration information into an actual record of the users table and save it.

I hate passwords. I hate having to think of a new password every time I register for a website, as I know I won’t remember it. When visiting a website for the first time in a while, I almost always need to use the "Forgot Password" function. This process is painful as it requires several extra steps, and, at the end of it all, I’m forced to create yet another password that I won’t remember.

In many cases a better option is for the site to support "Email Login" directly. The workflow for email login is simple:

To enable Email login, your users table must have an email field. You may use the "username" field to store the email address if you like, but the _auth section of the conf.ini file needs to declare which field contains the email.

With these directives in place, the login form will look something like the following:

Notice that there is a link to "log in with password". Pressing this link will toggle back to the password login form:

Also notice that there is still a "Forgot password" option, in case the user would prefer to log in with their password.

By default, Xataface authentication uses PHP sessions, which relies on a SESSION ID cookie to link requests to a session file on the server file system. The logged in username is stored in the $_SESSION['UserName'] variable. If you want to log the user out programmatically, you could simply unset this variable, or destroy the session. Most of the time, however, it is recommended that you just use the built-in Xataface workflows for login/logout.

The three most common aspects of sessions that developers want to configure are:

Example Settings

In some cases you may want your sessions to last "forever". I.e. If the user logs in once, you want them to stay logged in forever- or until they explicitly log out. Your first instinct might be to use the session_timeout directive to a really big number so that sessions last for 10 years. This is problematic for two reasons:

A better alternative is to activate "auto-login" support in your app. With auto-login support enabled, the login form will include a "Remember me" checkbox as shown below:

If the user checks this box, it will save a token on the server (in the dataface__autologins table), add a long-lived cookie. If the user tries to load a page a few days later, Xataface will first try to load the session. If none is found, it will look for an "autologin" cookie to and, if found, it will log the user in automatically, starting a new session seamlessly.

Example

Xataface supports Oauth2 authentication via the oauth module. This module provides all of core functionality to support OAuth2. There are also modules built to provide Oauth support for specific services, such as Facebook, Twitter, LinkedIn, and Instagram. These "sub" modules all depend on the core oauth module. They simply provide a few specific configuration settings to support OAuth2 on those services.

Xataface provides a REST API for authentication so that you can access your application using a REST client. When using this API, you’ll perform a request to the "login" action to obtain an authentication token. You can then make authenticated requests to your app by adding this token in the Authorization header as a bearer token.

To log in using the API, simply perform a POST request to ?-action=login&--no-prompt=1

If login succeeds, you’ll receive a JSON response with a token. E.g.

An unsuccessful login will look something like:

Once you have obtained a token, you should include this token in the Authorization header of HTTP requests. E.g.

But replace {TOKEN} with your token received during login.

To log out, simply perform a POST or GET request to ?-action=logout&--no-prompt=1

As relationships are a core feature of Xataface, it is helpful to understand how to handle permissions on related records. Even if you apply permissions to every table individually, you need to take into account the relationships that you have defined between tables, because they may open access to actions that you did not intend.

For example, suppose we have two tables: people and publications, and we have a relationship from publications table to the people table called publication_authors.

Suppose you give a user write access to a record of the publications table, but no access to the people table. If you are allowing the add new related record permission on the publications table record, then the user will still be able to add new people, via the "Add related people record" function of the database. This may or may not be desirable.

This section discusses the issues that arise due to relationships and permissions, and how to deal with them.

The Xataface permissions.ini file defines a handful of permissions that are related to the management of related records. These include:

Roles: -

You want to use a custom logo for your application instead of the default "Xataface" logo.

Use the site_logo directive in your conf.ini file to point to your custom logo image.

E.g.

You want mobile browsers to display a different logo image than desktop browsers.

Define the [alt_logos] section of your conf.ini file to specify the different images you want to use, along with the rules that define when they are used. The values in this section are used to construct a <picture> element with corresponding <source> elements for each image.

Example

In the above example, the mobile-logo.png will be used on devices with width smaller than 768px, and desktop-logo.png will be used on devices with greater tan 768px.

You want to use a .webp image for the app logo, but some browsers (e.g. Safari) don’t support the .webp format.

You want to add a custom stylesheet to your application so that you can override the default styles, and provide styles for your custom elements.

The xf_stylesheet() function can be used to inject a stylesheet into either the <head> section of the app’s page, or into the CSS bundle that is compiled by the CSSTool. Let’s start with the simplest case, where you want to include the stylesheet in the entire application (i.e. it should be loaded in every page of the app), and the stylesheet is hosted on a CDN (content-delivery network). In this case, you should place the call to xf_stylesheet() inside the beforeHandleRequest() method of the application delegate class.

e.g.

This will append a <link rel="stylesheet"…​> tag in the <head> section of every page.

If you want to host the stylesheet as part of the app, it is customary to create a css directory in your application’s main directory where you place your CSS files. So we can copy our stylesheet into this directory:

And use embed it just as before in the beforeHandleRequest() method.

xf_stylesheet() takes an optional 2nd parameter which is a flag to indicate whether the stylesheet should be included directly in the <head> section, or bundled by the CSS tool, and injected dynamically on page load.

is the same as

Which means that the stylesheet will be bundled by the CSS tool. All stylesheets in a particular request that are included using the CSS tool are bundled together into a single minified file, which is added to the document on load. The CSS tool has a set of include paths where it looks for CSS files to include, and these paths are treated as "roots" for all CSS files. The "css" directory is one of these "roots" by default. This is why we only need to specify "mystylesheet.css" in the path rather than "css/mystylesheet.css" - because all CSS files processed by the CSS tool are searched relative to the include path roots.

You can set the 2nd argument to false to simply include the CSS file in the `<head> of the document, and not have the CSS tool process it. In this case, you would need to include the full relative path to the CSS file. E.g.

With two different options for including stylesheets, you might be wondering when you should and should not use the CSS tool. Generally, I’ll use the CSS tool if I’m building a module and I want other modules and apps to be able to override the CSS file. However, if I’m just including a CSS file that will be used for my application styles, I won’t use the CSS tool.

You want to override the default color scheme with your own color scheme.

Add a custom stylesheet that redefines Xataface’s theme color variables

Xataface uses CSS variables to define the colors for its theme. You can create an entirely new color scheme by simply creating a custom stylesheet (see Adding a Custom Stylesheet) which redefines these variables. Here is a bare-bones example of such a "theme" stylesheet:

The following is an example "dark" theme for Xataface defined wholly overriding CSS color variables:

The result is:

You want to use a different color scheme depending on which user is logged in, or other run-time environment factors.

Use the user_stylesheet preference to specify the name of a stylesheet to use.

The "user_stylesheet" preference (See Preferences Directives) allows you to specify the name of a stylesheet to inject into the current request. Since preferences can be dynamically defined using the Application delegate’s getPreferences() method, you can easily use environment information such as the current user or the current URL to define a custom color scheme on a per-user basis.

For example:

Now add a CSS file as "css/fred.css" with your custom styles for fred.

See Changing the Color Scheme for details on changing the color scheme usinc CSS variables.

You want users to be able to select their own preferred color scheme.

Add a field to the "users" table with the prefs.key=user_stylesheet fields.ini property.

Xataface allows you to override preferences values using data from the currently logged in user’s record. The prefs.key fields.ini directive allows you to specify that the value of the field, in the currently logged in user record, will be used as a value for the specified preference.

As an example, let’s add a VARCHAR(100) column named "stylesheet" to the "users" table.

Add the following to the "tables/users/fields.ini" file:

Notice that we specified a vocabulary for the vield. We’ll define that in the valuelists.ini file.

E.g.

And, finally, ensure that we have added our stylesheets (dark.css and ocean.css) into the "css" directory of our app.

For details on creating custom color schemes using CSS, see Changing the Color Scheme.

Now the user can change their own color scheme, by simply editing their profile inside the app.

You want to install a custom favicon for your app.

Use the favicon block/slot.

You want to pass a parameter from the template to a block so that the block can output different content depending on the parameters.

Add parameters as as smarty parameters on the {block} tag.

E.g.

The block implementation inside a delegate class may look like:

You want to split your edit/new record forms into multiple tabs

Use the `tab`directive in each field definition of the fields.ini file to specify the "tab" that each field should be placed in.

The tab directive of the fields.ini file specifies which tab of the record edit form a field should be displayed on. Xataface supports multiple tabs on the edit form by way of this tab directive. If no fields contain the tab directive then all fields are displayed in a single tab (named main).

Example 1: Placing address info on separate tab Consider the following people table:

We want to split the fields into two tabs: "Personal Info" and "Address Info"

We’ll do this in two steps. We use the tab directive to assign all address-related fields to the address_info tab.

Now, when we load the edit form of the people table, we see two tabs: "__main__" and "address_info"

Customizing the tab labels

Next we will customize the tab labels by adding the following to the beginning of the fields.ini file:

http://media.weblite.ca/files/photos/Picture%2012.png?max_width=640

Reordering the tabs

If we want to reorder the tabs so that the "address_info" tab comes first, we would just reorder the definitions of the tabs:

Xataface allows you to delegate "new record" input to a different table. E.g. Given a Table A, you can configure Xataface to use the "new record" form for a different table B for inserting new records.

Why might you want to do this?

Xataface forms are built around the data model of the underlying table. It generates input fields for each column of the underlying table. In some cases, the "new record" form may want to take data in a different form that allows you to generate the underlying data.

For example, if you have a "Contacts" table, but you want the user to be able to insert contacts by simply entering their employee ID - and this will be used in the back-end to fetch some initial data about the user from another database. In this case, your "new record" form should really just include a single field: "Employee ID".

You want to "stamp" a record with the username or user ID of the user who created a record automatically.

Use the ownerstamp fields.ini directive on the field that you wish to store the userid in.

For example, consider a table "posts" that stores posts that users of the system make. This table has a posted_by field to record the user that posted it. You want this field to automatically populated with the user ID of the user that is currently logged in, so you can add the ownerstamp directive in the fields.ini file.

Adding this directive does a number of things simulataneously:

Before the "ownerstamp" directive existed, you could accomplish the same thing by implementing a beforeSave() trigger and setting the field value to the currently logged in user, changing the field permissions so it can’t be changed after the fact, and setting the widget type to "hidden". But since this is such a common requirement, it is much simpler to just set ownerstamp=1 and be done with it.

By default, when the user presses "Save" on the "Edit record form", they will be redirected back to the edit record form again after the save is complete. You want to redirect them to a different page, such as the "View" page.

Override the "edit" action in your actions.ini file to specify the "after_action" directive.

E.g. Add the following to your application’s actions.ini (or actions.ini.php) file.

If you only want to apply this rule to a particular table, you can use the after_action.{TABLENAME} instead. E.g.

You want the contents of a field to be automatically updated when the value of another field on the same form is changed. For example, you have a "Program Title" field that should automatically be populated when the user selects the program ID.

You can use the ajax_value fields.ini property to make a field dynamically update whenever one or more other fields on the same form is changed. When a change is detected, the field will load new data from a JSON web service specified by the URL in the property.

Syntax:

ajax_value=<url-template>#<json-path-query>

<url-template> is a string that is used as a template for the URL to the web service from which to load the field’s content. The template should contain one or more placeholders of the form {fieldname} which are replaced by the form value of the corresponding field.

<json-path-query> is a jsonPath query describing which part of the JSON response should be used as the new field value.

Triggers

The field will be updated whenever the URL would be changed. The URL template may include variables with the syntax {fieldname} that will be replaced by the corresponding field when generating the web service URL. If the values of any of the fields marked as variables changes, it will trigger an update.

Example

Consider the following fields.ini file:

[source,ini

In the above example, whenever the ProgramID field is changed (say to a value of "1"), it will trigger an AJAX request to index.php?-action=export_json&-table=Programs&ProgamID=1.

The JSON response will look like:

When it receives the response, it will take the ProgramTitle attribute of the first result in the JSON response, and place it in the ProgramTitle field. In the above example, it would be "Some program".

You want to display some richer feedback to the user based on the value entered into a field. For example, on a field where the user enters a URL, you may want to display some information about the URL so that the user knows that they have entered the correct URL.

Use the ajax_preview directive, which works just like the ajax_value directive, except that it displays the result of the AJAX request just below the field as a "preview", rather than in the field itself.

Consider the scenario where you have the following table structure:

The "posts" table is central repository of posts. The user_posts table is for a user to "post" a comment about a post. The idea is that a particular URL should only be imported into the "posts" table once, but many users can post comments around a "post" in the "users_posts" table. We will only give the user direct access to the "user_posts" table, where they will provide the URL they want to post along with a comment about the post.

The challenge here is that the user_posts table doesn’t have a "page_url" field - just a post_id field. We could use the depselect widget here, but this adds a step. It would be better to hide the post_id field, and just provide a page_url field, which will automatically populate the "post_id" field with the correct post ID from the posts table.

So for our first step, we’ll hide the "post_id" field and add a page_url transient field:

When the user enters a URL into the post_url field we want to trigger an AJAX request to a custom action that will:

In either case the AJAX request should obtain a post ID which can be inserted into the post_id field.

Such a custom action might look like the following:

We will use the ajax_value directive on the post_id field to automatically populate it from that AJAX action when the value of page_url changes.

Lastly, we want to display a preview of the page content below the page_url field. We will use the ajax_preview directive for this. First we’ll create an AJAX action to display this preview, given the post ID.

Now we can use this from our `ajax_preview directive:

Bonus Points

We’re not quite done. Our current setup works great for the new record form, because the user will be adding the URL. But if they’re editing an existing record, the post_id value will already by set, but the user hasn’t entered anything the post_url field (because it is transient). We need to add an ajax_value directive to the post_url field so that it auto-populates based on the value of the post_id field.

We’ll use the export_json action as our AJAX action so we don’t need to create a custom action.

You want to disable client-side validation for a particular field, but keep the server-side validaton.

Use the widget:validation=server fields.ini directive.

E.g.

You have a grid widget for editing related records on a form. Rather than have it start with only a single row, and have additional rows appear only as the user enters data into the last row, you want it to display a fixed number of rows and have some of the data pre-populated.

Use the widget:fixedrows directive to a specific number of rows, and you can implement the fieldname__prepareGridData($record, $cols, $data) delegate method to return the data to prepopulate the grid with.

You want to add an an action button next to a field in your form. For example, suppose you have a text field that stores the URL to a logo for the record, and you want to provide a link for the user to be able to upload an image, and then copy its URL into the field. Ideally the field would have an "upload" button next to it.

Use the actions directive of the fields.ini file to specify an action category on the field, and then define an "upload" action with that category.

E.g.

And the result:

You want to add a drop-down list for the user to select filters for the result set.

Use the filter directive in the fields.ini file on any field that you want the filter to be added for.

Now, if you navigate to this table’s list view, you’ll see a drop-down list at the top of the results where you can select all of the distinct values in the test_field column.

If you select one of the options, it will filter the results to only show those results that match the filter.

You want to hide the counts for each entry in the "filters" drop-down list on the list view. By default when you add a filter list via the filter directive, each row has the "count" displayed beside it:

We want to hide this.

Use the show_filter_counts preferences directive to hide these counts as follows. In the _prefs section of the conf.ini file, add:

After this change, the filter lists will look like:

Filter lists are sorted by the "filtered" field in alphabetical order. You want to sort the filter lists on some other column.

Use the filter.sort. fields.ini directive to specify the field that the filter should sort on.

E.g.

You want to add custom CSS classes to the rows of the table in list view.

Implement the css__tableRowClass() method in the table delegate class. Have it return a string with the CSS classes you wish to add.

In the above example, on rows where the 'status' field is a approved you’ll see something like:

and in other rows you’ll see

You want to add a button to each row of the list view to perform some action on that row.

Define an action with category=list_row_actions and condition="$query['-table'] == 'tablename'.

E.g.

You want to customize the style on a particular action

Use the class directive on the action to specify a custom CSS class on the <a> tag of the action. Then use this CSS class to target that button specifically from your stylesheet.

Then in your CSS file you can target this action directly:

You want to trigger a Javascript function when the user clicks on a row action instead of just directing the user to a URL.

Use the onclick directive instead of the url directive.

See Triggering Javascript Function with Action for an introduction to Javascript actions with a detailed example using the onclick handler. The only thing we need to add to make our Javascript action useful, is the ability to retrieve the record ID of the current row. There are two ways to do this:

e.g.

An alternative way is to make user of the xf-record-id attribute that can be found on the <tr> tag of the row in list view. If you look at the resulting HTML source of the list view, and drill down to the individual rows of the table, you’ll see something like:

We can use this inside our Javascript function, as follows. First we pass this as an argument to our function. this will refer to the <a> tag that was clicked.

You want to add an action to each row of the list view that can be toggled between two different states. For example, we have functionality to add and remove rows from a playlist. If the record is currently "on" the playlist, we want the action to display "Remove from playlist". If the record is not on the playlist, we want the action to display "Add to playlist".

Use two different actions: "add_to_playlist" and "remove_from_playlist" and conditionally show either action depending on whether the record is currently "on" the playlist.

I’ll include two different recipes here to achieve this:

The 2nd option is more complex but yields a better user experience.

We can define our actions as follows: (And assume that our table has an "on_playlist" field that indicates whether or not a record is on the playlist currently.

The key here is in the condition directives of these actions. The add_to_playlist is set to appear only when we are on the _tmp_newsfeed table AND the record is not on the playlist. The remove_from_playlist action is set to appear only when the record is on the playlist.

There is a lot hidden in this solution inside the addToPlaylist() and removeFromPlaylist() Javascript functions. These are responsible for actually adding and removing records from the playlist. See Using AJAX To Modify Row Records for an example using AJAX to do this.

The first solution relies on the condition directive to show or hide our actions. However, this directive is processed on the server-side, so we would need to reload the whole page if we wanted to update state. We can offer a better user experience by using CSS to show/hide the actions.

The gist of this solution is to:

Adding the CSS class to the <tr> tag:

Adding CSS classes to the two actions:

Defining Styles to Show/Hide Actions

Now that we have our CSS actions defined, we’ll be dealing with HTML like:

Now we can target our <a> tags with the following CSS directives in our stylesheet.

Adding/Removing CSS classes using Javascript

As we’ve seen above, our actions will trigger the addToPlaylist() and removeFromPlaylist() functions respectively. We just need add/remove the CSS class as appropriate here.

e.g.

You need to perform a server-side action when the user clicks on a row action. E.g. From Making Row Actions Toggleable, we needed to add and remove the row record from the playlist.

Create a custom action handler that performs the the function, and returns JSON, and write a Javascript function that calls this AJAX action.

TODO: Need to write this solution

You want the records in a particular table to be sorted on a particular column by default.

You want to display the "list" view as a grid for one or more tables in your app.

Add list_template=@grid to the beginning of your table’s fields.ini file.

This will cause the list to use the actions/list/grid.html template for rendering the list view.

Note: For the "grid" layout to make sense, you should have at least one image column column in the table. You can specify a column as an "image" column by adding the image=1 fields.ini directive.

The Xataface list view is responsive, and renders lists differently on mobile devices than on desktop. In some cases you may prefer to use the mobile list style on desktop also to achieve a unified look.

Set the table.listStyle=mobile directive in the table’s fields.ini file. This is a table-level directive, so it should be at the top of your fields.ini file, before any of the field definitions.

Let’s look at a quick example. Here is a list using the mobile theme.

Here is the same list when viewed on a desktop:

Now, I’ll add the table.listStyle=mobile directive to the beginning of the table’s fields.ini file.

The result is:

You want to render the rows of your table such that they summarize some external web page, and provide a link to it, similar to the way that Twitter renders tweets that contains a link to a webpage.

Use the table.listStyle=mobile fields.ini directive in conjunction with the table.row_style=external-link directive, and implement a calculated field on the table named external_link as I will describe below. The result will be something that looks like:

You want to create a synthetic field, and display it in the view tab just as you would with all of the regular fields.

Tuxpin includes a podcasts table that allows users to create their own podcast. Each podcast has a unique ID, which is stored in the podcast_uuid column. It also provides a website for the podcast, which is located at a URL of the form:

https://podcasts.tuxpin.com/{podcast_uuid}

Beause the website URL can be derived from the podcast_uuid, we don’t need to actually store it in the database. However, we would like to display this URL in the View tab.

To achieve this, we first define the website_url field in the delegate class as follows:

By default synthetic (or calculated) fields are not displayed in the view tab (or anywhere in the UI, for that matter). You need to set the visibility:browse property of the field to visible, in order to have it appear in the view tab.

So, in the table’s fields.ini file we add:

And the result:

We can now treat this field like any other field in our view tab. We can further customize using configuration options and delegate class methods, just as we would with a real field.

You searches on a particular column to be case-sensitive. (E.g. If the user searches for "Bob", it should match "Bob" but not "bob").

Use the collate fields.ini directive to "utf8_general_cs" (or any other supported collation that is case-sensitive.

E.g.

[source,ini

By default, the case-sensitivity of searches depends on the collation of the underlying table and column in MySQL. If the column was defined with a case-sensitive collation (e.g. utf8_general_cs), then all searches on this column will be case-sensitive. If, however, it was defined with a case-insensitive collaction (e.g. utf8_general_ci), all searches will be case-insensitive. If you want to change the behaviour of the app, you could simply change the underlying collation. But in some cases you may not want to modify the table structure (or you won’t have access to the table structure). In such cases, the "collate" directive is helpful.

You want to perform a case-sensitive search on a field that has a case-insensitive collation.

Wrap the query value in a command wrapper, and use the "cs" command to specify "case-sensitive" (or "ci" to specify case-insensitive").

E.g.

If you want to search for "Bob" in the name field, enter the following in the search field for "Bob".

If you, instead wanted to explicitly perform a case-insensitive search you would enter

The main search box at the top of the application searches for matches in all of the char, varchar, and text fields by default. What if you want to only match against specific fields?

By default the contents of blob fields and container fields are downloaded as a file download in the browser. You want the browser to navigate to the file instead of downloading it.

Use the contentDisposition=inline fields.ini directive.

Now, when users click on the link for this field, the browser will navigate to the field content.

I want to automatically resize uploaded images to specific dimensions.

Use the transform property on the Container field in the fields.ini file.

In the above snippet, I’ve defined two thumbnail sizes for uploaded images:

The transform directive will cause images to be automatically resized at the time that the images are uploaded, but it doesn’t specify how and when the thumbnails are used. You might want a small (100px) thumbnail used when displaying the record in list view, and a slightly larger image (640x480) used in the view tab. In the above example we’ve defined two thumbnail sizes "itunes300" and "itunes1400".

The default behaviour is to display the first thumbnail type defined in all situations. If you want a particular action to use a different thumbnail by default, then you can use the thumbnail.ACTIONNAME fields.ini directive to specify this.

For example, if you want the "view" action to use the "itunes1400" thumbnail, you would add the following:

So the full snippet becomes:

Rather than storing uploaded files directly on the server file system, you want to store them on Amazon S3 for scalability purposes.

Use the s3 module.

Installation Instructions

You can find installation instructions for the s3 module in the README.

Configuration

Once the module is installed, you need to add some configuration to your app’s conf.ini file.

fields.ini Configuration

In addition to the conf.ini configuration, you need to add the s3.bucket directive to any Container fields that you wish to store on S3, to specify the name of the bucket where it should store the files.

The key properties in the above example are:

You want your application to use a default action other than the Xataface default, if the user doesn’t explicitly provide an "-action" parameter.

Use the default_action conf.ini directive.

E.g.:

This would result in the user being directed to the "find" action by default.

You want to specify a default action only for one table in your application. The "default_action" conf.ini directive sets the default action application-wide.

Use the default_action.tablename directive in your conf.ini file. (tablename should be replaced with your desired table name. For example, suppose I want to make the "view" action the default action for the "posts" table, then I would define the following at the beginning of the conf.ini file:

You want to supply additional query parameters for your default actions. These parameters should only be applied when the default action is used.

Use the default_params.tablename directive. E.g.

These default parameters will be used if the user requests a URL like:

The above would effectively be the same as:

The above example shows the default_params.posts directive specified as a URL-encoded string. However, you can also define the parameters as a section.

E.g.

This would be equivalent to

By default, when the user clicks on a record to see its details, they will be shown the "View" tab. You want to show them the "Edit" tab instead.

Use the default_browse_action directive of the conf.ini file. This directive is analagous to the default_action directive, except it is only applied when the user requests the "browse" action, which is the default action used for displaying record details.

The direct solution to our problem would be the following at the beginning of the conf.ini file.

You have specified a custom action that you are using as the default "browse" action for your table via the default_browse_action.mytable=myaction directive. However your action requires some additional query parameters to work correctly. You need to add these default parameters somehow.

Use the default_browse_params.tablename directive to add parameters to the browse action. This directive works similarly to the default_params.tablename directive. E.g. Let’s add a "foo" query parameter by default when the user accesses the "browse" action on the "posts" table.

When the user clicks on a record in the "list" view, you want them to see a related record tab instead of the "View" tab by default.

We can achieve this by way of the default_browse_params.tablename conf.ini directives. For example, suppose we wanted to show the "authors" relationship of the "posts" table by default when a post’s details are shown:

Notice here, that we didn’t actually need to use the default_browse_action parameter to specify that it should use the related_records_list action (which is the action used to display a related list). Xataface infers this by the presence of the "-relationship" directive.

You want to create a user-specific SQL query and navigate its results as if it were a proper table. You want the results of this table to be different for different users.

There are a few strategies that you could use for this. You could simply use a MySQL view, and set up a security filter on the table. In some cases, this may not be flexible enough, though. In such cases you can use a dynamic query.

You can create a dynamic query as follows:

For example, let’s add a dynamic query called "my_posts", which is basically just a list of posts that the current user has posted. This provides an easy way for the user to generate a feed of his own posts.

First we’ll create the _tmp_my_posts directory, inside the "tables" directory. Then we’ll add our fileds.ini.php file:

You can access this "table" just as you would, a normal table. Just remember that the full table name is "_tmp_my_posts". E.g. If you go to "index.php?-table=_tmp_my_posts", it will show you these results.

When xataface receives a request for a table whose name starts with "tmp" it begins by performing the __sql__ and loading the results into a temporary table. This operation is very fast because temporary tables are typically stored in RAM, and they are only usable in the current session (i.e. other users cannot see this table).

You need to change a setting in your php.ini file but you don’t know where it is, or your server has multiple php.ini files and you don’t know which one is the correct one.

Create a file inside your application directory named "phpinfo.php" with the following contents:

Load this page in your web browser and search for "php.ini".

Now open that file and make your changes.

You want your production server to use different configuration options than your development server. For example, perhaps you want to enable the output cache on the production server, but not on the development server.

You want to deploy the changes in the development version of your app to the production server, including database changes.

Increment the build number in your app’s version.txt file, and implement corresponding update_xxx() methods in your conf/Installer.php file.

One of the more annoying challenges involved with managing production web applications is keeping the development and production versions in sync. Git makes this task trivial for source code and file system changes, but changes to the database schema between versions still need to be handled with care, as these changes fall outside the watch of any version control system.

For example, suppose I am running an application that stores user profile information, and I want to add a column to the “users” table to store the user’s postal code. I add the column to my development database but I don’t want to add it to the production database until I am finished with the rest of my changes.

The old way: Copy & Paste – text files

The old way managing these changes was to make the change in the development database, then copy and paste the SQL query that I used to perform the update into a text file. I would repeat this process for each change that I made. When it came time to move the changes to the production application, I would just execute these statements manually one by one on the production server.

The down-side of this approach is that it didn’t scale very well. It works OK if I only have one production installation and one development server. But what if I have dozens of production servers all running the same application, and perhaps running different versions. It would become cumbersome if not impossible to keep track of all of these changes and manually apply them across all installations.

The new way: Xataface Application Versioning

Xataface allows you to track the version of your application with a text file named version.txt stored in your application’s directory. This file should contain one line like with two numbers separated by a space:

1.0b1 345

This example means that the application version is 1.0b1, and that the build version is 345. The build version must be an integer that is incremented every time there is a change to the source code. It is used by Xataface to figure out whether the file system version matches the database version.

On every page request, Xataface checks the version.txt file to see what version of application is currently in the file system. It compares this with the version of the database. If the database version is lower, it will execute the necessary queries to update the database to the current version.

Xataface looks for a class named conf_Installer located in your application’s "conf/Installer.php" file to find out what it needs to do to update between versions. You can define methods in this class of the form:

function update_##(){}

Where ## is the build number of the update.

Xataface will execute all functions update_XX() to update_YY() in your conf_Installer class automatically if it finds that the database version is XX and the filesystem version is YY. This is where you can place your database updates that need to be performed between versions.

For example, suppose the production server is running build version 345. That means that the version.txt file in your production server might look something like:

0.5.1 345

Now you want to add a postal_code column to the users table in the development version, so you’ll increment the version number on the development server:

0.5.2 346

And add a method to your conf/Installer.php file to perform the database change:

Then you can just update the source files to the production server using subversion. The first time you run the production app after updating the source files you’ll get a message saying that the application has been updated to version 346.

That’s all it takes. You just keep on adding these methods for each update. Then even if you have an instance that is a couple of versions behind, all you need to do is update to the latest source revisions, and it will automatically update the database to the correct version.

The theme is fully responsive, meaning that it will automatically render the appropriate UI based on the size of the window. Currently the threshold occurs as a window width of 768 pixels. If the window is wider than that, it will render the desktop UI. Narrower, and it will render the mobile theme.

When in "mobile" mode, the body tag will include the "small" CSS class. When in "desktop" mode, it will include the "large" CSS class. This will allow you to define CSS styles that target mobile or desktop separately. E.g.

A Javascript event is fired both when entering and exiting mobile mode. You can use these events in your Javascript code to be notified when transitioning between modes. E.g.

For more information about these events, see Javascript Events.

The header and footer components of the mobile theme have "fixed" positions.

The size of these components may change as it is possible to add and remove contents from these components. It is also possible to hide them in some contexts.

Xataface automatically configures the body padding so that these do not obscure other content on the page. If you are using fixed or absolute positioning, you should be aware of these components. You can use the xf-viewport-changed Javascript event be be notified when the size of the header or footer is changed. For example, the FAB component is designed to hover in the lower right corner of the page, but it shouldn’t overlap the bottom tabs, so it needs to be positioned relative to the "mobile-footer" component. It uses the following code to accomplish this:

You can hide the mobile-header and/or mobile-footer components by adding "no-mobile-header" and "no-mobile-footer" CSS classes to the body tag respectively.

The mobile footer is a handy place to add content that you want to display in a fixed position at the bottom of the screen. The following snippet shows how to add a component to the top/beginning of the mobile footer.

The table tabs (i.e. "Details", "List", and "Find") are rendered in the mobile footer by default. These are taken from the same actions as the table tabs in the desktop UI. You can add/remove options to this menu by adding actions to the "table_tabs" category.

Like the header and footer, you can hide the table tabs in mobile using the "no-table-tabs" CSS class on the "body" tag.

For example, the "edit" action includes the following snippet to remove the header, fab, and table tabs.

The table actions menu is rendered using a floating action button. You can hide this by adding the "no-fab" CSS class to the body tag.

To add options to the FAB, simply add actions to the table_actions_menu category, and make sure they have a materialIcon directive. See Using Material Icons for more about material icons.

The rows of the list view use different mark-up in mobile than in desktop. Both versions are rendered in HTML, but only one of them is visible at any given time.

There are 4 core content elements of a row in the mobile theme:

You’ll notice that the mobile list view doesn’t include any paging buttons (e.g. "Previous" or "Next"). This is because it uses infinite scrolling. When the user scrolls to the bottom of the list, it will automatically load the next 30 records and append them to the end of the list seamlessly.

Stand-alone attributes for an INI file must appear at the beginning of the INI file (before any of the sections). The conf.ini may contain the following stand-alone attributes.

The relationship.ini file is a configuration file which is associated with a single table of a database application. It provides metadata about the table’s relationships to other tables to help Xataface dictate how they should be included in the application.

The following directives may be added to a field’s section of the relationship.ini file to customize the field’s behavior. Some directives are not applicable to all fields.

In the view tab, related records are shown by default in the left column. These sections are called glance lists. The field directives below customize how the glance lists are displayed.

See Relationship Permissions

As with the fields.ini file and the valuelists.ini file, the actions.ini file uses the simple INI file syntax to define its actions. Each action is defined in its own section, and can have a number of directives to specify the action’s behavior.

Here is a snippet from the Xataface actions.ini file to give you an idea:

This snippet shows the definition of the browse, list, and find actions - three of the most central actions in a Xataface application. Notice how each action has its own section (according to INI file syntax?) with a number of directives which specify how the action behaves. For instance, each action has a "category" value of "table_tabs", which tells Xataface to display the actions as part of the table tabs in the user interface.

Notice that the url, condition, and url_condition directives allow you to use a PHP expression for their values. In order for this to be helpful, you should know a little bit about the context and environment in which these expressions will be executed. All expressions are evaluated immediately prior to being rendered, so the same action can be displayed multiple times in the same page, but have very different resulting values for their urls and conditions.

These expressions are all executed within the context of the Dataface_Application::parseString() method, with the following variables loaded in the local symbol table (i.e. you can use the following variables in your expressions).

The category directive of the actions.ini file is used to specify where an action should be displayed in the UI. Xataface includes a number of built-in categories that you can leverage to inject menu items and buttons into various parts of the UI. Some of these are:

Permissions are defined by standalone properties in the beginning of the permissions.ini file. For example, if you were desiging a proof-reading application, you might need permissions for "submit_for_proof", or "approve_text" to correspond with the submitting a document to be proof-read, and approving a document’s proof. In this case we would have the following at the beginning of our permissions.ini file:

The left side of the equals sign is the name of the permission. The right side contains a human readable description of the permission and what it is for.

At this point these permissions don’t do anything. In order to be useful we need reference these permissions from an action or a section. For example, let’s create an action called "submit_for_proof" which displays a form for a user to submit a document record to be proofread.

Our actions.ini file entry might look something like:

And for completeness, since this make-believe action specifies th "submit_for_proof.html" template, we’ll create the "submit_for_proof.html" template in the templates directory:

Finally, in order to benefit from permissions, your application has to decide that it is going to use permissions (unless you define a getPermissions() method, users are granted ALL permissions by default. Hence if you try to access our submit_for_proof action, we’ll see it without any problem. Regardless of who we are. So let’s create a simple, but restrictive getPermissions() method in our application delegate class:

Now if we try to access our submit_for_proof action it will give us a "Permission Denied" message, because we are only granted READ ONLY permissions (which is a role that includes the view permission and some others - but not our custom "submit_for_proof" permission.

Now we’ll make a small modification to our getPermissions() method to provide us with our submit_for_proof permission:

Now if we try to access our submit_for_proof action, it will show us our template with no error messages (hopefully).

Roles are sets of permissions. They are defined in the permissions.ini file as sections with lists of included permissions. It might be handy to create roles such as EDITOR or MANAGER which contain sets of permissions that are meant to be assigned to users of those types. For example an EDITOR may have the view and edit permissions, but not the delete permission. A MANAGER might have the view, edit, and delete permissions. You can define these two roles in the permissions.ini file as follows:

Then we could assign these roles to users using the Dataface_PermissionsTool::getRolePermissions() method:

Or equivalently we could use the getRoles() method of our delegate class instead of getPermissions():

Xataface is distributed with its own permissions.ini file that defines some core permissions and roles. You can look at this permissions.ini file (located in the xataface directory) to see what the format should look like. Any settings you place in your application’s permissions.ini file will augment or override settings in Xataface’s file.