Documentation

Built-in Property Types

Asset

The asset property type is used to store files/assets on the filesystem and have these associated with Speck content types.

Property definition attributes for asset properties

Attribute	Type	Required	Description
extensions	String	No	List of allowed file extensions (minus the dot) for uploaded files. E.g. "doc,pdf".
displayMimeType	String	No	If specified, asset will always be displayed as this mime type, e.g. for downloads set this to "application/octet-stream". If not specified, Speck uses the mimemap in the /speck/config/system/ directory to determine the mime type from the file extension.
contentDisposition	String	No	Value of the type parameter of the content-disposition header used in the asset view/download script. Default "inline". Set to "attachment" to force assets to be downloaded.
secureKeys	String	No	Use this attribute to secure access to an asset. Assets that have been promoted to the live level are normally stored in the publicly accessible assets directory. If you use this attribute, the assets are stored in the secure assets directory and access is determined by the value of this attribute. See section "Securing asset properties" below.
width	Number	No	If asset is a supported image, scale to fit within this width. Use preserveAspect or cropToExact settings to force image to be resized to exactly this width.
height	Number	No	If asset is a supported image, scale to fit within this height. Use preserveAspect or cropToExact settings to force image to be resized to exactly this height.
maxWidth	Number	No	If asset is a supported image and width of image is greater than maxWidth, scale the image to fit within maxWidth.
maxHeight	Number	No	If asset is a supported image and height of image is greater than maxHeight, scale the image to fit within maxHeight.
cropToExact	Boolean	No	If image is to be scaled to fit within a specific width and height, maintain aspect ratio and crop to fit new dimensions. Default false.
preserveAspect	Boolean	No	If image is to be scaled to fit within a specific width and height, and is not to be cropped to fit exactly, scale to fit within new dimensions and maintain aspect ratio. Default true.
jpegCompression	Number	No	Compression quality or resized images (all resized images are saved as JPEGs), with 100 being the highest quality (least compression) and 0 being the lowest quality (most compression). Default 90.

Performance Considerations
Note that if you use either the secureKeys or displayMimeType attributes or set the contentDisposition attribute to 'attachment' when defining an asset property, a ColdFusion script will be used when delivering the asset to the client. Using the ColdFusion script to deliver assets can affect server performance, especially in CF5. You may want to examine the code in /speck/www/properties/asset/asset.cfm to assess the possible impact on your server.
Note RE X-SendFile support
The asset delivery script now includes support for the xsendfile Apache module. If you are using Apache and have this module installed, set xSendFile = yes in your application configuration file and refresh your app.

Notes RE image resizing
The image manipulation code used when CF version is 6 or 7 comes courtesy of Rick Root, check out his ImageCFC component and other open source projects at opensourcecf.com. Image CFC supports PNG, GIF, and JPEG images, though CMYK JPEGs and RGB PNGs are not supported. If the CF version is 8 or later, CF's built-in image functions are used.

Securing asset properties
Asset properties are secured by setting a secure key for an asset. Only users who have the secure key added to their session structure can then access the asset. For example, if the secure key for an asset property is "vip", then Speck checks for the existence of "session.vip" before granting the user access to the asset. If the key doesn't exist, access to the asset is denied. Speck obtains the list of secure keys from the secureKeys property definition attribute. If the value of a list item is prefixed by a dollar sign, e.g. "$propertyName", the name of the key to look for in the users session structure is the value of the property "propertyName" for the content item. Without the dollar sign prefix, e.g. "variableName", the value indicates the name of the key to look for in the users session structure to grant access.

Boolean

The boolean property type stores boolean values as integers (1 or 0) in the database. An integer data type is used for database independence.

Property definition attributes for boolean properties

Attribute	Type	Required	Description
inputType	String	No	Input type to use when rendering form field, "radio" or "checkbox". Default "radio".
defaultValue	Integer	No	Default value when rendering form field. Default 0. If value is 1, radio/checkbox will be checked.

Date

The date property type stores date values (not datetime/timestamp values) as strings in the database. Like the use of integer for the Boolean type, this is done for database independence (not all databases have a date, as opposed to datetime/timestamp, data type). The dates are stored in standard ISO-8601 format, i.e. YYYY-MM-DD, and the column is always indexed (regardless of whether you use the index attribute in cf_spProperty).

Property definition attributes for date properties

Attribute	Type	Required	Description
richEdit	Boolean	No	Show calendar when rendering form field. Default "no".
yearRange	List	No	Allowed year range. For example, a value of "1970,2030" will restrict the range of accepted dates to between 1 Jan 1970 and 31 Dec 2030. Default "".
defaultCurrent	Boolean	No	Use current date as default value? Default "no"

