Custom fields let you add information to your posts or pages beyond the standard title, content, categories, etc. The consists of a label, a key and the value. The label is used to show a small description of the field while editing a post or page. The key is an unique string that identifies the field. This key is commonly used by plugins to determine if a custom field is available. The value is a string with the contents of the custom field.
Custom fields are not visible unless the skin or a plugin explicitly exposes them. Skins can show custom fields by using the <PostProperty> and <PageProperty> tags, with attribute customField. To verify the existance of a custom field before attempting to show it, you can use the attribute ifHasCustomField or ifNotHasCustomField.
Example:If the user adds a custom field with key=thumbnail, you can show the value of this field by adding this tag to your skin:
<mango:PostProperty ifHasCustomField="thumbnail" customField="thumbnail" />
If you want to show a portion of html when the post has a custom field, you would write:
<mango:PostProperty ifHasCustomField="thumbnail">
... html .... <mango:PostProperty customField="thumbnail"/>
</mango:PostProperty>
Plugins can add custom fields any time they have access to a post or page (ie: when saving a post, when showing a post in the admin, etc...).
A plugin can also add a custom field by default when adding or editing a post, so that the user doesn't have to know the key the plugin is expecting. For example, if a skin can show a thumbnail for every post, you may want to create a plugin that helps the user adding that thumbnail while adding a post. To do that, your plugin will use the administration event "beforeAdminPostFormDisplay" to pre-populate the new post with a custom field with label="Post Thumbnail", key="thumbnail" and empty value, so that the post form will already show this custom field ready to be entered. To add the custom field, the plugin will use the function setCustomField() of the entry object as follows:
//code in processEvent function of your plugin:
<cfif arguments.event.name EQ "beforeAdminPostFormDisplay">
<cfset event.item.setCustomField('thumbnail',"Post Thumbnail", '')>
</cfif>