DLCustomField

Handles custom fields.

Summary

DLCustomField	Handles custom fields.
Author	Duc Tri Le <cmsmadesimple---at---email.tiger-inc.com>
License	This class is released under the GNU General Public License.
Member Data
$data	(array) An array containing the structure of the table containing the values of the custom fields.
$options	(array) An array containing all of the required options for each of the custom fields.
$types	(array) An array containing the available types for the options.
Abstract Methods	The user are required to overwrite these methods.
GetCustomFieldTable	Get the name of the table containing the custom field information.
GetDataTable	Get the name of the table containing the data.
Singleton	Retrieve a single instance of this class.
Normal Methods	The user can just use these methods as is or overwrite it if necessary.
AddCustomField	Add a custom field into the database.
GetTypes	Get the available types.
OverwriteDefaultData	Overwrite the default data.
OverwriteDefaultOptions	Overwrite the default options.
OverwriteDefaultTypes	Overwrite the default types.
Final Methods	The use can only use these methods as is.
Factory	Get an instance of a sub class of this class.
GetAllCustomFields	Retrieve an array from database with all of the custom fields.
GetDataValues	Retrieve the values of the custom fields.
InstallTables	Install the necessary tables in the database.
RemoveTables	Removed the installed tables.

Author

Duc Tri Le <cmsmadesimple---at---email.tiger-inc.com>

License

This class is released under the GNU General Public License.

Member Data

$data

private $data

(array) An array containing the structure of the table containing the values of the custom fields.

In most cases, this should not need to be overwritten. However, if it does, overwrite the method OverwriteDefaultData.

Refer to $options for more information on how the structure of this array should look like.

$options

private $options

(array) An array containing all of the required options for each of the custom fields.

In most cases, this should not need to be overwritten. However, if it does, overwrite the method OverwriteDefaultOptions.

Use the following as a guide on how the structure of this variable should look like:

array(
    {The name of the column.} => array(
        auto_increment => {
            (boolean) Whether or not the column should have the auto
            increment property. Defaults to FALSE.
        },
        default => {
            (string) The default value for the column if it is not
            given. Defaults to an empty string.
        },
        default_quotes => {
            (boolean) Whether or not the default value should be
            surrounded by double quotes. Defaults to TRUE.
        }
        index => {
            (boolean) Whether or not the column should be indexed.
            Defaults to FALSE.
        },
        null => {
            (boolean) Whether or not the column can be null.
            Defaults to FALSE.
        },
        primary => {
            (boolean) Whether or not the column should be the
            primary key. Defaults to FALSE.
        },
        type => {
            (string) The type of the column. Default to "VARCHAR".
        },
        unique => {
            (boolean) Whether or not the column's data should be
            unique. Defaults to FALSE.
        },
        value => {
            (string) The value or length for the column. Default to
            an empty string.
        }
    ),
    ...
)

$types

private $types

(array) An array containing the available types for the options.

If you need to overwrite this method, use the method OverwriteDefaultTypes.

Use the following as a guide on how the structure of this variable should look like:

array(
    {The unique name for the type.} => array(
        'type' => {
            (String) The type of data this should holds. It can be
            one of the following: "boolean", "date", "decimal",
            "integer", "string".
        },
        'options' => array(
            {An option used by this type.},
            ...
        )
    ),
    ...
)

Abstract Methods

The user are required to overwrite these methods.

GetCustomFieldTable

abstract protected function GetCustomFieldTable()

Get the name of the table containing the custom field information.

Returns

(String) The name of the table in the database.

GetDataTable

abstract protected function GetDataTable()

Get the name of the table containing the data.

Returns

(String) The name of the table in the database.

Singleton

Retrieve a single instance of this class.

Unfortunately, with PHP < 5.3, there is no way to do this unless the sub class has to overwrite it. The body of the subclass though should just be:

return DLCustomField::Factory(__CLASS__);

Returns

(DLCustomField) A DLCustomField.

Normal Methods

The user can just use these methods as is or overwrite it if necessary.

AddCustomField

public function AddCustomField( $name,
$type,
$required,
$id = NULL,
$options = array() )

Add a custom field into the database.

Parameters

