Documentation

Mobirise

• Theme and components formatting

o Adjustment of a `params.json` file for a theme
o A component file structure
o Component settings (attributes)
• Expressions
• Parameters
o A section title
o A break line
o Text fields
o Checkboxes/Radio buttons
o A drop-down options list
o Color
o Range
o Font
o Image
o Video
o Background
o Map
o A hidden parameter
o Conditionals
• Templates
o The mbr-text directive
o The mbr-article directive
o The mbr-buttons directive
o The mbr-menu directive
o The <IMG> tag
o The mbr-icon directive
o The mbr-video directive
o The mbr-map directive
o The mbr-form directive
o The mbr-if directive
o The mbr-style directive
o The mbr-class directive
o Interpolation in attributes
• Tracing of component changes from custom scripts
o Recommendations for Use
 o Event add.cards
o Event delete.cards
o Event drag.cards
o Event changeParameter.cards
o Event changeContent.cards

Theme and components formatting

Adjustment of a `params.json` file for a theme

We add a `secondary` theme type:

{
"title": "TEST",
...
"theme": {
"type": "secondary",
...
}
}

A components list should be presented in this format:

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

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:
<input type="image" title="Image" name="bgImg" value="logo.png">

From a template:

<img src="logo.png" height="128" alt="Mobirise">

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:

<section
group="Menu"
plugins="DropDown, TouchSwipe"
always-top
global
not-draggable
position-absolute
></section>

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

<header>Section</header>

A break line

<hr/>

Text fields

<input type="text" title="Text" name="text" value="Default Text">

<textarea title="Textarea" name="text">Default Text</textarea>

Checkboxes/Radio buttons

<input type="checkbox" title="Show Title" name="showTitle" checked>

<input type="radio" title="Radio 1" name="radio" value="1">
<input type="radio" title="Radio 2" name="radio" value="2" checked>

A drop-down options list

<select title="Alignment" name="textAlign">

<option value="left">Left</option>
<option value="center" selected>Center</option>
<option value="right">Right</option>
</select>

It supports the inline attribute:

<select inline title="Alignment" name="textAlign">

<option value="left">Left</option>
<option value="center" selected>Center</option>
 <option value="right">Right</option>
</select>

Color

<input type="color" title="Background" name="bgColor" value="#ffffff">

Range

<input type="range" title="Font Size" name="fontSize" min="0.6" max="4" step="0.025"

value="0.625">

It supports the inline attribute:

<input type="range" inline title="Font Size" name="fontSize" min="0.6" max="4"

step="0.025" value="0.625">

Font

<input type="font" title="Font" name="font" value="Oswald">

Image

<input type="image" title="Image" name="bgImg" value="bg-image.png">

Video

<input type="video" title="Video" name="bgVideo"

value="http://www.youtube.com/watch?v=uNCr7NdOJgw">

Background

<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>

The parallax attribute for thefieldset 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 thename 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.

<input type="map" title="Map" name="googleMap">

A hidden parameter

<input type="hidden" name="hiddenParam" value="Lorem ipsum dolor sit amet.">

Conditionals

The condition attribute for parameters allows to control visibility depending on a condition.

<input type="color" title="Background" name="bgColor" value="#ffffff"

condition="backgroundType == 'color'">

Templates
The mbr-text directive

A simple text without an extended text editor.

<div mbr-text>Address...</div>

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.

<div mbr-article>
<p>Lorem ipsum dolor sit amet.</p>
...
</div>

The mbr-buttons directive

The element is interpreted as a buttons group.

<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>

The mbr-menu directive

An element is interpreted as a menu.

<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>

The <IMG> tag

An element is interpreted as an image automatically.

<img src="logo.png" height="128" alt="Mobirise">

or
<a href="#"><img src="logo.png" height="128" alt="Mobirise"></a>

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.

<span mbr-icon class="mbri-mobirise mbr-iconfont" style="font-size: 96px; color: rgb(255,

51, 102);"></span>

or

<a href="#"><span mbr-icon class="mbri-mobirise mbr-iconfont" style="font-size: 96px;

color: rgb(255, 51, 102);"></span></a>

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:

<div mbr-video>
<iframe src="http://www.youtube.com/watch?v=uNCr7NdOJgw"></iframe>
</div>
The mbr-map directive

A parameter name is used as an attribute value. Only one parameter type is supported: map.

<div class="google-map" mbr-map="googleMap"></div>

A map has several states:

Loading

<div class="google-map" mbr-map="googleMap" data-state="loading">

<div data-state-details></div>
</div>

Loading error (if a location is not found)

<div class="google-map" mbr-map="googleMap" data-state="not found">

<div data-state-details>Not found</div>
</div>

Map representation

<div class="google-map" mbr-map="googleMap">

<iframe>...</iframe>
</div>

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:

<form mbr-form class="mbr-form" action="[email protected]" method="post" name="My

Mobirise 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.

<div mbr-form>
<div data-form-alert hidden>
Thanks for filling out the form!
</div>
<form class="mbr-form" action="[email protected]" 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>

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.

<form name="My Mobirise Form" action="[email protected]" method="post">

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.

<input type="email" name="email" class="field" data-form-field="Email"

placeholder="Email" required>

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.

<label mbr-text class="form-label" for="phone">Phone</label>

<input type="tel" name="phone" class="form-control" data-form-field="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.

<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>

The mbr-if directive

It shows/hides a block depending on a condition:

<h1 mbr-if="showTitle">Header</h1>

or
<div mbr-if="showTitle || showText">
<h1 mbr-if="showTitle">Header</h1>
<div mbr-if="showText"></div>
</div>

The mbr-style directive

<section mbr-style="{'background-color': bgColor, 'background-image':

url(bgImg)}"></section>
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"

<span mbr-class="{'with-title': showTitle, 'with-text': showText}"></span>

<span class="with-title"></span>

or

<span mbr-class="blockType"></span>

<span class="flat"></span>

or

<span mbr-class="blockType == 'flat' ? 'flat-style' : '3d-style'"></span>

<span class="flat-style"></span>

or

<span mbr-class="[blockType, {'with-title': showTitle, 'with-text':

showText}]"></span>

<span class="flat with-title"></span>

Interpolation in attributes

Any attribute if it contains a syntactically correct expression inside double braces {{ ... }}
becomes active and changes dynamically by changing parameters.

<div title="color: {{bgColor}}"></div>

or
<div style="background: {{bgColor}}"></div>

or
<div data-video-src="{{bgVideo.url}}"></div>

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:

<input type="range" name="progress" min="0" max="100" step="1" value="50">

And a template:

<div class="circle-progress" data-progress="{{progress}}%"></div>

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
});
});

© Copyright 2017 Mobirise - All Rights Reserved