Wiki : CategoryUtil
Documentation Home :: Categories :: Index :: Recent Changes :: Comments :: Search :: Help :: Login/RegisterUsing Categories in Modules
In order to enable categorization of content items in 3rd party modules you need to do the following:
- Activate categorization in the table definition.
- Register one or more categories for your data tables.
This will activate automatic categorization when using the various DBUtil methods. If you lookup a content item (called Object in DBUtil) you will get an array back with the data:
$item = DBUtil::selectObjectByID('TABLENAME', ...);
// $item = array('field1' => 'xxx',
'field2' => 'yyy',
'__CATEGORIES__' => array(...));
// $item = array('field1' => 'xxx',
'field2' => 'yyy',
'__CATEGORIES__' => array(...));
The CATEGORIES array is something like:
array('PROPERTYNAME1' => array('id' => CATEGORYID1, ...),
'PROPERTYNAME2' => array('id' => CATEGORYID2, ...));
'PROPERTYNAME2' => array('id' => CATEGORYID2, ...));
So you have one entry for each property you have registered for your data table.
The same applies to the DBUtil updater methods that will accept a similar CATEGORIES array.
After this you need to:
- Add category selectors in the user interface.
- Add category filters in the content item lists.
Activate categorization in the table definition
The module's pntables.php should be:
function MODNAME_pntables()
{
// Initialise table array
$pntable = array();
// Full table definition
$pntable['TABLENAME'] = DBUtil::getLimitedTablename('TABLENAME');
$pntable['TABLENAME_column'] = array (...);
// Column definitions (no category stuff here)
$pntable['TABLENAME_column_def'] = array(...);
// Enable categorization services
$pntable['TABLENAME_db_extra_enable_categorization'] = true;
$pntable['stories_primary_key_column'] = 'PRIMARYKEYNAME';
return $pntable;
}
{
// Initialise table array
$pntable = array();
// Full table definition
$pntable['TABLENAME'] = DBUtil::getLimitedTablename('TABLENAME');
$pntable['TABLENAME_column'] = array (...);
// Column definitions (no category stuff here)
$pntable['TABLENAME_column_def'] = array(...);
// Enable categorization services
$pntable['TABLENAME_db_extra_enable_categorization'] = true;
$pntable['stories_primary_key_column'] = 'PRIMARYKEYNAME';
return $pntable;
}
Register one or more categories for your data tables
The module needs to register exactly which set of categories to use. This registration couples a data table, a property and a category node. The property is simply a name you decide - if you want multiple categories for one content item you need one name for each category. The user is allowed to select any sub-category under the category node.
In the module initialization code (pninit.php) we then need a registration of the categories to use:
// This function must be called manually from MODNAME_init()
function _MODNAME_createDefaultCategory($regpath = '/__SYSTEM__/Modules/Global')
{
// load necessary classes
Loader::loadClass('CategoryUtil');
Loader::loadClassFromModule('Categories', 'Category');
Loader::loadClassFromModule('Categories', 'CategoryRegistry');
// get the category path for which we're going to insert our categories
$rootcat = CategoryUtil::getCategoryByPath($regpath);
if ($rootcat) {
// create an entry in the categories registry to the Main property
$registry = new PNCategoryRegistry();
$registry->setDataField('modname', 'MODNAME');
$registry->setDataField('table', 'TABLENAME');
$registry->setDataField('property', 'PROPERTYNAME');
$registry->setDataField('category_id', $rootcat['id']);
$registry->insert();
} else {
return false;
}
// Repeat above for each category you want to register
return true;
}
function _MODNAME_createDefaultCategory($regpath = '/__SYSTEM__/Modules/Global')
{
// load necessary classes
Loader::loadClass('CategoryUtil');
Loader::loadClassFromModule('Categories', 'Category');
Loader::loadClassFromModule('Categories', 'CategoryRegistry');
// get the category path for which we're going to insert our categories
$rootcat = CategoryUtil::getCategoryByPath($regpath);
if ($rootcat) {
// create an entry in the categories registry to the Main property
$registry = new PNCategoryRegistry();
$registry->setDataField('modname', 'MODNAME');
$registry->setDataField('table', 'TABLENAME');
$registry->setDataField('property', 'PROPERTYNAME');
$registry->setDataField('category_id', $rootcat['id']);
$registry->insert();
} else {
return false;
}
// Repeat above for each category you want to register
return true;
}
Add category selectors in the user interface
In the template you can have something like this:
<div class="pn-formrow">
Category
<!--[nocache]-->
<ul>
<!--[foreach from=$catregistry key=property item=category]-->
<!--[array_field_isset assign="selectedValue" array=$__CATEGORIES__ field=$property returnValue=1]-->
<li><!--[selector_category category=$category name="TABLENAME[__CATEGORIES__][$property]" field="id" selectedValue=$selectedValue defaultValue="0"]--></li>
<!--[/foreach]-->
</ul>
<!--[/nocache]-->
</div>For this you need to assign a few values in the PHP code:
$item = DBUtil::selectObjectByID('TABLENAME', ...);
$pnRender->assign($item);
// load the categories system
if (!($class = Loader::loadClass('CategoryRegistryUtil'))) {
pn_exit (pnML('_UNABLETOLOADCLASS', array('s' => 'CategoryRegistryUtil')));
}
$catregistry = CategoryRegistryUtil::getRegisteredModuleCategories ('MODNAME', 'TABLENAME');
$pnRender->assign('catregistry', $catregistry);
$pnRender->assign($item);
// load the categories system
if (!($class = Loader::loadClass('CategoryRegistryUtil'))) {
pn_exit (pnML('_UNABLETOLOADCLASS', array('s' => 'CategoryRegistryUtil')));
}
$catregistry = CategoryRegistryUtil::getRegisteredModuleCategories ('MODNAME', 'TABLENAME');
$pnRender->assign('catregistry', $catregistry);
Add category filters in the content item lists
A category filter is an array where each of your category properties are assigned a value:
You can pass this filter to the DBUtil selector:
$items = DBUtil::selectObjectArray('TABLENAME', ..., $filter);
This will return all items associated with either $id1? or $id2?.
Using pnForm?'s category selector
You can get pnForms category selector to return categories in the CATEGORIES array directly:
<!--[pnformcategoryselector id=PROPERTYNAME category=xxx enableDBUtil=1]-->
In this way you will get this value returned:
Examples
You can look into the News and Pages modules for more example code.
|
