Creating custom data with backend list and edit form

In this article you learn how to create custom data with lists in the backend and forms for admins to manage it. You will learn how a controller, model, list view and form view play together and how to write the classes and templates for each. This is described in a step-by-step tutorial and on the sub-pages you find detailled information of each concept.

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

Create a menu in the backend

The left-hand side menu in CB is handled by the view adminmainmenu. By way of template overrides, we add a link to the list view we will create. You find the original template in {{APPLICATION_DIR}}/views/adminmainmenu/tmpl/default.php. For practical reasons, the default template loads another template named extra_menu_items.php, which is meant for additions to the menu without the need to override the entire menu.

You can override that extra menu items template by adding a file in this location:

{{CUSTOMIZATION_DIR}}/templates/adminmainmenu/extra_menu_items.php

<?php
defined('CB_VALID_ENTRY') or die();
/** @var $this ConfigboxViewAdminmainmenu */
?>

<ul class="menu-list">
    <li class="menu-list-item item-adminconfig">
        <a class="menu-link ajax-target-link" href="<?php echo KLink::getRoute('index.php?option=com_configbox&controller=adminlogos');?>"><?php echo KText::_('Logos');?></a>
    </li>
</ul>

We are mentioning the controller while getting the link for the menu. This controller will be responsible to handle the page.

The link to your list:

echo KLink::getRoute('index.php?option=com_configbox&controller=adminlogos');

You see that all link URLs are done using KLink::getRoute(). As parameter you supply a URI starting with index.php and you append a query string. option=com_configbox is fixed, controller=adminlogos instructs the system to use the controller (we create this in the next step). The query string parameter ‘task‘ would instruct which task to execute - ‘display’ is the default task if you omit it.

Create a controller

All browser HTTP requests go through controllers. The KenedoController base class has generic methods for tasks like ‘display’, ‘edit’, ‘store’, ‘delete’ etc.

In our controller files we simply supply configuration, but we could also override the task methods.

Upon clicking a menu in the backend, a page should be rendered. For this operation, we need a controller. Since it is a custom controller, we should create the file in the following path:

{{CUSTOMIZATION_DIR}}/controllers/adminlogos.php

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

class ConfigboxControllerAdminlogos extends KenedoController {

    /**
     * @return ConfigboxModelAdminlogos
     * @throws Exception
     */
    protected function getDefaultModel() {
        return KenedoModel::getModel('ConfigboxModelAdminlogos');
    }

    /**
     * @return ConfigboxViewAdminlogos
     * @throws Exception
     */
    protected function getDefaultView() {
        return $this->getDefaultViewList();
    }

    /**
     * @return ConfigboxViewAdminlogos
     * @throws Exception
     */
    protected function getDefaultViewList() {
        return KenedoView::getView('ConfigboxViewAdminlogos');
    }

    /**
     * @return ConfigboxViewAdminlogo
     * @throws Exception
     */
    protected function getDefaultViewForm() {
        return KenedoView::getView('ConfigboxViewAdminlogo');
    }

}

About the methods:

getDefaultModel() - returns the model responsible for any tasks to execute.
getDefaultViewList() - returns the view responsible for rendering a list of records
getDefaultViewForm() - returns the view for rendering an edit form for a record
getDefaultView() - This is used for frontend use of a controller, for backend you can just return the list view.

For more details about the controllers, please refer KenedoController.

Create a model

Model is responsible to handle all the database operations. As mentioned in the above controller, we should create a model class in the following path:

{{CUSTOMIZATION_DIR}}/models/adminlogos.php

KenedoModels contain generic functions for CRUD operations and typically you only need to supply configuration:

getTableName() - returns the name of the DB table that stores the model’s data (#__ is a placeholder for a table prefix)
getTableKey() - returns the name of the primary key column.
getPropertyDefinitions() - returns settings for each property of the records. In the above code, we have defined 3 properties - ID, Title and the uploaded file.

For more details about the models, please refer KenedoModel. Properties are described in KenedoProperty.

Create a DB update script to create a table

With your model’s properties in place, you create the database table using an update script. It will be executed automatically by the Kenedo platform (during app initialisation on Joomla and WP, during setup:upgrade on M2).

The following file can be used to create a table to store the logos:

{{CUSTOMIZATION_DIR}}/updates/0.0.1.php

Note: The property ‘title’ (type translatable) stores itself in a separate table (configbox_strings) and does need a column in the base table.

Execution of database scripts are maintained by the configbox_system_vars table. The last executed version is noted down in this table. For more details about the execution procedure, please refer to the article about Application Update Scripts.

Create the views

The views responsible to render the listing and form should be created in this step. We have to create 2 views as mentioned in the controller - one for displaying a list of record, the other for an edit form.

For more details about the views, please refer KenedoView.

Creating view for the list

The following files are needed to create the list view:

{{CUSTOMIZATION_DIR}}/views/adminlogos/tmpl/default.php

This file just loads a generic template for HTML of lists.

{{CUSTOMIZATION_DIR}}/views/adminlogos/metadata.xml

This file is for Joomla - it ensures that this view does not show up in the Joomla menu manager.

{{CUSTOMIZATION_DIR}}/views/adminlogos/view.html.php

This file holds the configuration for the view.

Creating view for form

The following files are needed to create the form view. It follows the same principles as the list view.

{{CUSTOMIZATION_DIR}}/views/adminlogo/tmpl/default.php

{{CUSTOMIZATION_DIR}}/views/adminlogo/metadata.xml

{{CUSTOMIZATION_DIR}}/views/adminlogo/view.html.php

Verify the output

After creating the files and code as per the above instructions, we should be able to see the following:

Menu added to the backend
Upon clicking the menu, a listing of all the logos can be seen
By clicking one of the logos, we can edit the details of that logo
We can add a new logo by clicking the Add button

ConfigBox 3 for Joomla and Wordpress