The Collection Definition File

Collection definition files live in the inc/app/cms/conf/collections folder. They are INI-formatted files with a .php extension, which we'll explore further in a moment. In Sitellite apps, it is standard to keep these files in the app's install folder, with the installation instructions to copy them to the collections folder upon installation. See the apps available on sitellite.org for examples.

Definition Header

A collection definition file always begins with the same three blocks: [Collection], [Source], and [Store]. These blocks describe the general behaviour of the collection, and tell Sitellite which source and store drivers to use to access its data and store new revisions.

[Collection]

The collection block describes the essentials of your collection to Sitellite. This includes a display name, some of the important field names, etc. The full list of properties in this block are:

• name (required) - The actual name of your collection. This field must match both the source database name as well as the collection definition file name.
• display (required) - A pleural display name to refer to your collection.
• singular (required) - A singular name to refer to documents in your collection. For example, if the "display" value is "News Stories" then the "singular" value might be "Story".
• icon - The path to an icon image to use when displaying your collection in the Sitellite Control Panel.
• key_field (required) - The primary key field, or the field containing a unique identifier for documents in your collection.
• key_field_name - A display name for the primary key field.
• title_field - A field that can act as a title for documents in your collection.
• title_field_name - A name to refer to the title field of your collection.
• summary_field - A field that can act as a summary for documents in your collection.
• keywords_field - A field that can act as a keyword list for documents in your collection. You may specify multiple fields by separating them with commas.
• body_field - A field that can act as a body for documents in your collection.
• add - A reference to a Sitellite form to use to override the default add form behaviour. This and the edit field are useful when customizations beyond what are possible via the hint blocks are necessary.
• edit - A reference to a Sitellite form to use to override the default edit form behaviour.
• is_versioned (required) - A yes/no field determining whether the current collection should be version controlled.
• list_weight - A numeric value which gives your collection a higher or lower priority in the Sitellite Control Panel list.
• sitesearch_url - A printf-formatted URL suffix that enables a collection to be indexed by SiteSearch. This URL should contain a single "%s" value which will be replaced with the field specified in "key_field" so that the URL will act as a reference to that particular document. For example, in the "sitellite_news" collection the "sitesearch_url" value is "news-app/story.%s" because a reference to a single news story takes the form "/index/tutorials-story-action/story.[story_id]". Note that the key_field, title_field, summary_field, keywords_field, and body_field values are used by SiteSearch for content indexing.
• sitesearch_access - A minimum access level required to see the collection in the search results at all.
• sitesearch_include_field - A field specifying a yes/no value in your collection which determines whether a document should be indexed by SiteSearch.
• visible - A yes/no value determining whether the collection should be listed in the Sitellite Control Panel.
• scheduler_skip - A yes/no value determining whether the collection should be passed over by the scheduler's "documents" task.

Continuing our collection of favourite tunes, the collection block would be:

[Collection]

name = myapp_tunes
display = Tunes
singular = Tune

key_field = id
key_field_name = ID

title_field = title
title_field_name = Title

body_field = lyrics

is_versioned = yes

[Source]

The source block only requires one field, the "name" field. This tells Sitellite the name of the driver to load. Source drivers are in the inc/app/cms/lib/Versioning/Source folder. So, for example, if you wanted to use the "Database" driver (this is the one you want for most uses), then your source block would look like this:

[Source]

name = Database

The reason there may be additional properties is that they are passed to the source driver itself, which may require additional information. For example, the "Filesystem" driver requires a "path" property, which is the path to the root folder to store files in, relative to the root of your web site.

[Store]

The store block behaves exactly like the source block, except that it loads store drivers instead, from the inc/app/cms/lib/Versioning/Store folder. A store is where the revision history of a document is stored. The most common store drivers are "Database" and "Blank". The database driver stores revisions in the "_sv" database table that we saw above. The blank driver doesn't store revisions at all. The blank driver is used on collections with the "is_versioned" property under the collection block set to "no". An example store block would look like this:

[Store]

name = Database

Page 1: Creating a Rex Collection
Page 2: The Database Schema
Page 3: The Collection Definition File
Page 4: The Collection Definition File (Continued)
Page 5: Accessing Rex Programmatically
Page 6: Supplimentary Rex APIs

All Tutorials