Creating new libraries for Qoob in the theme

Libraries play key role in Qoob. They are conditionally divided into two types: libraries with blocks and libraries with media files (images, video). We can include an unlimited number of libraries into Qoob and also unite blocks and media files in one single library.

A standard library with blocks Default, that is located in the root of the plugin, comes along with Qoob plugin. In addition, it’s possible to include the library from the theme using the file function.php or remotely through the Qoob’s interface.

The list of included libraries is displayed in the interface of Qoob.

What does the library consist of?

Any library consists of the folders which contain the files of the block or media files from the main file lib.json, that describes the library in the form of json array.

The example of lib.json file

{
    "name": "keo",
    "groups": [{
        "id": "main",
        "label": "Main Blocks",
        "position": 0
    }],
    "blocks": [{
        "name": "mainblock",
        "url": "mainblock/"
    }],
    "assets": [{
        "type": "image",
        "src": "%theme_url%/assets/img/bg_pricing_block.jpg",
        "tags": ["bg", "background", "man"],
        "pack": "keo"
    }, {
        "type": "video",
        "src": {
           "url": "%theme_url%/assets/video/traffic.mp4",
           "preview": "%theme_url%/assets/img/main_bg_coming_video2.jpg"
         },
        "title": "Traffic",
        "tags": ["traffic", "city", "town", "street"],
        "pack": "keo"
    }],
    "res": [
        {
            "name": "fancybox_css",
            "type": "css",
            "url": "%theme_url%/blocks/fancybox/assets/css/fancybox.css",
            "use": {
                "frontend": true,
                "backend": true
            }
        },
        {
            "name": "fancybox_js",
            "type": "js",
            "url": "%theme_url%/blocks/fancybox/assets/js/fancybox.js",
            "use": {
                "frontend": true,
                "backend": true
            }
        }
    ]
}

Having got to know about the file, let’s consider it in details.

name accounts for the name of the library. Normally the name of the theme that the library is being created for is indicated.

groups include the array from the list of groups. Groups are essential for grouping blocks according to the concrete theme or functional.

Every group consists of these elements:

Name Type Default Description
id string The identifier of the group. Identifiers in different groups can coincide.
label string The name of the group.
position int The position of the group in the list of groups.

Blocks is responsible for including blocks. This is an array with a number of blocks.

Name Type Default Description
name string The name of the block.
url string The path to the block.

Assets are used for adding images, video, icons into the Qoob’s media library. The parameters for media elements can vary.

Name Type Default Description
type string The type of the media file image, video, icon
src string The path to the media file
tags array The list of tags. Tags can be used for searching on the media library.
pack string The name of the pack. Files can be grouped шn the packs which can be selected in the media library then.
preview string video type only The path to the preview image is used for video preview only for the file type video
title string video type only The title of the video, e.g. “Traffic video”, is used only for the file type video
classes string icon type only Classes for an icon, e.g. “fa fa-adjust”, are used only for the file type icon

Res attaches css and js files which are used in the library.

Name Type Default Description
name string File’s name that is used as handle for the included file.
url string The path to the file.
type string It contains the key “js” or “css”
use string json object. It is responsible for including files on the user’s side or in the admin panel. It contains the key “frontend” or “backend” with value true or false.

How to create a block?

A block consists of three files: config.json, preview.png, template.hbs or template.html. Also it can contain images or video.

The example of config.json file

{
    "name": "",
    "groups": "news",
    "template": "template.hbs",
    "settings": [{
        "name": "block_id",
        "label": "Block's id",
        "type": "text",
        "placeholder": "Enter id"
    }, {
        "name": "header",
        "label": "Block's header",
        "type": "text",
        "placeholder": "Enter header"
    },
    {
        "name": "ajax_url",
        "label": "Ajax url",
        "type": "text",
        "placeholder": "Enter ajax url"
    }],
    "defaults": {
        "block_id": "",
        "header": "Last news",
        "ajax_url": "/wp-admin/admin-ajax.php"
    }
}
Name Type Default Description
name string The name of the block. It can be empty.
groups string The group the block belongs to.
template string The name of the html template file.
blockTemplateAdapter string hbs or underscore. By default Qoob uses template builder hbs. If you’re willing to make templates with the help of underscore it’s necessary to add this parameter.
settings array The array of fields which are used for configuring the block.
defaults object The objects with default values, the default values are compulsory.

The file preview.png is used for displaying thumbnails of blocks in the list. The recommended width of the image is 236px.

To save images and video it’s advisable to create the folder assets. To show the path to media files we can use masks:

%block_url% – shows the path to the root folder of the block
%block_url(media_assets)% – shows the path to the root folder of the block. It’s necessary to indicate the name of the block the url to which we want to get.
%theme_url% – the path to the active theme