Getting started with Mobiscroll for jQuery

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

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/jquery/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.

Registering components

When using module loaders, components that we want to include in the project's bundle need to be registered. For example, if we wanted to use the eventcalendar calling $('selector').mobiscroll().eventcalendar(), we can do so only after registering the eventcalendar with the registerComponent function. This registration should be done only once.

How to register components

import $ from 'jquery';
import {
  registerComponent, // import the registerComponent function
  Eventcalendar, // import component classes that needed to be regitered
  Datepicker,
  Button,
  Checkbox,
} from '@mobiscroll/jquery';
import '@mobiscroll/jquery/dist/css/mobiscroll.min.css'

// register components for jQuery
registerComponent(Eventcalendar);
registerComponent(Datepicker);
registerComponent(Button);
registerComponent(Checkbox);

After doing the registration the initialization functions can be called through the jquery selectors like this:

$('#my-div').mobiscroll().eventcalendar({
  view: {
    schedule: {
      type: 'week'
    }
  },
  theme: 'ios',
});

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 jquery --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/jquery/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.

When using module loaders, components that we want to include in the project's bundle need to be registered as described in Registering components section above.

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 jQuery -->
<script src="jquery-2.2.2.min.js"></script>
<!-- Include Mobiscroll -->
<script src="js/mobiscroll.jquery.min.js"></script>
<link href="css/mobiscroll.jquery.min.css" rel="stylesheet" type="text/css">

Then you can use the initialization functions through jquery:

$(function() {
  $('#my-div').mobiscroll().eventcalendar({
    view: { schedule: { type: 'day' }},
  });
  $('#my-other-div').mobiscroll().datepicker({
    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:

$('#my-element').mobiscroll().button();

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

caution

When using an ESM bundles the auto-initialization will work only after registering the components.