Differences

This shows you the differences between two versions of the page.

--- secondary_extensions [2019/08/18 16:48] – created Degand Patrick
+++ secondary_extensions [2024/09/01 14:30] (current) – external edit 127.0.0.1
@@ Line 3: / Line 3: @@
 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:
+<code>
+    "components": [
+        {
+            "_group": "Headers",
+            "path": "components\/header1",
+        "_isSecondary": true
+        },
+        ...
+    ]
+</code>
+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:
+<code>
+<input type="image" title="Image" name="bgImg" value="logo.png">
+</code>
+From a template:
+<code>
+<img src="logo.png" height="128" alt="Mobirise">
+</code>
+==== 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:
+<code>
+<section
+        group="Menu"
+        plugins="DropDown, TouchSwipe"
+        always-top
+        global
+        not-draggable
+        position-absolute
+    ></section>
+</code>
+**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 ====
+<code>
+<header>Section</header>
+</code>
+==== A break line ====
+<code>
+<hr/>
+</code>
+==== Text fields ====
+<code>
+<input type="text" title="Text" name="text" value="Default Text">
+</code>
+<code>
+<textarea title="Textarea" name="text">Default Text</textarea>
+</code>
+==== Checkboxes/Radio buttons ====
+<code>
+<input type="checkbox" title="Show Title" name="showTitle" checked>
+</code>
+<code>
+<input type="radio" title="Radio 1" name="radio" value="1">
+</code>
+<code>
+<input type="radio" title="Radio 2" name="radio" value="2" checked>
+</code>
+==== A drop-down options list ====
+<code>
+<select title="Alignment" name="textAlign">
+        <option value="left">Left</option>
+        <option value="center" selected>Center</option>
+        <option value="right">Right</option>
+    </select>
+</code>
+It supports the ''%%inline%%'' attribute:
+<code>
+<select inline title="Alignment" name="textAlign">
+        <option value="left">Left</option>
+        <option value="center" selected>Center</option>
+        <option value="right">Right</option>
+    </select>
+</code>
+==== Color ====
+<code>
+<input type="color" title="Background" name="bgColor" value="#ffffff">
+</code>
+==== Range ====
+<code>
+<input type="range" title="Font Size" name="fontSize" min="0.6" max="4" step="0.025" value="0.625">
+</code>
+It supports the ''%%inline%%'' attribute:
+<code>
+<input type="range" inline title="Font Size" name="fontSize" min="0.6" max="4" step="0.025" value="0.625">
+</code>
+==== Font ====
+<code>
+<input type="font" title="Font" name="font" value="Oswald">
+</code>
+==== Image ====
+<code>
+<input type="image" title="Image" name="bgImg" value="bg-image.png">
+</code>
+==== Video ====
+<code>
+<input type="video" title="Video" name="bgVideo" value="http://www.youtube.com/watch?v=uNCr7NdOJgw">
+</code>
+==== Background ====
+<code>
+<fieldset type="background" name="bg" parallax>
+        <input type="image" title="Background Image" value="background5.jpg" parallax>
+        <input type="color" title="Background Color" value="#073B4C" selected>
+        <input type="video" title="Background Video" value="http://www.youtube.com/watch?v=uNCr7NdOJgw">
+    </fieldset>
+</code>
+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:
+<code>
+    {
+        "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"
+            }
+        }
+    }
+</code>
+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.
+<code>
+    @bg-value: "background5.jpg";
+    @bg-type: "image";
+    @bg-color-value: #073B4C;
+    @bg-parallax: true;
+</code>
+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.
+<code>
+<input type="map" title="Map" name="googleMap">
+</code>
+==== A hidden parameter ====
+<code>
+<input type="hidden" name="hiddenParam" value="Lorem ipsum dolor sit amet.">
+</code>
+==== Conditionals ====
+The ''%%condition%%'' attribute for parameters allows to control visibility depending on a condition.
+<code>
+<input type="color" title="Background" name="bgColor" value="#ffffff" condition="backgroundType == 'color'">
+</code>
+===== Templates =====
+==== The mbr-text directive ====
+A simple text without an extended text editor.
+<code>
+<div mbr-text>Address...</div>
+</code>
+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.
+<code>
+<div mbr-article>
+        <p>Lorem ipsum dolor sit amet.</p>
+        ...
+    </div>
+</code>
+==== The mbr-buttons directive ====
+The element is interpreted as a buttons group.
+<code>
+<div mbr-buttons>
+        <a class="btn btn-primary" href="https://mobirise.com">Button 1</a>
+        <a class="btn btn-danger" href="https://mobirise.com">Button 2</a>
+    </div>
+</code>
+==== The mbr-menu directive ====
+An element is interpreted as a menu.
+<code>
+    <ul class="navbar-nav nav-dropdown" mbr-menu>
+        <li class="nav-item"><a class="nav-link link" href="https://mobirise.com">HOME</a></li>
+        <li class="nav-item"><a class="nav-link link" href="https://mobirise.com">FEATURES</a></li>
+    </ul>
+</code>
+==== The <IMG> tag ====
+An element is interpreted as an image automatically.
+<code>
+<img src="logo.png" height="128" alt="Mobirise">
+</code>
+or
+<code>
+<a href="#"><img src="logo.png" height="128" alt="Mobirise"></a>
+</code>
+**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.
+<code>
+<span mbr-icon class="mbri-mobirise mbr-iconfont" style="font-size: 96px; color: rgb(255, 51, 102);"></span>
+</code>
+or
+<code>
+<a href="#"><span mbr-icon class="mbri-mobirise mbr-iconfont" style="font-size: 96px; color: rgb(255, 51, 102);"></span></a>
+</code>
+**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:
+<code>
+<div mbr-video>
+        <iframe src="http://www.youtube.com/watch?v=uNCr7NdOJgw"></iframe>
+    </div>
+</code>
+==== The mbr-map directive ====
+A parameter name is used as an attribute value. Only one parameter type is supported: **map**.
+<code>
+<div class="google-map" mbr-map="googleMap"></div>
+</code>
+A map has several states:
+**Loading**
+<code>
+    <div class="google-map" mbr-map="googleMap" data-state="loading">
+        <div data-state-details></div>
+    </div>
+</code>
+**Loading error (if a location is not found)**
+<code>
+    <div class="google-map" mbr-map="googleMap" data-state="not found">
+        <div data-state-details>Not found</div>
+    </div>
+</code>
+**Map representation**
+<code>
+    <div class="google-map" mbr-map="googleMap">
+        <iframe>...</iframe>
+    </div>
+</code>
+Styles are needed during the change of address to make clear what is going on. There's a simple example:
+<code>
+    .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
+            }
+        }
+    }
+</code>
+==== The mbr-form directive ====
+An element is interpreted as a **form**:
+<code>
+    <form mbr-form class="mbr-form" action="ebthemes@gmail.com" method="post" name="My Mobirise Form">
+</code>
+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.
+<code>
+    <div mbr-form>
+        <div data-form-alert hidden>
+            Thanks for filling out the form!
+        </div>
+        <form class="mbr-form" action="ebthemes@gmail.com" method="post" name="My Mobirise Form">
+            <input type="email" class="field" name="email" data-form-field="Email" placeholder="Email" required>
+            <a data-app-btn='true' type='submit' class='btn'>SUBSCRIBE</a>
+        </form>
+    </div>
+</code>
+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.
+<code>
+<form name="My Mobirise Form" action="ebthemes@gmail.com" method="post">
+</code>
+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.
+<code>
+<input type="email" name="email" class="field"  data-form-field="Email" placeholder="Email" required>
+</code>
+It's possible to add **<label>** 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.
+<code>
+<label mbr-text class="form-label" for="phone">Phone</label>
+</code>
+<code>
+<input type="tel" name="phone" class="form-control" data-form-field="Phone">
+</code>
+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.
+<code>
+    <div class="col-md-6 multi-horizontal" data-for="name">
+        <input type="text" class="input" name="name" data-form-field="Name" placeholder="Your Name" required>
+    </div>
+</code>
+==== The mbr-if directive ====
+It shows/hides a block depending on a condition:
+<code>
+<h1 mbr-if="showTitle">Header</h1>
+</code>
+or
+<code>
+<div mbr-if="showTitle || showText">
+        <h1 mbr-if="showTitle">Header</h1>
+        <div mbr-if="showText"></div>
+    </div>
+</code>
+==== The mbr-style directive ====
+<code>
+<section mbr-style="{'background-color': bgColor, 'background-image': url(bgImg)}"></section>
+</code>
+**ALERT:** ''%%url()%%'' - is the only one function in templates that wraps a value in ''%%'url(...)'%%'' if it exists.
+==== The mbr-class directive ====
+Parameters:
+<code>
+    showTitle = true
+    showText  = false
+    blockType = "flat"
+    <span mbr-class="{'with-title': showTitle, 'with-text': showText}"></span>
+    <span class="with-title"></span>
+</code>
+or
+<code>
+    <span mbr-class="blockType"></span>
+    <span class="flat"></span>
+</code>
+or
+<code>
+    <span mbr-class="blockType == 'flat' ? 'flat-style' : '3d-style'"></span>
+    <span class="flat-style"></span>
+</code>
+or
+<code>
+    <span mbr-class="[blockType, {'with-title': showTitle, 'with-text': showText}]"></span>
+    <span class="flat with-title"></span>
+</code>
+==== Interpolation in attributes ====
+Any attribute if it contains a syntactically correct expression inside double braces ''%%{{ ... }}%%'' becomes active and changes dynamically by changing parameters.
+<code>
+<div title="color: {{bgColor}}"></div>
+</code>
+or
+<code>
+<div style="background: {{bgColor}}"></div>
+</code>
+or
+<code>
+<div data-video-src="{{bgVideo.url}}"></div>
+</code>
+===== Tracing of component changes from custom scripts =====
+Component changes can be traced on a **JavaScript** user level. Example:
+<code>
+    $(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
+        });
+    });
+</code>
+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:
+<code>
+ <input type="range" name="progress" min="0" max="100" step="1" value="50">
+</code>
+And a template:
+<code>
+<div class="circle-progress" data-progress="{{progress}}%"></div>
+</code>
+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:
+<code>
+    $('.circle-progress').each(function() {
+        $(this).circleProgress({
+           value:  $(this).attr('data-progress') || '0%'
+        });
+    } );
+</code>
+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:
+<code>
+    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);
+    });
+</code>
+This code should work during a project loading and while adding a component. What can we do with the change of the **progress** value?
+<code>
+    $(document).on('changeParameter.cards', function(event, paramName, value) {
+        if (paramName == 'progress') {
+            initCircleProgress(event.target);
+        }
+    });
+</code>
+**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:
+<code>
+    $(document).on('delete.cards', function(event) {
+        $(event.target).find('.circle-progress').circleProgress('destroy');
+    });
+</code>
+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:
+<code>
+    $(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);
+        }
+    });
+</code>
+==== 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:
+<code>
+    $(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
+        });
+    });
+</code>
+==== changeParameter.cards Event ====
+It happens when a parameter is changed. Here is an example:
+<code>
+    $(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)
+        });
+    });
+</code>
+**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:
+<code>
+    $(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;
+                }
+            }
+        });
+    });
+</code>
+==== changeContent.cards Event ====
+Happens after editing of icons, images or videos. Example:
+<code>
+    $(function(){
+        $(document).on('changeContent.cards', function(event, type) {
+            // event.target - an edited item
+            // type - a type of an edited item
+        });
+    });
+</code>