The Collection Definition File (Continued)

Browse Columns

Browse columns are denoted by blocks whose name begins with a "browse:" followed by the name of a field in the collection. Browse columns determine which fields to display as columns in the Sitellite Control Panel while browsing your collection.

Browse column blocks may contain the following properties:

• header (required) - The name to display in the column header.
• width - The width of the column.
• align - The alignment of the text in the column.
• length - A character limit for text in the column. Field values going over this limit will automatically be cropped and a "..." will be added to the end.
• filter - A function name to filter the text in the column with before displaying it. This function must accept a single scalar value and return a single scalar value.
• filter_import - A package to import which contains the function specified in the "filter" property.
• virtual - The name of a function used to create a "virtual" value in this column. Virtual columns are columns that don't exist in the collection, but are displayed to provide information about the document (ie. the click-through ratio of a banner ad in SiteBanner). This function must accept an object containing the current document and return a scalar value. Virtual functions may also be imported from packages with the "filter_import" property.

The following will be the browse columns for our continued example:

[browse:title]

header = Title

[browse:artist]

header = Artist

[browse:style]

header = Style
filter = myapp_filter_style
filter_import = myapp.Filters

[browse:year]

header = Year

Note that before the filter we've specified will work we'll have to create it. Save the following PHP code to the file inc/app/myapp/lib/Filters.php to create the appropriate filter:

<?php

function myapp_filter_style ($id) {
	return db_shift ('select name from myapp_styles where id = ?', $id);
}

?>

Search Facets

Search facets are denoted by blocks whose name begins with a "facet:" followed by the name of a field in the collection. Search facets are the options that appear in the "Search Parameters" box above the collection data in the Sitellite Control Panel, allowing users to perform complex searches in just a few clicks.

Search facet blocks may contain the following properties:

• display (required) - The text to display next to the facet.
• type (required) - The type of facet. The list of available facets corresponds to the classes defined in inc/app/cms/lib/Versioning/Facets.php.
• fields - A comma-separated list of fields to search, used by "text" facets.
• values - PHP code that returns an array of values to display as options, used by "select" facets.
• fuzzy - A yes/no value determining whether a "select" facet should perform an exact match or fuzzy match search.

The following will be the search facets we'll use:

[facet:title]

display = Text
type = text
fields = "id, title, artist, album, lyrics"

[facet:style]

display = Style
type = select
values = "db_pairs ('select * from myapp_styles')"

[facet:sitellite_status]

display = Status
type = select
values = "session_get_statuses ()"

[facet:sitellite_access]

display = Access Level
type = select
values = "session_get_access_levels ()"

Form Hints

Form hints are denoted by blocks whose name begins with a "hint:" followed by the name of a field in the collection. Form hints are used in the default add and edit forms to generate customized forms for data entry. Form hints are just like ordinary MailForm widget blocks in terms of their properties. For more information on MailForm widget blocks, please refer to the article "MailForm: The Sitellite Form API".

The form hints we'll use for our example are a little longer than the other parts, as we'll want to customize most of the fields for our data entry forms. I've broken it up into sections so that I could add comments throughout.

The first block is rather straight-forward. Note that there's no need to specify the type value in some cases, since Sitellite does try to determine an occassionally intelligent default.

[hint:title]

extra = "size='30'"

[hint:artist]

extra = "size='30'"

[hint:album]

extra = "size='30'"

The next field uses the "selector" widget, which is the way in which we'll hook our myapp_tunes and myapp_styles tables together.

[hint:style]

type = selector
table = myapp_styles
key = id
title = name

Next, we'll use an eval statement to create a select box of the past 100 years (apparently 3155760000 is roughtly 100 years in seconds).

[hint:year]

type = select
setValues = "eval: assocify (range (date ('Y'), date ('Y', time () - 3155760000)))"

Again, we don't need the type property for the lyrics, as Sitellite will recognize it as a textarea by default.

[hint:lyrics]

rows = 10
cols = 60

The remainder of the hint blocks below are standard to the Sitellite-specific fields, so you can simply copy and paste them from this article as you create new collections later on.

[hint:sitellite_status]

type = status
alt = Status
setValue = draft

[hint:sitellite_access]

type = access
alt = Access Level
setValue = public

[hint:sitellite_startdate]

type = calendar
alt = "Publish On (If Status is `Queued`)"
nullable = yes
showsTime = yes
format = "%Y-%m-%d %H:%M:%S"
displayFormat = "%a, %e %b, %Y - %l:%M%P"

[hint:sitellite_expirydate]

type = calendar
alt = "Archive On (If Status is `Approved`)"
nullable = yes
showsTime = yes
format = "%Y-%m-%d %H:%M:%S"
displayFormat = "%a, %e %b, %Y - %l:%M%P"

[hint:sitellite_owner]

type = owner
alt = Created By

[hint:sitellite_team]

type = team
alt = Owned by Team

New in Sitellite 4.2.6: Custom Browse Links

A new feature of collections added in Sitellite 4.2.6 is the ability to specify custom links that will appear next to the "Add Item" link on the collection browse screen.  This is done with blocks that look like the following:

[link:importer]

text = File Importer
url = "/index/cms-filesystem-importer-action"
requires = rw

Each link is its own section block in the collection definition file.  This allows for more flexibility in the number and type of properties it can have.  The two required properties are the link "text" and the link "url" or address.  The URL can be specified as a complete link beginning with "http://", a relative path, or an absolute path beginning with "/index/" in which case a call to site_prefix() will be prepended to the URL automatically.

A third optional property allows you to specify the privilege level required for users to be shown the link.  This is compared against their access rights to the collection itself as a resource, so that you can have some users see read-only links, and others with read and write access can be shown additional links, such as the one in the example above.

If you've created your database tables and installed the above collection definition file, you should find your new Tunes collection in the Sitellite Control Panel under the Content pane. Try it out, have some fun with it.

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