This page will contain several components of the KikCMS you should familiarize yourself with to properly use the KikCMS and also to learn about it's capabilities.

Before you begin, make sure that you have setup a working dev environment.

Templates are what determine how a page looks. Each page you create in the CMS has it's own template. We will show you here how to create one.

Step 1: Add the template as option

1. Edit the following file, which looks something like this:

<?php
class TemplateFields extends TemplateFieldsBase
{
    public function getTemplates(): array
    {
        return [
            (new Template('home', 'Homepage')),
            (new Template('default', 'Default', ['content'])),
        ];
    }

    public function getFields(): array
    {
        return [
            'content' => (new WysiwygField('content:value', 'Page content', [new PresenceOf])),
        ];
    }
}

2. Add this to the getTemplates array:

(new Template('mytemplate', 'My template', ['content']))

Now when you create or edit a page, you have the option to choose the 'My template' template. The 3rd parameter contains which fields are in this template. You don't have to concern about that for now, just know that your template has a rich text editor for the field 'content'.

Creating a menu in you website is very easy. In your base template a menu has already been shown:

<nav>
    {{ helper.menu('main')|raw }}
</nav>

'main' is referring to the key given to the main menu you can see in the pages section of the CMS.

DataTable's are great to edit data, and here we'll show you how to use the data in your website. Note that this could be done with any data, not just data that was added using a DataTable.

Before proceeding, make sure you have a DataTable ready in the backend and added some records.

Now add this piece of code:

public function getHomeVariables(): array
{
    return [
        'persons' => Person::find(),
    ];
}

This tells the CMS to add an array of persons to the home template. The find mathod is part of Phalcon. You can now use this in the home template:

{% for person in persons %}
    <div>{{ person.name }}</div>
{% endfor %}

If you followed the previous part, you now output the person's name. Now change the code a little to add an image:

{% for person in persons %}
    <div>
        {{ person.name }}<br>
        <img src="{{ mediaFile(person.image_id, 'default') }}">
    </div>
{% endfor %}

To create your own custom DataTables and forms in the backend, you'll need to create a new menu item first.

Step 1: Add a menu item to the menu on the left

In the website settings file you'll see this method:

public function getMenuGroupMap(MenuGroupMap $menuGroupMap): MenuGroupMap
{
    return $menuGroupMap;
}

You can add a menu item by editing it in the following way:

public function getMenuGroupMap(MenuGroupMap $menuGroupMap): MenuGroupMap
{
    $myMenu = (new CmsMenuGroup('mymenu', 'My menu'))
        ->add(new CmsMenuItem('myMenuItem', 'My menu item', 'cms/mymenuitem'));

    return $menuGroupMap->addAfter($myMenu, 'mymenu', MenuConfig::MENU_GROUP_CONTENT);
}

Now you've added a new menu group called 'My menu', which is added after the 'content' group, with a menu item called 'My menu item'

Now notice the 3rd parameter of the menu item, this is the route.

Step 2: Add a route

So now we need to add a route, in the same file, in this method:

public function addBackendRoutes(Group $backend)
{
}

Now add a route:

public function addBackendRoutes(Group $backend)
{
    $backend->add('/mymenuitem', 'Module::myModule');
}

Notice that we didn't add cms/ to the route, this is because the $backend group always used a cms prefix.

These routes work like regular Phalcon routes, you can learn more about them here.

Step 3: Add content to the module

Now create the following file with the following content:

namespace Website\Controllers;

use KikCMS\Controllers\BaseCmsController;

class ModuleController extends BaseCmsController
{
    public function myModuleAction()
    {
        $this->view->selectedMenuItem = 'myMenuItem';
        $this->view->title  = 'My module';
        $this->view->object = 'Hi there!';
        $this->view->pick('cms/default');
    }
}

If you've worked with MVC frameworks before, these last 2 steps should feel very familliar to you.

You should now have a working new menu item!

Now that we have a new menu item in our CMS, let's make things more interesting and create a DataTable!

Step 1. Create a database table

We need to store the data somewhere, we'll create a MySQL table for this. Execute the following SQL:

myapp_person table

CREATE TABLE `myapp_person` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`name` varchar(255) COLLATE utf8_unicode_ci NOT NULL,
`image_id` int(11) DEFAULT NULL,
`active` tinyint(1) NOT NULL DEFAULT 0,
`type_id` int(11) NOT NULL,
PRIMARY KEY (`id`),
KEY `image_id` (`image_id`),
CONSTRAINT `myapp_person_ibfk_1` FOREIGN KEY (`image_id`) REFERENCES `cms_file` (`id`) ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;

Step 2. Create files

Now execute the following line from the root of your project:

php kikcms generate models

If you use docker, you should execute this command from your container, to do this from outside your container, run:

docker exec -ti <containername> sh -c "cd .. && php kikcms generate models"

Where you replace <containername> with your container name, which you can lookup with (last column NAMES contains the name):

docker ps

Now 6 new files should have been created. A Model, Form, List, Map, DataTable & Service file. We'll get into those later.

Step 3. Add form fields

To add and edit rows, we need to add fields to the DataTable's Form. Change the empty initialize method to:

