====== Secondary type extensions ====== this is the type of extension for mobirise 4, with the settings inside the template.html file and the styling inside the style.less file The complete description of this component structure is given in [[https://mobirise.com/docs/]] **Those extensions are editable with witsec or deltapi code-editors !** Δπ ====== Documentation ====== ===== Components formatting ===== ==== Adjustment of a `params.json` file for a secondary type component ==== A components list should be presented in this format:


    "components": [
        {
            "_group": "Headers",
            "path": "components\/header1",
        "_isSecondary": true
        },
        ...
    ]

Avoid using attributes like ''%%`_once`%%''. ==== A component file structure ==== * template.html * style.less * thumb.png A catalog may contain some images, it’s possible to refer to them the ways described below. From parameters:

From a template:

==== Component settings (attributes) ==== Component attributes are used in a parent element of a template. * ''%%group%%'' - group name * ''%%plugins%%'' - a comma separated plugins * ''%%always-bottom%%'' - a component is placed always at the bottom * ''%%always-top%%'' - a component is placed always on the top * ''%%global%%'' - a global component * ''%%not-draggable%%'' - a non draggable component * ''%%position-absolute%%'' - a component has an absolute position Example for a menu component:

**ALERT:** The `group` attribute doesn't influence anything at this time and will be used later in the theme exporting. ===== Expressions ===== The expressions work in interpolation of values, directives and `conditions` within parameters (check the 'Interpolation in attributes' section). The expressions are the same as in **ECMAScript** (**JavaScript**), but they have some extra features: * - The context is only local: there are no variables except for the ones declared in the parameters. * - A tolerance to non-declared variables: the script does not fail if there is no variable or value. * - There is a filter support (not maintained?). * - Assigning values is not allowed. * - Square brackets are not allowed - ''%%item['name']%%'' or even ''%%item[0]%%'' (it can work in **RivetsJS**). * - Using of loops, conditionals and exceptions is not allowed. * - Declaring functions isn't allowed. * - Using of RegExp with literal notation isn't allowed. * - Creating objects using the ''%%new%%'' operator isn't allowed. * - Using of bitwise-operators, the ''%%,%%'' operator or ''%%void%%'' isn't allowed. ===== Parameters ===== All tags that cannot be interpreted as parameters are ignored. ==== A section title ====


Section

==== A break line ====

==== Text fields ====


Default Text

==== Checkboxes/Radio buttons ====

==== A drop-down options list ====

It supports the ''%%inline%%'' attribute:

==== Color ====

==== Range ====

It supports the ''%%inline%%'' attribute:

==== Font ====

==== Image ====

==== Video ====

==== Background ====

The ''%%parallax%%'' attribute for the''%%fieldset%%'' tag shows the on/off parallax switch. If the same attribute is set for an image, it means that parallax is enabled. If it is absent, parallax is disabled. This parameter supports only three background types ''%%image%%'', ''%%color%%'' and ''%%video%%''. The current choice is denoted by the ''%%selected%%'' parameter for a corresponding tag. The ''%%title%%'' attribute assigns a title for the switch. In the rest, the nested parameters behave like the autonomous parameters, but they don't require the''%%name%%'' attribute. The value of the bg variable for the previous example looks this way:


    {
        "type": "color",
        "value": "#073B4C",
        "parallax": false,
        "image": {
            "value": "background5.jpg",
            "parallax": true
        },
        "color": {
           "value": "#073B4C"
        },
        "video": {
            "value": {
                "url": "http://www.youtube.com/watch?v=uNCr7NdOJgw"
            }
        }
    }

The selected type of background is stored in the ''%%type%%'' key, and the value is in ''%%value%%''. If the selected type is an image, and the parallax switch is shown in the interface, then the ''%%parallax%%'' key shows whether parralax is enabled or disabled. In addition, regardless of the current selection other type settings can be get by a needed key. Some variables are used in CSS too, but only partically.


    @bg-value: "background5.jpg";
    @bg-type: "image";
    @bg-color-value: #073B4C;
    @bg-parallax: true;

It's possible to access only the current selection through variables. The exception is ''%%@bg-color-value%%''. It can be useful in the cases when the background is an image, but it is loading slowly or can't be loaded at all. The background color should be set in the contrast with the text. As you can see, to get the access to the values, you need to use the hyphen instead of the dot - ''%%bg.color.value%%'' in templates and ''%%@bg-color-value%%'' in CSS. ==== Map ==== It's used along with the **mbr-map** directive.

==== A hidden parameter ====

==== Conditionals ==== The ''%%condition%%'' attribute for parameters allows to control visibility depending on a condition.

===== Templates ===== ==== The mbr-text directive ==== A simple text without an extended text editor.


Address...

This directive is set automatically for the following tags: **H1**, **H2**, **H3**, **H4**, **H5**, **P**. ==== The mbr-article directive ==== An article text with an extended text editor.



        Lorem ipsum dolor sit amet.
        ...

==== The mbr-buttons directive ==== The element is interpreted as a buttons group.



        Button 1
        Button 2

==== The mbr-menu directive ==== An element is interpreted as a menu.


    
        HOME
        FEATURES

==== The tag ==== An element is interpreted as an image automatically.

**ALERT:** Don't add directives like ''%%mbr-if%%'' to a parent link, because they can be removed with the help of an image editor. Use a container if it's needed. ==== The mbr-icon directive ==== It specifies an icon.

**ALERT:** You shouldn't add the ''%%mbr-icon%%'' attribute to a link. **ALERT:** Don't add directives like ''%%mbr-if%%'' to a parent link, because they can be removed with the help of an icon editor. Use a container instead. ==== The mbr-video directive ==== An element is interpreted as a video:

==== The mbr-map directive ==== A parameter name is used as an attribute value. Only one parameter type is supported: **map**.

A map has several states: **Loading**

**Loading error (if a location is not found)**


    
        Not found

**Map representation**

...

Styles are needed during the change of address to make clear what is going on. There's a simple example:


    .google-map {

        height: 25rem;
        position: relative;

        iframe {
            height: 100%;
            width: 100%;
        }

        [data-state-details] {
            color: #6b6763;
            font-family: Montserrat;
            height: 1.5em;
            margin-top: -0.75em;
            padding-left: 1.25rem;
            padding-right: 1.25rem;
            position: absolute;
            text-align: center;
            top: 50%;
            width: 100%;
        }

        &[data-state] {
            background: #e9e5dc;
        }

        &[data-state="loading"] {

            [data-state-details] {
                display: none;
            }

            &::after {
                // loader
            }

        }

    }

==== The mbr-form directive ==== An element is interpreted as a **form**:

It can have a nested structure. An element with a **data-form-alert** attribute is intended to show messages with the result of a form sending. To make a message initially hidden, use the **hidden** attribute.


    
        
            Thanks for filling out the form!
        
        
            
            SUBSCRIBE

The **name** attribute of the form is responsible for a title of a submited form. The **action** attribute may contain an e-mail or a handler script URL.

Elements **input** placed inside a form should contain a unique **name** attribute. The **data-form-field** value is a name of a field in a form editor window.

It's possible to add **** for form inputs. To bind them, it's necessary to add the **for** attribute to a label and add a proper input name as the value.


Phone

Also there is a possibility to control visibility of html elements inside a form depending on the visibility of certain inputs of this form. It's necessary to define the **data-for** attribute with a name attribute of a needed input as a value. Only one dependency can exist at this time.

==== The mbr-if directive ==== It shows/hides a block depending on a condition:


Header



        Header

==== The mbr-style directive ====

**ALERT:** ''%%url()%%'' - is the only one function in templates that wraps a value in ''%%'url(...)'%%'' if it exists. ==== The mbr-class directive ==== Parameters:


    showTitle = true
    showText  = false
    blockType = "flat"

==== Interpolation in attributes ==== Any attribute if it contains a syntactically correct expression inside double braces ''%%{{ ... }}%%'' becomes active and changes dynamically by changing parameters.

===== Tracing of component changes from custom scripts ===== Component changes can be traced on a **JavaScript** user level. Example:


    $(function(){
        $(document).on('add.cards', function(event) {
            // this code will be applied to every added component
            // to access the component, event.target can be used
        });
    });

All generated events have one namespace ''%%cards%%''. ==== Recommendations for Use ==== Events are needed only for work with the program, and a site would operate normally without them. It means that events should be used only when it's absolutely necessary. The most proper way for using of events is when it's necessary to use some third-party library or script. Let's take a look at a circle progress bar. We have a parameter of a **range** type here:

And a template:

I.e. a **progress** value is used in percents in a ''%%data-progress%%'' attribute. And during a call: ''%%$('.circle-progress').circleProgress()%%'' a **jQuery** plugin generates a progress bar based on the value of the ''%%data-progress%%'' attribute. It should work this way:


    $('.circle-progress').each(function() {
        $(this).circleProgress({
           value:  $(this).attr('data-progress') || '0%'
        });
    } );

The thing is that this code should be applied not only during loading, but also when a component is added. So we do it this way:


    function initCircleProgress(card) {
        // we search .circle-progress inside a block and call the circleProgress() method
        $(card).find('.circle-progress').each(function() {
            $(this).circleProgress({
               value:  $(this).attr('data-progress') || '0%'
            });
        } );
    }

    $(document).on('add.cards', function(event) {
        initCircleProgress(event.target);
    });

This code should work during a project loading and while adding a component. What can we do with the change of the **progress** value?


    $(document).on('changeParameter.cards', function(event, paramName, value) {
        if (paramName == 'progress') {
            initCircleProgress(event.target);
        }
    });

**ALERT:** It is recommended to avoid using ''%%value%%'' of changed parameters, it's better to take them directly from DOM, this method will help avoid a lot of problems. During initialization some libraries start tracking events (for example, onScroll or onResize of a browser window), and they has a special method to reset all to initialization state. It's important to remember that:


    $(document).on('delete.cards', function(event) {
        $(event.target).find('.circle-progress').circleProgress('destroy');
    });

There is one issue left: what if a site is opened in a browser but not in the program. How to call an **add.cards** event? If we call ''%%initCircleProgress()%%'' during a page loading, there is a chance that the **initCircleProgress** method will be used twice if we open a page in the app: during a page loading and when an **add.cards** event will happen. There are some options to avoid it, the easiest one is to check where a script is, is it in the program or in a browser? The code will look like this:


    $(function(){

        var isBuilder = $('html').hasClass('is-builder');

        function initCircleProgress(card) {
            $(card).find('.circle-progress').each(function() {
                $(this).circleProgress({
                   value:  $(this).attr('data-progress') || '0%'
                });
            } );
        }

        if (isBuilder) {
            $(document).on('add.cards', function(event) {
                initCircleProgress(event.target);
            }).on('delete.cards', function(event) {
                $(event.target).find('.circle-progress').circleProgress('destroy');
            }).on('changeParameter.cards', function(event, paramName) {
                if (paramName == 'progress') {
                    initCircleProgress(event.target);
                }
            });
        } else {
            initCircleProgress(document.body);
        }

    });

==== add.cards Event ==== It happens when a component is added or it loads from a project. It's possible to access the added element using ''%%event.target%%''. ==== delete.cards Event ==== It happens when a component is removed. Using ''%%event.target%%'', you can access an element to be deleted. ==== drag.cards Event ==== It happens when a component is dragged. Here is an example:


    $(function(){
        $(document).on('drag.cards', function(event, oldPrevCard) {
            // this code will be executed for a dragged component
            // event.target - a dragged component
            // oldPrevCard - a component that was located above a dragged component before the dragging
        });
    });

==== changeParameter.cards Event ==== It happens when a parameter is changed. Here is an example:


    $(function(){
        $(document).on('changeParameter.cards', function(event, paramName, value, key) {
            // this code will be executed when a parameter is changed
            // event.target - a component in which the parameters have changed
            // paramName - a parameter name
            // value - a value of a parameter
            // key - a value to be changed (rarely used)
        });
    });

**key** can help with the work with a **background** parameter, for example: when **parallax** is changed, there is an array as a **value**: ''%%{type: '', value: '', parallax: '', ...}%%'' and in this moment we don't know what is changed exactly: a background type or a single attribute. It means that we should keep a previous state to follow changes or reset all changes and set the new ones - that isn't good too. The **key** parameter can help in this case:


    $(function(){
        $(document).on('changeParameter.cards', function(event, paramName, value, key) {
            if (paramName == 'bg') {
                switch (key) {
                    case 'type':
                        // a background type is changed
                        break;
                    case 'value':
                        // change of the color or image or video location
                        // (it depends on the background type)
                        break;
                    case 'parallax':
                        // parallax is enabled/disabled
                        break;
                }
            }
        });
    });

==== changeContent.cards Event ==== Happens after editing of icons, images or videos. Example:


    $(function(){
        $(document).on('changeContent.cards', function(event, type) {
            // event.target - an edited item
            // type - a type of an edited item
        });
    });