-
Notifications
You must be signed in to change notification settings - Fork 58
fields.ini file
Steve Hannah edited this page Sep 2, 2016
·
1 revision
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.
- Field Groupings
- widget:atts - To use javascripts in event handlers
- and more
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.
;; 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.
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.
| Name | Description | Version |
|---|---|---|
| column:label | Specifies a custom label to use in list view for the column. If this is not specified, then the value of widget:label will be used. | 1.3 |
| column:legend | Adds a small amount of help text to the column header for this field in list view. Default is blank. E.g. <br/><img src="http://media.weblite.ca/files/photos/Screen%20shot%202011-02-08%20at%205.05.55%20PM.png?max_width=640"/><br/>In this photo it shows the text "*Paper Uploaded" set as the column:legend for "field 1". | 1.3 |
| date_format | Specifies how the field should be formatted when displayed. Takes same parameters as PHP strftime function. | 2.0 |
| display | 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. | 0.8 |
| display_format | A pattern that can be used to define the display format of the field. This takes the same parameters as the PHP sprintf function. | 2.0 |
| encryption | 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". | 1.0 |
| filter | Boolean value (0 or 1) indicating whether this field should be filterable in list view. | 0.8 |
| frozen_description | The field description shown when the widget is frozen (i.e. uneditable). If this is not specified, no field description is shown in this case. | 1.2 |
| group | The name of the field group that this field belongs to. Fields with the same "group" value will be rendered in the same field group on the form. | 0.5 |
| Key | If you are using a View for the table you need to explicitly mark the fields that comprise the primary key. E.g. Key=PRI | 0.6 |
| label_link | 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. | 1.1.3 |
| ignore | 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. | 1.0 |
| logo | 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. | 0.7 |
| money_format | For fields containing monetary amounts, this specifies the format. Takes same parameters as PHP money_format function. | 2.0 |
| noLinkFromListView | 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. | 1.1 |
| not_findable | 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. | 1.1 |
| number_format | For numeric fields, this indicates the number of decimal places to display when displaying this field. E.g. 2 | 2.0 |
| order | The order of the field when laid out on forms and lists. Can contain any floating point number or integer (e.g. 0, 10, -10, 235.4) | 0.6 |
| relationship | Used only with complex fields that involve editing related records (e.g. grid). This is the name of the relationship that the field should be edited. | 0.8 |
| repeat | Boolean value (0 or 1) used in conjunction with a select widget to indicate whether to enable a multi-select. | ? |
| section | The name of the section that this field should belong to in the view tab. | 0.7 |
| secure | 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. | 1.3 |
| struct | 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. | 1.1.2 |
| tab | If tabbed forms are enabled, then this specifies the name of the tab that this field belongs to on the edit form. | 0.8 |
| timestamp | Indicates when a timestamp should be set in the field (only applicable for date and time fields). Possible values are "insert" and "update" | 0.7 |
| Name | Description | Version |
|---|---|---|
| title | Boolean value (0 or 1) indicating whether this field should be treated as a title field. | 0.7 |
| transient | 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. | 0.8 |
| Type | 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. | 0.5 |
| validators:VALIDATOR_NAME | 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. | 0.5 |
| validators:VALIDATOR_NAME:message | The message the should be displayed if the form fails to validator due to the "VALIDATION_NAME" validation rule. | 0.5 |
| viewgroup | 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. | 1.0 |
| visibility:browse | Indicates whether the field should be visible in browse mode (i.e. in the "view" tab). Possible values are "visible" and "hidden". | 0.6 |
| visibility:csv | Indicates whether the field should be included in CSV exports. Possible values are "visible" and "hidden". (1.0 beta 4) | 1.0b4 |
| visibility:find | Indicates whether the field should be visible in find mode. Possible values are "visible" and "hidden" | 1.0 |
| visibility:list | Indicates whether the field should be visible in list view. Possible values are "visible" and "hidden". | 0.6 |
| visibility:update | Indicates whether the field should be included in update and copy/replace forms. Possible values are "visible" and "hidden". | 1.3 |
| vocabulary | 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. | 0.5 |
| widget:atts | 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.. | 0.5 |
| widget:columns | For checkbox groups, this specifies the number of columns to use for laying out the checkboxes. | 1.0 |
| widget:description | Help text to give the user a hint about how to edit the field's content. | 0.1 |
| widget:editor | The type of HTML editor that should be used. This is used only when widget:type is set to htmlarea Acceptable values include: | all |
| widget:editvalues | Used with select lists to allow users to add values to the select list. E.g. widget:editvalues=1 | 0.8 |
| widget:focus | Sets default focus. 0 or 1. (Javascript focus in a form) | 0.6 |
| widget:label | The label that should be used for the current field on edit forms, column headings, and other relevant locations. | 0.1 |
| widget:question | 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. | 0.1 |
| widget:type | The type of widget that should be used (e.g. checkbox, select, text, etc..) | 0.1 |
| xml | 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 |
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:
| Name | Description | Version |
|---|---|---|
| passwordTwice |
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.
| Name | Description | Version |
|---|---|---|
| __dependencies__ | 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. | 1.2 |
| __isa__ | The name of the parent table of the current table. This directive allows you to have a heirarchical structure amongst the tables in your application. | 0.8 |
| __source_tables__ | 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. | 1.2 |
| __sql__ | Defines a custom select query to override the default select query for the current table. (The default select query is generally "select * from tablename"). | 0.7 |
| __prefs__ | 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#toc10. |
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...
- "first_name" and "last_name"
- "phone", "fax", and "email"
- "address", "city", and "country"
[first_name]
group=name
[last_name]
group=name
[phone]
group=contact
[fax]
group=contact
[email]
group=contact
[address]
group=address
[city]
group=address
[country]
group=address
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.
The following directives are applicable in a fieldgroup section:
| name | description | version |
|---|---|---|
| order | 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. | 0.6 |
| label | Specifies the label that should be used for the field group. | 0.6 |
| label_link | Specifies a URL that the field group label should link to. | 1.1.3 |
| template | The path to a custom template that should be used to render the fields of the field group. | 1.0 |
| collapsed | Boolean value (0 or 1) indicating whether the field group should be collapsed by default (user can expand it). | 1.0 |