app/Forms/PersonForm.php

protected function initialize()
{
    $this->addTextField(Person::FIELD_NAME, 'Name', [new PresenceOf]);
    $this->addSelectField(Person::FIELD_TYPE_ID, 'Type', [1 => 'Introvert', 2 => 'Extravert'], [new PresenceOf]);
    $this->addCheckboxField(Person::FIELD_ACTIVE, 'Active')->setDefault(1);
    $this->addFileField(Person::FIELD_IMAGE_ID, 'Image');
}

If you look at the code, you can guess what we did here. (PresenceOf is a not-empty validator).

Step 4. Display the DataTable

Now let's see what we've got! Now change 'Hi there' with (new Persons)->render() (and make sure you also add a 'use'):

app/Controllers/ModuleController.php

public function myModuleAction()
{
    $this->view->selectedMenuItem = 'myMenuItem';
    $this->view->title  = 'My module';
    $this->view->object = (new Persons)->render();
    $this->view->pick('cms/default');
}

Now check out https://localhost:9001/cms/mymenuitem, you now have a completely functional CRUD for persons!

Step 5. Make it more fancy

Great! But if you added some rows, you'll see the DataTable's table now shows some numbers that your client probably doesn't understand. Let's fix by chaning the initialize method in the DataTable class:

app/DataTables/Persons.php

$this->setCheckboxFormat(Person::FIELD_ACTIVE);
$this->setFieldFormatting(Person::FIELD_IMAGE_ID, [$this, 'formatFinderImage']);
$this->setFieldFormatting(Person::FIELD_TYPE_ID, function ($typeId){
    $types = [1 => 'Introvert', 2 => 'Extravert'];

    return $types[$typeId];
});

Things should look better now, an image preview, a checkbox, and better readable types!

Now let's make things even more interesting with a SubDataTable! We're going to add editable hobbies to the Persons.

Step 1. Table and files

Again, create a table:

myapp_person_hobby table

CREATE TABLE `myapp_person_hobby` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`name` varchar(255) COLLATE utf8_unicode_ci NOT NULL,
`person_id` int(11) NOT NULL,
`display_order` int(255) DEFAULT NULL,
PRIMARY KEY (`id`),
UNIQUE KEY `display_order` (`display_order`),
KEY `person_id` (`person_id`),
CONSTRAINT `myapp_person_hobby_ibfk_1` FOREIGN KEY (`person_id`) REFERENCES `myapp_person` (`id`) ON DELETE CASCADE ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;

And run again from your root (inside the docker container):

php kikcms generate models

Step 2. Create a relation

We need to let the app know what relation a SubDataTable has to the parent DataTable. We'll use Phalcons' own method to define this. Change the initialize method to this in the following file:

app/Models/Person.php

public function initialize()
{
    parent::initialize();

    $this->hasMany(self::FIELD_ID, PersonHobby::class, PersonHobby::FIELD_PERSON_ID, ['alias' => 'personHobbies']);
}

Step 3. Add form fields

Just like with the regular DataTable, we'll need to add some fields:

app/Forms/PersonHobbyForm.php

protected function initialize()
{
    $this->addTextField(PersonHobby::FIELD_NAME, 'Name', [new PresenceOf()]);
}

Step 4. Add the SubDataTable

Now add the DataTable form field to the Person form:

app/DataTables/Persons.php

protected function initialize()
{
    $this->addTextField(Person::FIELD_NAME, 'Name', [new PresenceOf]);
    $this->addSelectField(Person::FIELD_TYPE_ID, 'Type', [1 => 'Introvert', 2 => 'Extravert'], [new PresenceOf]);
    $this->addCheckboxField(Person::FIELD_ACTIVE, 'Active')->setDefault(1);
    $this->addFileField(Person::FIELD_IMAGE_ID, 'Image');

    $this->addDataTableField('personHobbies', PersonHobbys::class, 'Hobbies');
}

You should now check out the CMS, you can now add hobbies to persons!

Step 5. Make it more fancy

Let's also make this SubDataTable a little more fancy.

app/DataTables/PersonHobbys.php

public function getTableFieldMap(): array
{
    return [
        PersonHobby::FIELD_ID   => 'Id',
        PersonHobby::FIELD_NAME => 'Name',
    ];
}

And add this property: protected $sortable = true;

Now we've removed some redundant columns and made the items rearrangeable, check it out!

If you want to track your website's visitors, you can easily do so by using the available statistics module using Google Analytics.

• Create an analytics account
• Under Admin, Trackinginfo, trackingcode, copy paste the tracking code and add it in you base template.
• Under Admin, Data display settings, Copy the data display ID, and place it in app/config.ini under analytics > viewId
• Now enable the Analytics API here
• Now copy the e-mail address that has access to the API from the developer console to Google Analytics, and add it as a use with read permission.
• From the developer console, download a service-account-credentials.json file, and place in you env folder

I apologise for the many steps you need to take here, and the fact that you probably need to search around in google's anaytics system. Also I cannot give you more links or screenshots because google's UI changes more than you need to change a baby's diapers.

If you've followed all these steps, you can track visitor statistics from within the CMS!