DateTime

Similar to the date property type, except that this property type stores time values along with dates and uses the relevant datetime or timestamp data type in the database. However, you can force the time value to be a constant and only request a date from the user, thereby using a datetime/timestamp database column to store date information.

Property definition attributes for datetime properties

Attribute	Type	Required	Description
richEdit	Boolean	No	Show calendar when rendering form field. Default "no".
yearRange	List	No	Allowed year range. For example, a value of "1970,2030" will restrict the range of accepted dates to between 1 Jan 1970 and 31 Dec 2030. Default "".
time	String	No	Use this attribute to force a time value (HH:MM 24 hr clock format), and only request a date from the user. This effectively allows you to use a datetime/timestamp database column to store date information by forcing time values to be constant (e.g. 00:00).
defaultCurrent	Boolean	No	Use current datetime as default value when rendering form field? Default "no"
defaultTimeValue	String	No	Use to force a pre-defined time (HH:MM 24 hr clock format) when rendering form field with a default value, i.e. rather than show curent date and time, show current date and this time. Requires defaultCurrent to be true.

HTML

Property definition attributes for HTML properties

Attribute	Type	Required	Description
richEdit	Boolean	No	Use rich text editor when rendering form field. Default "no". If "yes", Speck will use FCKEditor when rendering the form field. The default configuration for FCKEditor is stored in the file speckconfig.js in the fckeditor directory. The configuration can be overridden using an application configuration file and/or a number of optional attributes for the Html property (only one of which, fckToolbarSet, should be needed in almost all cases).
fckToolbarSet	Boolean	No	Toolbar to use with this instance of FCKeditor if richEdit=yes. Default "Default", other options are Basic and Minimal.
allowFont	Boolean	No	Allow font tags in saved HTML. Default "no".
allowStyle	Boolean	No	Allow style attributes in HTML tags. Default "yes".
allowSpan	Boolean	No	Allow span tags in saved HTML. Default "yes".
allowDiv	Boolean	No	Allow div tags in saved HTML. Default "yes".
allowClass	Boolean	No	Allow class attributes, default "yes".
allowTarget	Boolean	No	Allow target attributes in anchor tags. Default "yes". If no, target attributes are stripped from html and target tab is hidden from link dialig in FCKeditor.
forceRelativeLinks	Boolean	No	Strip protocol and host name from href attributes where the host name is the current host. This allows the application host name to be changed without upsetting the apple tart. Default "yes".
forceTarget	Boolean	No	For target attributes for hrefs, such that local links have no target and remote links have a target set to "_blank". If yes, this also hides the target tab from the link dialog window in FCKeditor. Default "yes.
safeText	Boolean	No	Remove potentially nasty HTML from text (SCRIPT,FORM, OBJECT,EMBED,IFRAME etc.). Default "yes".
tidyWordHTML	Boolean	No	Remove useless HTML tags and attributes added by MS Word. When using a rich text editor based on Microsoft's DHTML Edit control (like the SiteObjects editor), unnecessary rubbish added to the HTML source by Word is preserved when pasting into the editor. Default "yes".
tidy	Boolean	No	Attempt to use JTidy to clean HTML / convert to XHTML before saving. Default "yes". Speck includes a custom tag for cleaning HTML using JTidy. The default configuration can be overridden by adding a jtidy.properties configuration file to the application configuration directory.
forceParagraphs	Boolean	No	Force HTML to be wrapped in paragraph tags. Default "no". Useful when creating accessible sites. Note that the code for this is pretty ruthless and might mangle complicated html with nested block level elements. You might want to check out the forceParagraphs function in the spFunctions file before using this.
escapeHTML	Boolean	No	Use HTML entities for non-Latin1 characters. Default "yes". Characters with codes from 128 to 159 inclusive are assumed to be part of the Windows 1252 character set.
convertLatin1	Boolean	No	Use to override the default behaviour when escaping html such that latin1 characters not in the ascii character set will also be escaped. Default "no". Note that this has no effect if escapeHTML is false.

Customising the FCKeditor configuration for Html properties.
The default FCKeditor configuration be overridden per application by creating an fckeditor.cfg file in the config directory inside the application install root directory. This file should have a settings section and name value pairs for each FCKeditor setting that you want to override. For more info on the available settings, see the FCKEditor documentation. Note that the fckeditor.cfg file can only deal with simple values. Settings which require complex values, creating a new Toolbarset for example, must be defined using JavaScript. If you need to do this, create your JavaScript config file and then tell Speck to use it by either calling it fckconfig.js and dropping it into a javascripts directory off your web root or by specifying the CustomConfigurationsPath setting.The default configuration can also be overridden per instance of the HTML property using 6 optional cf_spProperty attributes - fckToolbarSet, fckWidth, fckHeight, fckCustomConfigurationsPath, fckEditorAreaCSS and fckFontFormats. The FCKeditor documentation explains how these options can be used to customise an FCKeditor instance. Speck also looks for an fckeditor.css file in a stylesheets directory off the application web root and, if it exists, defaults the EditorAreaCSS setting to the path to this stylesheet.

