Kenedo Properties

With properties you define the data that a KenedoModel holds. In the KenedoModel’s method getPropertyDefinitions() you return an array with settings for each property that the model shall have.

See the Kenedo Model ‘Adminexamples’ in the model directory as example.

Note: Upgrade to CB 3.3.3 (Wordpress/Joomla) or CB 3.3.12 (Magento 2) to make use of the properties. Naming of KenedoProperty settings have changed (old names are upward-compatible) and the documentation uses the new names only.

{AppDir}/models/adminexamples.php

<?php
defined('CB_VALID_ENTRY') or die();

class ConfigboxModelAdminexamples extends KenedoModel {

	function getTableName() {
		return '#__configbox_examples';
	}

	function getTableKey() {
		return 'id';
	}

	function getPropertyDefinitions() {
		
		$propDefs = array();

		$propDefs['id'] = array(
			'name'=>'id',
			'type'=>'id',
			'default'=>0,
			'label'=>KText::_('ID'),
			'canSortBy'=>true,
			'positionList'=>100,
			'positionForm'=>1000,
		);
		
		$propDefs['title'] = array(
			'name'=>'title',
			'type'=>'translatable',
			'label'=>KText::_('Title'),
			'stringTable'=>'#__configbox_strings',
			'langType'=>120,
			'required'=>1,
			'canSortBy'=>true,
			'makeEditLink'=>true,
			'component'=>'com_configbox',
			'controller'=>'adminexamples',
			'positionList'=>300,
			'positionForm'=>1100,
		);
		
		....
		
		return $propDefs;
	}
	
}

In the the array of arrays returned by getPropertyDefinitions(), all data of the model gets defined and you choose various behavior in the backend’s CRUD operations and UI.

Property Types

There are various types of properties like ‘string’, ‘translatable’, ‘image’ and others. Here you will see the property settings common to all types and then the types with their specific settings.

Common property settings

name

Required: yes
Valid values: string

The name setting defines the column name in the DB table behind the model and that name will also be used as object variable name in the getRecord() and getRecords() return object.

type

Required: yes
Valid values: string - Names of KenedoProperty Types (image, id, join, date etc)

Defines of which type the property is. See below about each property type.

