Forms

About

The form component adds styling to standard html form elements (textboxes, textareas, selects, checkboxes, radio buttons, submit buttons) giving them a native like look and feel on various platforms.

Initialization

Auto initialization

To auto-initialize the form elements, simply put the mbsc-form attribute on the container element. The form elements inside the container will be automatically intialized when the page is loaded.

<div id="myform" mbsc-form>
    <label>
        Username
        <input id="username" />
    </label>
    <label>
        Password
        <input id="password" type="password" />
    </label>
    <button type="submit">Sign In</button>
</div>

The initialization will use the default options. The defaults can be set in the mobiscroll.settings object, after the Mobiscroll scripts are loaded, but before the page load (document ready) event is fired, in order to have effect on the form initialization.

mobiscroll.settings = {
    theme: 'ios',
    lang: 'de'
};

If the form container is added later to the DOM, e.g. with an Ajax page load, a custom event named mbsc-enhance needs to be triggered in order to initialize the dynamically added content.
When the mbsc-enhance event is triggered on a DOM element, all form elements will be initialized inside all descendant elements with the mbsc-form attribute (including itself).

var xhr = new XMLHttpRequest();
xhr.onreadystatechange = function() {
    if (xhr.readyState == XMLHttpRequest.DONE) {
        var page = document.getElementByID('page');
        page.innerHTML = xhr.responseText;
        page.dispatchEvent(new Event('mbsc-enhance')); 
    }
}
xhr.open('GET', '/myform', true);
xhr.send();
    

Manual Initialization

The form can also initialized manually, just like any other Mobiscroll component.

<div id="myform">
    <label>
        Username
        <input id="username" />
    </label>
    <label>
        Password
        <input id="password" type="password" />
    </label>
    <button type="submit">Sign In</button>
</div>

mobiscroll.form('#myform', {
    theme: 'material'
});

If the form container is added later to the DOM, e.g. with an Ajax page load, call the initialization right after the content is appended in the DOM.

var xhr = new XMLHttpRequest();
xhr.onreadystatechange = function() {
    if (xhr.readyState == XMLHttpRequest.DONE) {
        var page = document.getElementByID('page'),

        page.innerHTML = xhr.responseText;

        mobiscroll.form('#myform', {
            theme: 'mobiscroll'
        });
    }
}
xhr.open('GET', '/myform', true);
xhr.send();

When elements are dynamically added to an already initialized form, call the refresh method to initialize the new elements.

mobiscrollInstance.refresh();

For many more examples - simple and complex use-cases - check out the forms demos for javascript.

Options

Events

mobiscroll.forms('#mobiscroll', {
    onInit: function (event, inst) {
    }
});

Methods

mobiscrollInstance.getInst();

mobiscrollInstance.option({
    display: 'bottom',
    lang: 'de'
});

mobiscrollInstance.refresh();

mobiscrollInstance.tap('#element', function () { alert("It's a tap!"); });

Localization

Validation

The Mobiscroll Forms component does not have built in validation mechanism, but provides error state stylings. Use the mbsc-err css class on the form element's container and the mbsc-err-msg css class on the error message:

<label class="mbsc-err">
    Username
    <input id="username" />
    <span class="mbsc-err-msg">Username is required.</span>
</label>
    

The above code sample makes a Mobiscroll input to show up as invalid. The text "Username is required" will be shown as the error message.

A functional Example

The following is a simple example on how to validate a login form using a functional approach. The validation requirements for each field are added with standard attributes like required, minlength and the type of the input field.

How it works: on the submit of the form loops over the form fields and validates each field. When a field is invalid, creates the error message element and adds the appropriate css classes to style it. Otherwise, if the field is valid and there is an error message in the markup, then removes it.

<form mbsc-form id="myForm">
    <div class="mbsc-form-group">
        <div class="mbsc-form-group-title">Sign In</div>
        <label>
            <input mbsc-input name="email" type="email" placeholder="Email" required>
        </label>
        <label>
            <input mbsc-input name="password" type="password" placeholder="Password" minlength="6" required>
        </label>
    </div>
    <div class="mbsc-form-group mbsc-btn-group-block">
        <button mbsc-button type="submit">Sign in</button>
    </div>
</form>

var form = document.getElementById("myForm");

form.noValidate = true; // disable HTML5 validation
form.onsubmit = validateForm; // validate form on submit

// loops through the form elements and validates each field
function validateForm(event) {
    event.preventDefault();
    var formValid = true;
    for (f = 0; f < form.elements.length; f++) {
        var field = form.elements[f],
            error = validateField(field);
        formValid = formValid && !error;
        if (error === null) {
            clearErrorState(field);
        } else {
            addErrorState(field, error);
        }
    }
    return formValid;
}

// checks if a field is valid, and returns the error message
function validateField(field) {
    var name = field.name.charAt(0).toUpperCase() + field.name.slice(1),
        firstError = null,
        errorMap = {
            'tooShort': ' is too short.',
            'typeMismatch': ' is invalid.',
            'valueMissing': ' is required.',
        };
    if (field.validity.valid) {
        return null;
    } else {
        for (var key in field.validity) {
            if (!firstError && key !== 'valid' && field.validity[key]) {
                firstError = key;
            }
        }
        var error = errorMap[firstError] ? errorMap[firstError] : ' is invalid.';
        return name + error;
    }
}

// clears a field of the error state and removes the error message
function clearErrorState(field) {
    var parent = field.parentNode,
        errorMsg = parent.querySelector('.mbsc-err-msg');

    parent.parentNode.classList.remove('mbsc-err');
    if (errorMsg) {
        parent.removeChild(errorMsg);
    }
}

// set the field as invalid and shows the error message
function addErrorState(field, message) {
    var parent = field.parentNode,
        errorMsg = parent.querySelector('.mbsc-err-msg');

    if (!errorMsg) {
        errorMsg = document.createElement('span');
        errorMsg.className = 'mbsc-err-msg';
        parent.appendChild(errorMsg);
    }
    errorMsg.innerHTML = message;
}

Groups

For styling the groups inside the form element you can use the mbsc-form-group, mbsc-form-group-title and mbsc-form-group-inset classes.

<div class="mbsc-form-group">
	<div class="mbsc-form-group-title">Phone</div>
	<label>
		Home
		<input type="tel" class="md-phone" placeholder="Phone" name="phone" value="+12225550127">
	</label>
	<label>
		Work
		<input type="tel" class="md-phone" placeholder="Phone" name="phone" value="+12225550128">
	</label>
</div>

<div class="mbsc-form-group-inset">
	<label>
		<input id="email" type="email" name="Email" placeholder="Email" />
	</label>
	<label>
		<input name="password" type="text" placeholder="Password" data-password-toggle="true" data-icon="none" data-icon-align="right" />
	</label>
</div>