The Content Meta Data system is a feature that will allow third party developers to store arbitrary data regarding a content item, that may not necessarily need it's own storage space, while also being efficient. This is particularly useful to when your application is intended to support multiple content types, as well as avoiding unnecessary alterations on large databases to add a single column and / or avoid creating small mapping tables that you must join on.
To support storing Meta Data, your Content Item Model must implement the \IPS\Content\MetaData interface, and then define meta_data in your column map.
namespace IPS\myapp;
class _MyClass implements \IPS\Content\MetaData
{
public static $databaseColumnMap = array(
/* etc */
'meta_data' => 'item_meta_data',
);
}
Additionally, you must add a BIT(1) column to your content items database table. This column is used to determine if the item has any meta data stored at all. If an item does not have any data, then the software will not attempt to load anything from the core_content_meta table (thus, making it more efficient than automatically attempting to load every time a content item is viewed).
ALTER TABLE myapp_content ADD COLUMN item_meta_data bit(1) NOT NULL DEFAULT b'0';
Once done, your Content Item will inherit the following methods:
/** * Meta data types supported by this content * * @return array|NULL */ public static function supportedMetaDataTypes() /** * Check if this content has meta data * * @return bool * @throws \BadMethodCallException */ public function hasMetaData() /** * Fetch Meta Data * * @return array * @throws \BadMethodCallException */ public function getMeta() /** * Add Meta Data * * @param string The type of data * @param array The data * @return int * @throws \BadMethodCallException */ public function addMeta( $type, $data ) /** * Edit Meta Data * * @param int The Meta Data ID from core_content_meta * @param array The data * @return void * @throws \BadMethodCallException */ public function editMeta( $id, $data ) /** * Delete Meta Data * * @param int The Meta Data ID from core_content_meta * @return void */ public function deleteMeta( $id ) /** * Delete All Meta Data relating to this content item * * @return void */ public function deleteAllMeta()
Important notes regarding specific methods:
- supportedMetaDataTypes() - Your content item model must define this method in your content item model, with a return value similar too return array( 'myappkey_ExtensionKey' ); with each member of the return array being a specific extension, with the first part being the application the extension belongs too, and the second being the extension key, separated by an underscore. This is useful for checking to ensure that a specific content item support that specific type of data. This method returns NULL by default to indicate the content item does not support storing any data.
- hasMetaData() - This method does not check against the core_content_meta table to see if there is data present. Instead, it will check against the meta_data column that you have specified in your items column map, which acts as a simple flag and as the return value of this method, type-casted to a boolean (1 will return TRUE, 0 will return FALSE).
- getMeta() - This method will return all meta data associated with this particular content item in the format of array( 'myappkey_ExtensionKey' => array( X => array( 'data' ) ) ); where "myappkey_ExtensionKey" is the type as defined in supportedMetaDataTypes(), X is the value of meta_id in the core_content_meta table, and then finally the data (which has been json_decode()'d from the database).
- addMeta() - The $type parameter here must be at least one of the array members as defned by the supportedMetaDataTypes() method. The $data parameter must be an array that will be json_encode()'d and stored in the meta_data column of core_content_meta.
- editMeta() - This method is exactly the same as addMeta(), however the first parameter is the value of meta_id in core_content_meta, and the second is the new data that should be stored. When called, the method will compare all members of the $data array with the stored version. If it's value differs, then it will automatically store the new value while retaining any that already exist. As such, it is not necessary to specify every member of the array, if only one has changed.
- deleteMeta() - As with editMeta(), the $id parameter must be the value of meta_id from core_content_meta.
The Extensions
While the extensions are required, to verify what application a specific type of data belongs too, there is no enforced structure / required methods which must be present within the extension. You are free to use the meta data methods from within \IPS\Content\Item directly, within your own content model, or you can use the extension to define "helper" methods for formatting the data (for a real life example of this, you can reference the two extensions located at /applications/core/extensions/core/MetaData/).
Real World Examples
The Content Message and Recommended Replies features both utilize the Content Meta Data feature for storing their data.
Report Document