This is the documentation for concrete5 version 5.6 and earlier. View Current Documentation

Attribute Types determine the nature of the data that a particular Attribute Key object stores. They determine its schema, how it is searched and stored. Simple Attribute Types may store just a bit of text or a number. Complex Attribute Types can store an entire address, multiple selections from a list, and more.

Built-in Attribute Types

  • boolean
  • default
  • text
  • rating
  • date_time
  • address
  • number
  • image_file
  • select
  • textarea

These attribute types may all be found in concrete/models/attribute/types/.

Directory Setup

An attribute type's directory can contain the following items.

Database Definition: db.xml

This is a file named db.xml, in the ADODB AXMLS format (link to http://phplens.com/lens/adodb/docs-datadict.htm). This file describes the schema of the attribute type in a way that can be easily read and understood. The schema can also be altered later and refreshed through the dashboard.

Here is the schema for the Date/Time attribute.

<<xml version="1.0">    <table name="atDateTimeSettings">     <field name="akID" type="I" size="10">       <KEY/>       <UNSIGNED />     </field>     <field name="akDateDisplayMode" type="C" size="255" />   </table>   <table name="atDateTime">     <field name="avID" type="I" size="10">       <KEY/>       <UNSIGNED />     </field>     <field name="value" type="T">       <DEFAULT value="0000-00-00 00:00:00"/>     </field>   </table>

Multiple tables can contained within this file. The only requirement for the table is that the core attribute type table must contain a column named avID, which is an unsigned integer.

Icon: icon.png

An attribute type's icon is displayed when attributes of that type are listed in the dashboard. This is a 16x16 PNG named "icon.png".

Controller: controller.php

This file extends the AttributeTypeController object. You can learn more about this file in the _MVC Approach_ section below. Multiple classes may be present in this file.

Optional: form.php

This file is displayed when the attribute type is being interacted with.

Optional: type_form.php

This file is displayed when attributes of this type are added to the system. This is only ever displayed in the dashboard. This file will be necessary if the type of attribute contains special configurable options.

Additional JavaScript/CSS

If form.css or form.js exists, it will be autoloaded when form.php is rendered. If type_form.js or type_form.css exists, it will be autoloaded when type_form.php is rendered. Any additional JavaScript or CSS can be added to the display by using $this->addHeaderItem() from within the controller.php methods.

MVC Approach - Methods of an Attribute Type Controller

An Attribute Type's controller is where all retrieval, saving, searching and other manipulation of a particular type's data occurs. Many attribute types will only need this file, as it can fulfill many of the functions of optional components above.

The following items are available within controller.php

$searchIndexFieldDefinition

This is a string or array which determines the schema of this type of attribute, when its data is added to an Attribute Key's search index table. If this is a string, the attribute key handle will be used as the column name in the table (with "ak_" as its prefix.) If it is an array, multiple columns will be created in the format ak_handle_KEY, where KEY is the key of the column in the associative array. For example, take a look at the $searchIndexFieldDefinition variable within the Address Attribute Type Controller:

	protected $searchIndexFieldDefinition = array( 		'address1' => 'C 255 NULL', 		'address2' => 'C 255 NULL', 		'city' => 'C 255 NULL', 		'state_province' => 'C 255 NULL', 		'country' => 'C 255 NULL', 		'postal_code' => 'C 255 NULL' 	);

If an address with the handle "billing_address" is added to the system, when the search index is built, the search index field for that Attribute Category will contain the columns

	ak_billing_address_address1 	ak_billing_address_address2 	ak_billing_address_city  	etc...

getValue()

This method must query the Attribute Type table for the value of the current $this->getAttributeValueID(), and return it in unformatted.

form()

This method is run when the attribute type's form is displayed. This method runs before the form.php file is rendered. If form.php does not exist, form elements may be printed out from within the form() method itself.

type_form()

This method is run when the attribute type's settings form is displayed. This method runs before the type_form.php file is rendered. If type_form.php does not exist, form elements may be printed out from within the type_form() method itself. This method allows attribute type developers to specify additional settings for attribute types. These settings will be displayed whenever attributes of this type are added or edited.

searchForm($list)

This method is run when a DatabaseItemList is queried for an attribute of this type. This method will then run the proper filtering logic based on the current attribute type.

getDisplayValue()

This is a method that should get the current value, and then display it in a nice way. This might be formatting a date/time to a more easily human-readable string, or displaying a rating as nice HTML instead of a simple number.

getDisplaySanitizedValue()

This is a method that should get the current value, and if its possible it has some potential harmful characters (ie, it's HTML with JavaScript) it should sanitize this value, using TextHelper::entities() or something similar.

search()

This method is run when a search form for this attribute type is rendered. This method runs before the search.php file is rendered. If search.php does not exist, form elements may be printed out from within the search() method itself.

saveValue($value)

This method is automatically run when calling $object->setAttribute(). It should save the value in the Attribute Type's table, and bind it to the avID of $this->getAttributeValueID().

saveForm($data)

This method is run when the form rendered by either form() or form.php is submitted. $data is an associative array of POSTed form values. Only the relevant values are within this array.

duplicateKey($newAttributeKey)

This method is automatically run when an attribute key is duplicated. It should take care of duplicating data.

deleteKey()

This is run when an attribute key is deleted, allowing the type to clean up after itself. An example:

	$db = Loader::db(); 	$arr = $this->attributeKey->getAttributeValueIDList();	foreach($arr as $id) { 		$db->Execute('delete from atDefault where avID = ?', array($id)); 	}

validateForm($data)

This is run when a developer or concrete5 has decided a particular attribute needs to be validated before it can proceed. This function should return false if the $data is incomplete, or true if it validates.

deleteValue()

This method is run when it is time to remove the data from the Attribute Types table which matches $this->getAttributeValueID().

Creating Your own Attribute Types

Creating your own attribute type is as simple as duplicating one of the existing attributes, moving it into your local directory, rewiring the controller and schema to suit your purpose, and installing the new type through the dashboard. You can learn how to create your own custom attribute in this how to.

Loading Conversation