Public Functions & Methods - lokothodida/DM_Matrix GitHub Wiki
Below is a list of the available front-end functions for you to use from TheMatrix and TheMatrixExtended classes.
Tables
TheMatrix::createTable($table, $fields, $maxrecords, $id)
This function allows you to build the main structure that will hold your data: the table. The table is made up of several important components:
- The 'name' (identifies the table in the overall schema by The Matrix and is called upon for queries (so keep the name simple and avoid special characters)
- The 'maxrecords': maximum number of records that the table can hold before stopping new record creation (set to 0 to make it unlimited)
- The 'id': the unique identifier given to each newly created record - this starts off on 0 but increments with each new record. This setting is here primarily for restoring backed up tables to their original state, in turn fixing the id counter to what it was before.
- The fields: the various data types that your records will be able to take (e.g. a title may be 'text', a date may be 'datetimelocal', an integer may be 'int', etc...) This parameter must be an array. Said array will be of the following structure in order to successfully build all of your fields in the desired order:
$fields = array(
// each field requires an array of the following structure)
array(
'name' => 'your-field-name', // name of your field (MANDATORY - avoid spaces or special characters)
'type' => 'yourfieldtype', // type of field (MANDATORY - choose from the available options (visible in the dropdown))
'desc' => 'Your field description', // description for field -- becomes placeholder for field content (OPTIONAL)
'label' => 'Your field label', // label that appears in forms (OPTIONAL)
'default' => 'Default content', // default content that will fill the field when a record is created (OPTIONAL)
'cacheindex' => '1', // dictates whether the field's value will be cached when performing the query (OPTIONAL. Takes value 0 for no and 1 for yes)
'table' => '_routes', // for type 'dropdown' -> the table that the dropdown will pull record values from (MANDATORY iff dropdown is the field type)
'row' => 'id', // for type 'dropdown' -> the table FIELD that the dropdown will pull record values from (MANDATORY iff dropdown is the field type)
'options' => '', // for type 'dropdowncustom' -> the values that can be selected from the dropdown menu (separate each option with a line break, e.g. "\n"). (MANDATORY iff 'dropdowncustom' is the field type)
'path' => '', // for type 'imageupload' -> relative path from root of GS installation to where images will be uploaded (MANDATORY iff 'imageupload' is the field type)
'size' => 50, // size of the field in The Matrix table view (OPTIONAL)
'visibility' => 1, // visibility of the field in The Matrix table view (1 = visible, 0 = hidden; OPTIONAL)
'class' => '' // class given to field when a form is built using the buildForm() method (primarily for generating admin panel forms; OPTIONAL)
),
// more fields....
);
Example
$var->createTable('foo', $fields, 0, 0);
TheMatrix::renameTable($table, $name)
Allows you to rename a table. Provide the original name and then the new name. Returns true/false at the end. Will return false if either the table doesn't exist or the name you are giving is already taken.
Example
$var->renameTable('foo', 'bar');
TheMatrix::copyTable($table, $newTable)
Provides a duplicate of the initial table, suffixed with '_copy' (if $newTable is left blank). You can give it any name that you wish.
Example
$var->copyTable('foo'); // creates 'foo_copy'
$var->copyTable('foo', 'bar'); // creates 'bar'
TheMatrix::emptyTable($table)
Lets you empty the table of its current data without also getting rid of the table. Mainly used if you want to start afresh. Note: this does not reset the 'id' counter back to 0, in case you need to restore the table back to its original state and end up overwriting new data.
$var->emptyTable('foo'); // 'foo' will have no more records.
TheMatrix::deleteTable($table)
Empties the table then deletes its contents. Before doing so though, a backup of the current schema is automatically created, so if you accidentally invoke this function, there will always be a backup ready for you to roll back to.
Example
$var->deleteTable('foo');
TheMatrix::getBackups($table, $directory, $file)
Returns an array of the available backups from the directory specified (default is 'data/other/matrix') and with the file name provided (a '' can be used as a wildcard for searching for file names; the default is just 'tablename_').
$var->getBackups('foo'); // returns all backups in 'data/other/matrix' for foo with the prefix 'foo_'
$var->getBackups('foo', 'data/foo/backups'); // returns all backups in 'data/foo/backups' with the prefix 'foo_'
$var->getBackups('foo', 'data/foo/backups', '*'); // returns all backups in 'data/foo/backups' (regardless of prefix)
The array returned is sorted by the modification date of the backup and contains the timestamp of the backup's creation, the name of the file and the direct url link to the backup file.
Example
array (size=3)
0 =>
array (size=3)
'date' => string 'Tue, 18 Jun 2013 14:23:09 +0000' (length=31)
'link' => string 'http://yourdomain.com/data/foo/backups/foo_1371565389.zip' (length=64)
'file' => string 'foo2_1371565389.zip' (length=19)
1 =>
array (size=3)
'date' => string 'Tue, 18 Jun 2013 14:21:59 +0000' (length=31)
'link' => string 'http://yourdomain.com/data/foo/backups/foo_1371565319.zip' (length=64)
'file' => string 'foo2_1371565319.zip' (length=19)
2 =>
array (size=3)
'date' => string 'Tue, 18 Jun 2013 14:16:48 +0000' (length=31)
'link' => string 'http://yourdomain.com/data/foo/backups/foo_1371565008.zip' (length=64)
'file' => string 'foo2_1371565008.zip' (length=19)
TheMatrix::backupTable($table, $directory, $file)
Backs up the schema of the selected table and dumps its records and schema into a zip file. $directory sets where the zip file will end up (default is 'false', which puts it in the 'data/other/matrix' directory) and $file dictates the file name (default is 'false', which sets it to 'tablename_unixtimestamp'). The schema in the zip is given the name 'tablename_schema.xml'.
Example
$var->backupTable('foo'); // @ Tue, 18 Jun 2013 13:44:13 GMT, 'foo_1371563053.zip' would be created and sent to 'data/other/matrix'
$var->backupTable('foo', 'data/foo/backups'); // @ Tue, 18 Jun 2013 13:44:13 GMT, 'foo_1371563053.zip' would be created and sent to 'data/foo/backups'
$var->backupTable('foo', 'data/foo/backups', 'foo1'); // 'foo1.zip' would be created and sent to 'data/foo/backups'