What is this article for

Here you learn how to create lists and forms for custom data structure. With a KenedoModel sub-class you define your data and optionally override the base class' methods for storing, loading etc. It works together with KenedoController and KenedoView for a complete MVC pattern. Here we explain how to set up a model in your customisation folder and how to use it.

What is the KenedoModel base class

KenedoModel classes deal with saving and loading data sets in cooperation with KenedoControllers and KenedoViews. You may override any methods for storing/loading, but typically you simply define data and let the base class methods do their thing. The important things you define in a model are these:

• The model’s name

• The DB table holding the data

• The primary key column name

• The properties of the model (typically one for each DB table column, but depending on the property type, data can be stored elsewhere or completely differently).

Model name

The sub-class' name must start with ‘ConfigboxModel’, followed by a sensible choice of name of the type of data (e.g. ‘Examples’, this is referred to as ‘model name’).

In customization projects you may want to prefix your model name to avoid future naming collisions with built-in models.

DB table name

Generally, a model’s data is stored in one database table. Use the KenedoModel's function getTableName() to return the name. Use #__ as placeholder for the application's table prefix. Per convention, best use #__configbox_external_[model name].

DB primary key column name

Use the function getTableKey() to return the name of the property serving as primary key (more info about Properties later).

Properties of the model

With KenedoModel you configure your data and its storing/loading behavior as well as its appearance in backend lists and forms. And you can override any base methods and create custom properties where you need to.

To define the data handled by your KenedoModel, you define called Properties. Each property is of a certain type (ID, boolean, file, image, dropdown etc) and has settings. Each Property’s type and the settings affect how the model’s backend form appears and how CRUD operations function.

To define the properties in your models, you implement the method getPropertyDefinitions() and have it return an array with property settings. There are about 20 built-in types which are specialised for various purposes (like image uploads, drop downs, calendars, translatable strings, yes/no questions etc) and you can also make your own types.

In this example you simply define a primary key property called 'id' of type 'id'. This will make KenedoModel instantiate a KenedoPropertyId using the various settings in that array. More about all that follows.

Property types

Knowing the property types, what their ideal purpose and their settings are will help you creating data types quickly and with ease. In this article you find an overview of properties and all settings. In the following we try a tutorial example approach to see what properties do.

Imagine you want to make a data set for an image gallery. You have

• an ID

• an internal name for your backend list

• a multi-language caption

• an image (thumbnail and large version) 

• a position number for ordering

• an on/off switch for each image.

In your KenedoModel, you pick an appropriate property type for each of those and configure them. Once done, KenedoModel and KenedoView use that info to display backend lists, edit forms and to load and store data you provide.

See this table, where we pick a name and type for each of the properties of our image gallery items:

Lets have a look again at one of these arrays holding settings for a property - we will take the name property (type 'string')

We call the things like 'name', 'type', 'label' etc. property settings. Most are common across all types, some are specific to a type. Here we describe the common ones:

See KenedoProperties for all details on working with properties.

Adding the DB table for the model

Each KenedoModel has it’s data stored in a typical DB table, which you create it yourself (choosing appropriate column types, indices etc). You add these tables with any tool you prefer - if you want to make use of a deployment scheme, see Application Update Scripts on how to create or modify tables for the base software or customization projects.

Adding controller, model and views

We've been talking about KenedoModel as isolated thing without the files and file locations to actually make use if it. The locations and file names are like this:

Controllers

Built-in controllers are in {appDir}/controllers and the files are named like this: Class name is ConfigboxControllerAdminexamples and the file name is adminexamples.php

Custom controllers are in {customizationDir}/controllers and have the same naming convention.

In a minimal implementation of a controller, do this:

• Tell the controller which model it works with (method getDefaultModel).

• Which view to use for showing a backend edit form (method getDefaultViewForm)

• Which view to use for a list of records (method getDefaultViewList)

• Which view to use for general purpose (method getDefaultView) - usually return the list’s view

To call a controller task (like 'edit') you use these GET parameters: option=com_configbox&controller=adminexamples&task=edit

That will instantiate the right controller and call its edit() method. edit() and the other base methods for CRUD operations are generic and use getDefaultModel() to know which model to work with.

Note: If you want to replicate that example, use a different name. There is already a controller adminexamples in the built-in controllers folder for illustration purposes.

Models

Built-in models are in {appDir}/models and the files are named like this: Class name is ConfigboxModelExamples and the file name is examples.php

Custom models are in {customizationDir}/models and have the same naming convention.

Views

Typically there are two views for the backend of a type of data. A list view and an edit view (in the corresponding controller you define those view classes).

Built-in views have a subfolder in {appDir}/views and that subfolder is named like this: Class name is ConfigboxViewAdminexamples and the subfolder is adminexamples.

Custom views are in {customizationDir}/views and have the same naming convention.

In that subfolder you have a file named view.html.php that contains your PHP class. And in that folder there is another subfolder called 'tmpl' containing a default.php file which is your template file.

From other frameworks you may be used to load the data for your template in the controller. In Kenedo, the data loading is handled by a view class method (called prepareTemplateVars). The controller merely passes HTTP request data and handles authentication and lets the view load data.

To make the view aware of what data to deal with, you use getDefaultModel and the view knows what to do. getPageTitle() lets you control the heading of the page. The class variables $component and $controllerName tell what component/controller to use for the various buttons and refreshes.

Example for an admin list view class:

Bringing it all together for an overview

For our example, lets summarise the file locations:

All these files exist in the built-in folder location for illustration. If you try to replicate this, use different names (CB searches first in the built-in locations and after that in the customization folder).

Using the MVC maker

Since making all these files can be cumbersome and repetitive, CB comes with an MVC maker that creates the files for you. See MVC Maker for details.