The fields.ini file is a configuration file which is associated with a single table of a database application. It provides metadata about the table's fields to help Xataface dictate how they should be included in the application. This includes metadata such as
Widget type - To specify the type of widget that should be used to edit content in the field (e.g. text, select, checkbox).
Label? - The labels that can be used in column headers and on forms.
Help text? - for forms to inform the user how data should be entered.
Although a table doesn't need to have an associated fields.ini file in order for the application to work, each table can have one; and it is always located in the table configuration directory?. For example, the fields.ini file for the people? table would be located at Site Root?/tables/people/fields.ini file.
The fields.ini file uses standard INI syntax? (just like the php.ini file), where each section corresponds to a column in the table.
For example, consider a table "people" with columns "first_name", "last_name", and "age". The fields.ini file for the people table could then contain sections for each of its columns as follows:
In this example the sections are empty (i.e. they have no directives, but we could easily add some directives:
widget:description="Please enter your first name"
Here we have told Xataface that the first name field should include some help text (using the widget:description? directive) on its edit form.
Example fields.ini file
;; Global directives applied to every field (requires Xataface 1.2.6)
widget:label = ISBN
widget:label = "Year"
vocabulary = book_categories
vocabulary = book_media
widget:description = "The date that the book is due to be returned to the library"
widget:label = Description
widget:type = static
This is an example from the Library DB application for the books table.
The following directives may be added to a field's section of the fields.ini file to customize the field's behavior. Some directives are not applicable to all fields.
Specifies the layout of the field on the edit form. Most fields have an implicit value of "inline" meaning the widget and its label appear on the same line. Textareas and htmlareas have an implicit value of "block" meaning that the label and widget appear in separate rows (label above the widget). You can set this value explicitly also to override the layout of a field.
Boolean value (0 or 1) indicating whether this field should be ignored on the edit form. This is handy if the field is going to be constantly updated in the background (via a cron job perhaps) and you don't want the edit form to interfere.
Boolean value (0 or 1) to indicate if this field should be treated as a logo field. Logo fields are displayed in the upper left of the view tab? for a record, and are assumed to contain an image. If no logo field is explicitly specified, Xataface will make a best guess as to which field should be used.
Boolean value (0 or 1) to indicate if this field should be linked when in list view (or in a related list). Default value is 0 to indicate that the field IS linked. It is common to use this directive when using a custom xxx__renderCell() method that contains its own links.
A flag to indicate that this field can not be used as part of a query. This is helpful if you want a field to remain completely confidential to prevent people from finding records based on the value of this field. This flag is even necessary if the permissions for the field don't permit viewing the value of the field.
A boolean flag for use with container fields? to indicate that it should use secure URLs for the file downloads (i.e. it will obey the application permissions). Without this directives, uploaded files are served directly by apache and don't obey the Xataface permissions defined per record.
A boolean (0 or 1) value indicating whether this field is considered a structure. A value of 1 indicates that this field is a structure and should not be truncated under any circumstances. Normally fields are truncated at 255 chars in list view. This is useful if the field contains XML or other structured data so that attempts to truncate it would destroy integrity.
Boolean value (0 or 1) indicating whether this field is a transient field or not. A transient field is a field that is defined in the fields.ini file but not in the database. Hence the values that are input into this field on the edit form are not saved to the database.
Text displayed just before the widget. This is almost the same as widget:description? except that this text is guaranteed to be displayed before the widget, whereas widget:description? may be displayed below or beside the widget.
A flag for use with calculated fields (i.e. fields defined in the delegate class? via the field__fieldname method) that will include the field in XML output produced by the export xml action?. Default is 0, but setting this value to 1 wil cause the field to be included.
Applying Directives to All fields (__global__)
Xataface 1.2.6 includes support for a __global__ section that allows you to specify directives that should be applied to all fields. These directives can be overridden on a field by field basis. The __global__ section can take all the same directives that a normal field section takes.
The widget:atts:class directive allows you to assign a CSS class to a field's widget. There are certain CSS classes that have meaning to Xataface and will cause additional functionality to automatically be added to the field. These built-in classes are listed below:
Applicable only to password fields. If you set widget:atts:class=passwordTwice, then this will convert the password field into two fields whereby both fields need to match in order for submission to continue on the edit form. This operates as a password verification field."
The following directives can be added to the beginning of the fields.ini file (before any field sections) to customize field groups and the table as a whole.
A comma-delimited list of tables that this table is dependent upon for caching purposes. E.g. if any table in this list is modified, then the query cache is cleared for queries on this table. See this blog article for more information about query caching.
A comma-delimited list of tables that this table/view is derived from. This is used with the query caching feature and is necessary to use this directive if the table is actually a view. If this directive is not set, then any queries involving this view will not use the query cache because Xataface would have no way to discern the update time of the view. See this blog article for more information about query caching.
Sets preferences for this table and its records. This directive is an array, so it must be enclosed in square brackets, i.e. [__prefs__], unlike the other global directives listed above.
Sets the friendly name for this table. This is the equivalent of using the [_tables] section in the conf.ini file, except without imposing the requirement that these tables appear in the application's primary navigation menu. E.g. label = "Table Name"
A string SQL select expression that is used to describe the title of records. This is the equivalent of the titleColumn() function used in Delegate_class_methods.
The group directive allows you to group multiple fields together so that they will be rendered in the same field group on forms. You can also configure these groups as a whole by defining a section named "[fieldgroup:GROUPNAME]" (where GROUPNAME is the name of the field group, corresponding to the group directive values for the fields) in the fields.ini file. This section provides a few basic directives to customize some aspects of the field group:
The most common use of these sections is to customize the label or order of groups, especially when there are multiple field groups in the table. For example, suppose we have a table "people" with fields "first_name", "last_name", "phone", "fax", "email", "address", "city", and "country". Suppose these fields are grouped as follows: