Skip to content

Installation & Running

Jump to bottom
Douglas Parker edited this page Aug 11, 2017 · 6 revisions

TODO: This page is out-of-date to the point of meaninglessness. See the README for a more up-to-date version.

Installation

Uniform is installed as an NPM module. This is be done by running $ npm install uniform-validation --save in the project's working directory. This will install the language runtime under node_modules/uniform-validation.

Client-Side

To add the language interpreter to the client-side scripts, simply reference the compiled script from the HTML. This script is present in node_modules/uniform-validation/build/uniform.js. This location is likely not served, so it can by copied or symbolically linked to a directory which is served.

# Unix
# Assuming www/ is the root served directory
# Symlink Uniform library to www/lib/
$ ln -s node_modules/uniform-validation/build/uniform.js www/lib/uniform.js
rem Windows
rem Assuming www\ is the root served directory
rem Symlink Uniform library to www\lib\
> mklink www\lib\uniform.js node_modules\uniform-validation\build\uniform.js

Then source the language in the <head> tag of the page HTML and use Uniform's href() function to load the validation script for this particular page.

<head>
    <script src="lib/uniform.js"></script>
    <script>uniform.options.href("path/to/script.ufm");</script>
</head>

Form Submission

Form submission is handled the same way it is in standard HTML. Uniform will automatically check that its root-level valid tag is true, and if so, it will submit the data normally. Otherwise, Uniform will prevent the submission and display an error message.

In the example below, when the user clicks the "Submit" button, the system automatically checks if the form is valid (if the checkbox is checked). If the box is not checked, it will not submit anything to the server and instead display an error message. If the box is checked, Uniform will perform a POST request with the checkbox (along with any other inputs) to /submit.

HTML:

<form id="myForm" method="POST" action="/submit">
    <input name="chkBox" type="checkbox" />
    ...
    <button type="submit">Submit</button>
</form>

Uniform:

valid: chkBox equals true;

AJAX Submission

In single-page applications and often many other use cases, it becomes necessary to build an HTTP request directly in JavaScript and send it asynchronously without navigating the browser to a different page. To support this requirement, Uniform can be submitted as an AJAX request. This can be done using the uniform.submit.ajax() function.

var options = { method: "POST", url: "/submit" };

uniform.submit.ajax(options).then(function (res) {
    // Handle success
}, function (err) {
    // Handle error
});

The AJAX function is given an options object which should align to the format of the options in jQuery's $.ajax() call. Behind the scenes, all the uniform.submit.ajax() function does is replace the options.data value with Uniform data to submit, and then calls $.ajax() to send the request.

This does not check if a form is valid. This decision was made because AJAX requests are often built ad hoc for a particular kind of action which was probably hidden from the user and may not have any kind of <form> tag existing on the page to validate. Because of this, the uniform.submit.ajax() function does not check if anything is valid on the client. If the developer wanted such behavior, then he/she could simply check before sending the request like so:

if ($("#rootForm").ufm().valid()) {
    var options = { method: "POST", url: "/submit" };
    
    // Send AJAX request
    uniform.submit.ajax(options).then(function (res) {
        // Handle success
    }, function (err) {
        // Handle error
    });
} else {
    // Handle invalid form
}

It is considered a best practice to check the form for validity before submitting it, as it provides a better user experience for the client and allows them to fix the error more easily. However, in many scenarios it is not always practical to do so, therefore the client will have to depend on the server to notify it of any validation errors that have occurred.

Server-Side

Uniform is meant to be used as middleware for Express. To use Uniform server-side and validate inputs before accepting them, require the uniform-validation module and give it the path to a particular Uniform script to create a validator for it. Then use that validator as middleware for the Express route you wish to validate. The success callback will be invoked when the data is valid, while the error callback will be invoked if the data is invalid (or anything else goes wrong).

Note: The error callback must declare 4 arguments for Express to identify it as an error callback. Otherwise it may not be invoked correctly when invalid data is submitted.

// Require Express and Uniform
var express = require("express");
app = express();

var validator = require("uniform-validation");
var myValidator = validator("path/to/script.ufm");

// On POST request to /submit, validate input against path/to/script.ufm
app.post("/submit", myValidator, function (req, res) {
        res.end("Valid!"); // Submitted data was valid
    }, function (err, req, res, next) {
        res.end("Invalid!"); // Submitted data was invalid
    }
);
Clone this wiki locally