$name	(String) The name for the custom field.
$type	(String) The type for the custom field.
$required	(Boolean) Whether or not this custom field is required.
$id	(mixed) Optional and defaults to NULL. If provided, this will be used as the ID, otherwise, when inserting, the ID is not added to the SQL.
$options	(array) Optional and defaults to an empty array. An array containing all the other options used by this custom field.

The structure of the parameter $options, if given, should look like the following:

array(
    {The name of the option.} => {
        (String) The value for the option.
    }
)

GetTypes

public function GetTypes()

Get the available types.

Returns

(array) An array containing the available types.

OverwriteDefaultData

protected function OverwriteDefaultData()

Overwrite the default data.

Note that the current default data will be merged with the returned array.

Returns

(array) An array containing the default data to overwrite. Refer to $options for more information on the structure of the returned array.

OverwriteDefaultOptions

protected function OverwriteDefaultOptions()

Overwrite the default options.

Note that the current default options will be merged with the returned array.

Returns

(array) An array containing the default options to overwrite. Refer to $options for more information on the structure of the returned array.

OverwriteDefaultTypes

protected function OverwriteDefaultTypes()

Overwrite the default types.

Note that the current default types will be merged with the returned array.

Returns

(array) An array containing the default types to overwrite. Refer to $options for more information on the structure of the returned array.

Final Methods

The use can only use these methods as is.

Factory

public static function Factory( $subclass )

Get an instance of a sub class of this class.

Note that the subclass must have been loaded.

Parameters

$subclass

(String) The name of the subclass to get.

Returns

(mixed) An instance of the subclass or null if the class doesn’t exists.

GetAllCustomFields

final public function GetAllCustomFields( $id = NULL )

Retrieve an array from database with all of the custom fields.

Parameters

$id	(Numeric) Optional and defaults to NULL. If set, the returned result will just be the custom field with the provided ID.

Returns

(array) An array containing the custom fields. If no ID was given, then the result will be an array of the following, otherwise it is just the following array:

array(
    'id' => {
        (String) The ID of the custom field.
    },
    'name' => {
        (String) The name of the custom field.
    },
    'type' => {
        (String) The type of the custom field.
    },
    'required' => {
        (Boolean) Whether or not the custom field is required.
    },
    {Any other option used by the type.} => {
        (String) The value for the option.
    },
    ...
)

GetDataValues

final public function GetDataValues( $where = '',
$options = array() )

Retrieve the values of the custom fields.

Parameters

$where	(mixed) Either a string of the WHERE clause or an array containing all the constraints. If it is an array, refer to the method DLDatabase::BuildWhereClause. Defaults to an empty string.
$options	(array) An array containing data used in this method. Refer to the methods DLDatabase::BuildJoinOnClause and DLDatabase::BuildGroupByClause, DLDatabase::BuildOrderByClause for more information regarding some of the attributes. Defaults to an empty array.

The structure of the $options parameter, if given, should look like the following:

array(
    and_or => {
        (string) The joining string of the first level in the WHERE
        clause. Defaults to "AND".
    },
    and_or_join => {
        (string) The joining string of the first level in the JOIN
        ON clause. Defaults to "AND".
    },
    distinct => {
        (boolean) Whether or not the result should be distinct.
        Defaults to FALSE.
    },
    freeform => {
        (string) Anything else to be attached at the end of the SQL
        right before the semicolon. Defaults to an empty string.
    },
    group_by => {
        (mixed) Either a strinf of the GROUP BY clause or an array
        containing the grouping. Refer to the method
        DLDatabase::BuildGroupByClause. Defaults to an empty string.
    }
    join => {
        (mixed) Either a string of the JOIN ON clause or an array
        containing the joining condition. Refer to the method
        DLDatabase::BuildJoinOnClause. Defaults to an empty string.
    },
    order => {
        (mixed) Either a string of the ORDER BY clause or an array
        containing the sorting preference. Refer to the method
        DLDatabase::BuildOrderByClause. Defaults to an empty string.
    }
)

Returns

(array) An array containing all the rows in the database that match the search criteria. The result array will look something similar to the following:

array(
    array(
        {The name of the column.} => {
            (string) The value of the column.
        },
        ...
    ),
    ...
)

InstallTables

final public function InstallTables()

Install the necessary tables in the database.

RemoveTables

final public function RemoveTables()

Removed the installed tables.