Getting started with Mobiscroll for JavaScript

Depending on the target project, the Mobiscroll library can be installed into:

1. A web application with module loaders (like webpack or similar app building tools)
2. Simple HTML web pages (with script and link tags)

For simple web pages the Mobiscroll CLI is not required and you can follow the install guide for web pages.

To install the Mobiscroll library to your web application, you will need the Mobiscroll CLI.

Install the CLI

Install the Mobiscroll CLI from NPM (you'll only have to do it once).

npm install -g @mobiscroll/cli

info

On Windows client computers, the execution of PowerShell scripts is disabled by default. When using Powershell, to be able to install the Mobiscroll CLI you will need to set the following execution policy:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Make sure to read the message displayed after executing the command and follow the instructions.

Starting with the trial

Start a free trial by entering your email address on the Mobiscroll homepage and create your account. When asked, enter your first name, set a password and you're ready to go!

This is how the free trial works:

1. You can try Mobiscroll for free.
2. The trial needs an active connection to Mobiscroll servers for validation. Don't worry, the licensed product will work offline with downloadable resource files. Read about the differences between trial and licensed products.
3. You can upgrade to the licensed product at any time during or after your trial.

Installing a trial package

To install the Mobiscroll Trial, you will need to open a terminal window in the root folder of you project and run the following command:

mobiscroll config javascript --trial

Installing from NPM

To install the Mobiscroll library from NPM, you will need to open a terminal window in the root folder of you project and run the following command:

mobiscroll config javascript

info

If you're working behind a proxy, additional configuration might be needed. Please check the proxy configuration options of the CLI.

info

The package will be installed from a private npm registry, which requires authentication. If your project uses a CI/CD workflow, read this guide on how to make it work.

For the components to work, you will also need to import the css file of the installed library under the node_modules folder (at @mobiscroll/javascript/dist/css/mobiscroll.min.css).

If you are using SCSS, you will also find a full and a modular .scss file in the same directory.

Installing a downloaded package

A downloaded package can be installed into a webapp with module loaders as well as a simple web page by including the code into the html.

On the download page a custom package can be built by picking only the components, themes, languages and additional modules you need.

When building your package, select the required components and other resources, then hit the download button.

1. Copy Mobiscroll into your app

Extract the zip file you just downloaded, then grab the js, src and css folders and copy it into src/lib/mobiscroll folder of your JavaScript app. If there is no such folder available, you can create it.

2. Run the config command

Run the config command in the root folder of your app in a terminal window.

mobiscroll config javascript --no-npm

For the components to work, you will also need to import the css file of the installed library under the node_modules folder (at @mobiscroll/javascript/dist/css/mobiscroll.min.css).

If you are using SCSS, you will also find a full and a modular .scss file in the same directory.

Web pages

To include a downloaded package to a simple website, unzip the contents of the downloaded zip file. Copy the css and js folders to your project, next to your html file. A script and a stylesheet will need to be included into the html like this:

Your html file, for example index.html

<!-- Include Mobiscroll -->
<script src="js/mobiscroll.javascript.min.js"></script>
<link href="css/mobiscroll.javascript.min.css" rel="stylesheet" type="text/css">

Then you can use the initialization functions from the mobiscroll namespace:

mobiscroll.eventcalendar('#my-div', {
  view: { schedule: { type: 'day' }},
});

mobiscroll.datepicker('#my-other-div', {
  select: 'range',
});

ESM Bundle

With every Mobiscroll package we provide an ESM bundle, so it can be used as a JavaScript Module. This way many bundlers (for example Rollup, Webpack, etc...) can take advantage of the tree-shaking technique and eliminate dead code. This reduces the bundle size to only what is actually used in the application.

The ESM bundles are under the esm5 folder of the package.

The Mobiscrol ESM bundle has all the components the regular bundle has, but it omits a few setup steps in order to be tree-shakeable. One of these steps is the registering of components, that needs to be done manually for the auto-initialization to work.

Manual vs Auto initialization

All of the Mobiscroll components can be initialized manually using their initialization functions:

import { button } from '.\esm5\mobiscroll.javascript.min.js'; // import the button initialization function
button('#my-element'); // initialize a button on the element with id 'my-element'

Some Mobiscroll components can also be initialized using a html attribute that automatically initializes the component:

<button id="my-element" mbsc-button onclick="myOnClickFunction();"></button>
<!-- the mbsc-button attribute is used to auto-initialize the button component -->

Registering components

In ESM bundles, for the auto-initialization to work, the components will need to be registered. This registration can be done using the registerComponent function.

Manually initializing components will work the same way in both regular and esm bundles.

import {
  registerComponent, // import the registerComponent function used to register the components for auto-initialization
  Button, // import component classes that needed to be regitered
  Checkbox,
  Segmented,
  SegmentedGroup
} from '.\esm5\mobiscroll.javascript.min.js';

// register components for auto-initialization
registerComponent(Button);
registerComponent(Checkbox);
registerComponent(Segmented);
registerComponent(SegmentedGroup);