Number

Property definition attributes for number properties

Attribute	Type	Required	Description
decimalPlaces	Number	No	Number of decimal places allowed. Default "0", i.e. only allow integers.
minValue	Number	No	Minimum allowed value. Default "", i.e. no minimum value.
maxValue	Number	No	Maximum allowed value. Default "", i.e. no maximum value.
defaultValue	Number	No	Default value to use when rendering form field.

Picker

The picker property type allows you to create a one-to-many relationship between content types. The value of a picker property in a content item is a list of related content item Ids. You can use this value to retrieve related content items using cf_spContent or cf_spContentGet. The renderFormField method of the picker property allows you to search for and pick related content items. Which fields of the related content type are available for searching is determined by use of the finder cf_spProperty attribute in the related content type.

Property definition attributes for picker properties

Attribute	Type	Required	Description
contentType	String	Yes	Content type from which to pick items.
maxSelect	Integer	No	Maximum number of content items that can be picked. Note that Speck creates a column with max length of 4000 characters to store the list of picked items, which is enough to store a list of 111 UUIDs. If you need to store more, you'll have to manually modify the column definition.
dependent	Boolean	No	If yes, the picked items are considered dependent on the containing content item. The option to select/pick an existing content item will not be available, items can only be added and deleted and if the containing content item is deleted, all "picked" content items are also deleted. Default "no".
prepend	Boolean	No	BY default, picked items are appended to the end of the list. You can use this setting to prepend to the list instead. The order in which items get added to the list only matters when picked items are being manually sorted and being output in their manually sorted order.
displayMethod	String	No	Method used to display picked content items when rendering the edit form. Default "picker". Note: the default content type has a picker method which dumps basic info about content items. We highly recommend you create your own picker methods though.
showSort	Boolean	No	Allow list to be sorted manually. This is very useful if you wish to display related content items in an order that cannot be achieved using the order attribute of cf_spContent and cf_spContentGet. The result of using this option is that the list of Ids stored in the database are sorted manually. You can obtain the listed items from the database in the order in which they appear in the list by calling spContentGet and providing the list of ids as the value of the id attribute and setting the orderByIds attribute to true (this is a hack, but it's quite a neat one).
showAdd	Boolean	No	Show a link to add content items of type <contentType> when rendering the form field. Deault "yes".
showEdit	Boolean	No	Show a link to edit each content item when rendering the form field. Default "yes".

SimplePicker

This is a version of the picker property type with a simple renderFormField method, which does not allow you to search for related for or add items. Instead, all items of the content type you wish to create a relationship with initially appear in a multiple select form element and can be moved to a "selected items" multiple select box. This property can be used as a replacement for the picker property when you know there will only ever be a small number of items to pick from.

Property definition attributes for simplepicker properties

Attribute	Type	Required	Description
contentType	String	Yes	Content type from which to pick items.
maxSelect	Integer	No	Maximum number of content items that can be picked. Note that Speck creates a column with max length of 2000 characters to store the list of picked items, which is enough to store a list of 55 UUIDs. If you need to store more, you'll have to manually modify the column definition.
displayProperty	String	No	Property of the content type from which to pull values to populate the select form element.

Text

Property definition attributes for text properties

Attribute	Type	Required	Description
password	Boolean	No	Use password input type for form field. Default "no".
confirm	Boolean	No	Show a confirm password field if password attribute is "yes" and check that property value matches confirmation value. Default "no".
editable	Boolean	No	Allow property value to be edited once added. Default "yes", if "no", form element for this property is readonly when editing a content item.
match	String	No	Regular expression pattern to search for in value. Allows custom validation on text properties. Default empty string, i.e. no custom validation.
email	Boolean	No	Check that value is a validly formed email addresses. The validation does not check that the address exists, just that it's correctly formed and it assumes the email address will be in the standard user@host form. Default "no".
httpurl	Boolean	No	Check that value is a validly formed HTTP or HTTPS URL. The validation rule is quite lax to allow for intranet URLs. Default "no".
convertWin1252	Boolean	No	Replace common windows 1252 characters with codes between 128 and 159 inclusive with their nearest equivalent ASCII character or sequence of characters. Default "yes".
defaultValue	String	No	Default value to use when rendering form field.

ValuePicker

A property that allows one or more values to be picked from a list