UIZE JavaScript Framework

GUIDES Building Uize Powered Pages

1. Introduction

This document explains how to build your own UIZE-powered Web pages, with sophisticated user interactions.

BEFORE YOU START

This document assumes that you have already downloaded the UIZE JavaScript Framework, and followed the Getting Started With UIZE guide to set up the UIZE JavaScript Framework for use in your Web site project. You may also optionally read through the Overview of Features guide as a background to the topics that will be discussed in this document.

2. Anatomy of a Typical Page

2.1. Sourcing in JavaScript Modules

To start using the UIZE JavaScript Framework on a Web page, you'll want to load some of its JavaScript on the page.

At the very least, you'll want to load in the Uize.js file that defines the Uize base module for the framework and that implements a module loader mechanism that can dynamically load other modules required by your page.

There are three recommended places where you can include script tags for sourcing in UIZE JavaScript modules.

2.1.1. In the Head

It is safe and reliable to source in UIZE JavaScript modules in the head of the document.

EXAMPLE

<html>
<head>
  <title>My UIZE-enhanced Web Page</title>
  <link rel="stylesheet" type="text/css" href="css/site-theme.css"/>
  <script src="js/Uize.js"></script>
</head>
<body>
  ... ... ...
  ... ... ...
  ... ... ...
</body>

2.1.2. Start of Body

It is safe and reliable to source in UIZE JavaScript modules after the open body tag, and before any open tags for child nodes of the body that are layout elements.

EXAMPLE

<html>
<head>
  <title>My UIZE-enhanced Web Page</title>
  <link rel="stylesheet" type="text/css" href="css/site-theme.css"/>
</head>
<body>
  <script src="js/Uize.js"></script>
  ... ... ...
  ... ... ...
  ... ... ...
</body>

2.1.3. End of Body

It is safe and reliable to source in UIZE JavaScript modules at the bottom of the document's body, after the close tag for the last child node of the body that is a layout element.

EXAMPLE

<html>
<head>
  <title>My UIZE-enhanced Web Page</title>
  <link rel="stylesheet" type="text/css" href="css/site-theme.css"/>
</head>
<body>
  ... ... ...
  ... ... ...
  ... ... ...
  <script src="js/Uize.js"></script>
</body>

2.1.4. Earlier-in-the-document Pros & Cons

There are pros and cons to the earlier-in-the-document placements of the script tags for sourcing in JavaScript modules.

CON

The earlier in the document that you place the script tags, the longer it will typically take before the user sees any of the page render in the browser. This is because browsers handle loading external JavaScript files synchronously, meaning that the browser doesn't continue parsing the rest of the document until the entire external JavaScript file is loaded.

PRO

The earlier in the document that you place the script tags, the less time lag there will be between the user seeing the document and it becoming fully interactive. If you don't stall the rendering of the document until the JavaScript is loaded, the user will see the document and all the user interface controls that will become active once they are wired up by JavaScript code that will load later.

2.1.5. Splitting the Difference

You can use a hybrid approach to choosing where to source in external JavaScript files, in order to split the difference between the pros and cons of each.

If you want to get some of the benefits of sourcing in JavaScript earlier in the document and some of the benefits of sourcing them later in the document, you could choose to load in some "core" JavaScript files - that are shared by all pages in the site - early in the document (say, for example, in the head), and then load in the page specific JavaScript files further down in the document. Such an approach can help make it so that neither of those two critical delay periods is too perceptibly long for the user.

2.2. Page Widget Setup Code

2.2.1. Page Widget Example

EXAMPLE

<html>
<head>
  <title>My UIZE-enhanced Web Page</title>
  <link rel="stylesheet" type="text/css" href="css/site-theme.css"/>
  <script src="js/Uize.js"></script>
</head>
<body>
  ... ... ...
  ... ... ...
  ... ... ...
  <script type="text/javascript">
    Uize.require (
      [
        'Uize.Widget.Page',
        'Uize.Widget.Bar.Slider'
      ],
      function () {
        'use strict';

        /*** create the example page widget ***/
          var page = window.page = UizeSite.Page.Example ();

        /*** add the Uize.Widget.Bar.Slider child widget ***/
          page.addChild ('slider',Uize.Widget.Bar.Slider,{minValue:0,maxValue:200});

        /*** wire up the page widget ***/
          page.wireUi ();
      }
    );
  </script>
</body>

2.2.2. Only Need One Script Tag

Once you've sourced in the "Uize.js" file, you shouldn't need to source in any other JavaScript modules built on top of the UIZE JavaScript Framework using script tags, because the module loader mechanism will handle that for you, as long as your module declarations correctly require all the modules that will be used.

Taking another look at the page widget example shown earlier, the code inside the builder function of the module declaration can rely on the Uize.Widget.Page and Uize.Widget.Bar.Slider modules being loaded, even though there are no script tags in the document loading the external JavaScript files that define these modules. That's because the module loader mechanism implemented in the Uize base module - that was loaded in with the script tag - takes care of dynamically loading all modules declared in the required list of the module declaration (including all modules that are required by those modules), if they are not already loaded. This takes a load of your mind as a developer, because you don't have to worry about resolving all those complex dependencies across all the modules that your code uses.

For a more in-depth discussion of the module loader mechanism, you can consult the guide JavaScript Modules.