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.
widget:atts - To use javascripts in event handlers
and more
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.
Syntax
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:
[first_name]
[last_name]
[age]
In this example the sections are empty (i.e. they have no directives, but we could easily add some directives:
[first_name]
widget:description="Please enter your first name"
widget:label="Given Name"
...etc...
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)
[__global__]
visibility:list=hidden
[isbn]
widget:label = ISBN
visibility:list=visible
[copyright_year]
widget:label = "Year"
widget:atts:size=4
visibility:list=visible
[categories]
widget:type=checkbox
vocabulary = book_categories
[media]
widget:type=checkbox
vocabulary = book_media
[borrower_id]
widget:type=select
vocabulary=users
[due_date]
widget:description = "The date that the book is due to be returned to the library"
visibility:list=visible
[cover_art_url_small]
visibility:browse=hidden
[cover_art_url_medium]
;visibility:browse=hidden
[cover_art_url_large]
visibility:browse=hidden
visibility:find=hidden
[amazon_description]
widget:label = Description
[amazon_reviews]
[amazon_url]
[amazon_refresh_timestamp]
widget:type=static
[date_created]
timestamp=insert
widget:type = static
[date_modified]
timestamp=update
widget:type=static
[created_by]
widget:type=static
[modified_by]
widget:type=static
[notes]
This is an example from the Library DB application for the books table.
Field Directives
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.
Adds a small amount of help text to the column header for this field in list view. Default is blank. E.g. In this photo it shows the text "*Paper Uploaded" set as the column:legend for "field 1".
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.
Primarily used with password fields, indicates the type of encryption that should be used to save the field. Supports "md5", "sha1", "encrypt", and "password".
0.6
event.date
For use by the Calendar Action. Indicates that the field stores the date of the record when interpreted as an event. Possible values "0" or "1".
1.0
event.start
For use by the Calendar Action. Indicates that the field stores the start time of the record when interpreted as an event. Possible values "0" or "1".
1.0
event.end
For use by the Calendar Action. Indicates that the field stores the end time of the record when interpreted as an event. Possible values "0" or "1".
1.0
event.location
For use by the Calendar Action. Indicates that the field stores the location of a record when interpreted as an event. Possible values "0" or "1".
An optional URL for the field label to link to. This would usually be some "help" page that explains what the field is for. The link will be a link in both the view and edit tabs.
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.
The data type of the field (note the capital "T" as Xataface is case sensitive). This value is only overridden for container? fields, however its value can be accessed programmatically for any field.
A prefix for a validation type on the current field. (Replace "VALIDATOR_NAME" with the name of the validator to be used. e.g. required). There are many validators available to be used.
The name of the field grouping that this field will belong to in the view tab. If this is not present, then it will be grouped according to the group directive.
The valuelist? that should be used as the options to select. This is only applicable for fields that have options to select like a select list or a checkbox group.
A namespace for attributes that should be added to the HTML widget. This allows you to specify things like javascript events, styles, widget size, etc..
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.
1.2.7
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.
widget:atts:class Values
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."
1.3rc2
Global Directives
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.
Defines a custom select query to override the default select query for the current table. (The default select query is generally "select * from tablename").
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.
1.0b4
label
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"
title
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.
Field Groups
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:
label
order
description
template
more...
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:
By default, the "name" group will appear first in the form, followed by "contact" and "address". If we want to place "address" first we could add the following section to our fields.ini file:
[fieldgroup:address]
order=-1
Since the default order value is 0 on other groups, setting the "order" parameter to -1 will place the "address" group before all others.
Field Group Directives
The following directives are applicable in a fieldgroup section:
Specifies the order of the group with respect to other groups on the form. Accepts any numerical value (e.g. 0, 1, -1, 25.43), with lower values appearing first. Default value is 0.