Each property has a PHP class extending KenedoProperty (e.g. property type ‘translatable’ is backed by the class KenedoPropertyTranslatable. The classes are in the directory {AppDir}/external/kenedo/properties/ and in {customizationDir}/properties/ you can store your own types.

label

Required: yes
Valid values: string

With ‘label’ you choose the label in the edit form view of the model. If you run a multi-language backend, then use KText::_() is for translating. See Custom Wording and Translations for details.

required

Required: no
Valid values: boolean or 0, 1

Choose if the property requires a value when the admin saves a record in the backend edit form.

positionForm

Required: yes
Valid values: numbers

With this setting you control in which order the properties display in edit forms.

positionList

Required: no
Valid values: numbers or omit
In CB 3.3.2 (Magento 2 CB 3.3.10) and lower, this setting is named ‘listing’

With this setting you control if the property should be displayed in the backend list view and in which order.

canSortBy

Required: no
Valid values: boolean or omit
In CB 3.3.2 (Magento 2 CB 3.3.10) and lower, this setting is named ‘order’

This setting regards the backend list view sorting - use ‘true’ to allow admins to sort the table by this property’s values.

addSearchBox

Required: no
Valid values: boolean or omit
In CB 3.3.2 (Magento 2 CB 3.3.10) and lower, this setting is named ‘search’

Use ‘true’ to show a search box in backend list views. Possible with certain property types (e.g. translatable and string).

addDropdownFilter

Required: no
Valid values: boolean or omit
In CB 3.3.2 (Magento 2 CB 3.3.10) and lower, this setting is named ‘filter’

Use ‘true’ to show a dropdown for filtering by possible values. Works with certain property types (e.g. join, boolean, published).

makeEditLink

Required: no
Valid values: boolean or omit
In CB 3.3.2 (Magento 2 CB 3.3.10) and lower, this setting is named ‘listinglink’

With this setting you choose which property will show as edit link in backend list views.

Mind that the setting ‘positionList’ needs to be set.

When you use this setting, two more settings need to be made:

component: always ‘com_configbox'
controller: the controller name in your MVC set.

Example

$propDefs['title'] = array(
	..
	'positionList' => 20,
	'makeEditLink' => true,
	'component' => 'com_configbox',
	'controller' => 'adminoptions',
	..
);

The values of the property will appear as edit links in the list:

See MVC Maker on creating controller/model/views for the backend.

appliesWhen

Required: no
Valid values: array with instructions

With this settings you control visibility of the property in the edit form and make the setting ‘required’ conditional. For example you can make a property display only if the admin made a specific choice in another property.

Example

$propDefs['show_title'] = array(
  'name'=>'show_title',
  'type'=>'radio'
  'choices'=>array('0'=>'yes', '1'=>'no'),
  ..
);

$propDefs['title'] = array(
	..
	'appliesWhen' => array(
		'show_title'=>'1'
	),
	..
);

appliesWhen takes key/value pairs (so called conditions), with keys being names of other properties and values being the should values. In the example above, the ‘title’ property will only display if ‘show_title’ was set to ‘yes'.

Multiple conditions: There can be multiple conditions, then all conditions need to apply.

$propDefs['title'] = array(
	..
	'appliesWhen' => array(
		'show_title'=>'1',
		'another_property'=>'3'
	),
	..
);

Multiple should-values: If a range of selections should make your property apply, use an array of should values

$propDefs['show_title'] = array(
  'name'=>'show_title',
  'type'=>'radio'
  'choices'=>array('0'=>'yes', '1'=>'no', '2'=>'maybe'),
  ..
);

$propDefs['title'] = array(
	..
	'appliesWhen' => array(
		'another_property'=>array('1', '2')
	),
	..
);

Negated should-values: Prepend a ‘!' to the should-value to negate the value. The example below reads 'show unless “another_property” is set to “1”'.

$propDefs['title'] = array(
	..
	'appliesWhen' => array(
		'another_property'=>array('!1')
	),
	..
);

storeExternally

Required: no
Valid values: boolean

This is setting is useful if you extend the properties of a built-in model. It instructs the model to store the property’s values in a specific table (called an extension table). This enables you to keep the built-in DB tables unaltered and have your customised properties stored separately.

Using this setting requires you to define the settings foreignTableName, foreignTableAlias and foreignTableKey. And you need to create an extension DB table (see infos in the following settings).

Example:

$propDefs['show_heading'] = array(
   'name'=>'show_heading',
   ...
   'storeExternally'=> true,
   'foreignTableName'=>'#__configbox_external_product_appends',
   'foreignTableAlias'=>'product_appends',
   'foreignTableKey'=>'product_id',
   ...
);

foreignTableName

Required: if you use setting storeExternally
Valid values: string (DB table name using table prefix), e.g. #__configbox_external_modelname_appends

Define the name of the extension table to use. The table must contain a column named after the property and a primary key column named after the setting foreignTableKey. Best use the customization update scripts to create the table.

Example table:

Taking the property settings from above, your extension table.

Column name	Type	Note

Column name	Type	Note
product_id	INT UNSIGNED PRIMARY KEY	Make the type correspond to the base table’s primary key
show_heading	VARCHAR(1)	Up to the Property’s recommended column type

foreignTableAlias

Required: if you use setting storeExternally
Valid values: string - any valid MySQL table alias name

Pick any alias for the JOIN that happens internally. Ideally, use the name of the model you extend and append ‘_appends’ (e.g. products_appends)

If you extend a model with multiple properties, then use the same table alias for each property (improves performance).

foreignTableKey

Required: if you use setting storeExternally
Valid values: string - any valid MySQL column name

Define the primary key column name of your extension table.

Property types and their specific settings

See the sub-pages with descriptions of each built-in type.