Sample 0

Getting the library set up

This tutorial will cover:
  1. Prerequisites:
  2. Where to download TypeScript UI (TSUI for short)
  3. How to create or update a new or existing project
  4. Creating an app
  5. Where to find the sample apps
  6. Library structure / What the library contains
  7. Where to find documentation

1. Prerequisites

TypeScript UI requires a few tools before you can begin:
  1. Node.js - Required for NPM
  2. NPM - Required to UglifyJS2 & Typescript
  3. UglifyJS2 - Required for minification
  4. TypeScript - Required for compiling TypeScript
    1. Either install the NPM package,
    2. Or if you are using Visual Studio, install the Visual Studio extension.

2. Downloading TypeScript UI

To download the latest version of TypeScript UI:
  1. Go to the Downloads tab at the top of the page. The latest recommended release is automatically selected, or you can download the latest dev release.
  2. Download the TypeScript UI [Version] ZIP file (usually the Recommended Download)
  3. Download the TypeScript UI Updater [Version] associated with the release.

3. How to create or update a new or existing project

Note:
  • This process will not delete any existing files in the folder.
    • Except if a folder by the same name of TypeScript UI [Version] exists.
  • Using Update excludes any library files/folder with "/Apps/" in the path so, for example, modifications to MyApp.ts will not be lost.

To create or update a new or existing project:
  1. Put the TypeScript UI [Version] ZIP file in the top-level folder of where you want your project to be (usually where the Index.html file will be)
  2. Unzip the TypeScript UI Updater [Version]
  3. Run the TypeScript UI [Version] EXE file that you just unzipped.
    1. When the program loads it will take a moment to look up what the latest recommended version of TypeScript UI is and tell you.
  4. Select the folder for your project as Destination
  5. Select the TypeScript UI [Version] ZIP file as the version to use.
  6. Click Create to create a new project or Update to update an existing project.

4. Creating an app

Note: If you used the Create option above you will already have an app called MyApp set up and ready to use. The app's TypeScript file can be found in Scripts\TS\Apps\MyApp.ts

Creating an app is quick and easy, but this tutorial also aims to explain the process. So, two sets of instructions are provided below:
Quick Steps
To quickly create a new app, follow these steps:
  • Create the following folders\empty files _(replace App1 with the name of your app):
    • App1.html
    • CSS\Apps\App1.css
    • Scripts\TS\Apps\App1.ts
    • Scripts\TS\Apps\Starters\App1Starter.ts
  • Add the following HTML to App1.html (replace App1 in the HTML with the name of your app):
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" class="no-js">
<head runat="server">
    <title>TypeScript UI</title>
    
    <link href="CSS/UI.css" rel="stylesheet" type="text/css"/>
    <link href="CSS/Skins/Blue.css" rel="stylesheet" type="text/css"/>
    <link href="CSS/Apps/MyApp.css" rel="stylesheet" />
    
    <script src="Scripts/JS/jQuery/jquery-2.0.1.min.js"></script>
    <script src="Scripts/JS/jQuery/jquery-ui-1.10.3.custom.min.js"></script>
    
    <script src="Scripts/TS/Lib/TypescriptUI.js"></script>
    <script src="Scripts/TS/Apps/App1.js" type="text/javascript"></script>

    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0"/>
    <meta name="apple-mobile-web-app-capable" content="yes" />
</head>
<body>
    <script src="Scripts/TS/Apps/Starters/App1Starter.js" type="text/javascript"></script>
    
    <div class="NoJSMessage">
        <p>
            This page runs as a web app designed for HTML5/CSS3. Please make sure you have JavaScript enabled and are using any of the following browsers:
        </p>
        <ul>
            <li>Google Chrome</li>
            <li>Microsoft Internet Explorer (9 or above)</li>
            <li>Mozilla Firefox</li>
            <li>Opera</li>
            <li>Safari (PC or Mac)</li>
        </ul>
        <p>For mobile access please use any of the following:</p>
        <ul>
            <li>Android : Default / Chrome / Firefox / Boat Browser / Dolphin / UC Browser</li>
            <li>iPhone / iPad / iPod : Defailt browser or Chrome</li>
        </ul>
    </div>
</body>
</html>
  • Add the following CSS to App1.css
/* CSS for your app will go in this file. All required CSS in already in the libraries' UI.css */
  • Add the following TypeScript to App1.ts
    • Replace App1 with the name of your app
    • Replace OrganisationName with the name of your organisation (or your name if you are an individual)
/// <reference path="../Lib/Build/IApp.d.ts" />
/// <reference path="../Lib/Build/Animation/AnimationRefs.d.ts" />
/// <reference path="../Lib/Build/UI/UIRefs.d.ts" />
/// <reference path="../Definitions/jquery.d.ts" />

module OrganisationName
{
    export class App1 implements IApp
    {
        private MainContainer: JQuery = null;
        private StartArgs: string[] = null;

        Run(args: string[] = [], container: JQuery = $("body")): void
        {
            this.StartArgs = args;
            this.MainContainer = container;

            this.MainContainer.addClass("App1");

            console.log("App1 loaded.");
        }
    }
}
  • Add the following TypeScript to App1Starter.ts
    • Replace App1 with the name of your app
    • Replace OrganisationName with the name of your organisation (or your name if you are an individual)
/// <reference path="../App1.ts" />
/// <reference path="../../Definitions/jquery.d.ts" />

var TheApp = null;
$(function ()
{
    TheApp = new OrganisationName.App1();
    TheApp.Run();
});
  • Edit Scripts\TS\Apps\Build_Apps.bat with Notepad
Replace the line:
CALL tsc "MyApp.ts" "DemoApp.ts"
With:
CALL tsc "MyApp.ts" "DemoApp.ts" "App1.ts"
Add the following line before the echo Build complete.
CALL uglifyjs -o "App1.min.js" "App1.js"
  • Done! - This has set up your first app and the build process.
    • To build your app, open a command prompt in the Apps directory and run "Build_Apps.bat".
    • To view your app, open App1.html

Explained Steps
1. Creating the required files
TypeScript UI has a standard structure for creating apps that maintains order for even large numbers of apps. Each app has 3 basic files and 1 optional file:
  1. AppName.css - The CSS file for the app which contains all the CSS associated with thr app and only that app.
  2. AppName.ts - The TypeScript file for the app - contains all the main TypeScript for the app.
  3. AppNameStarter.ts - The basic app starter - contains the TypeScript for initialising the app in a page.
  4. Optional : AppName.html - This optional HTML page is the app's HTML page.
    1. This can be omitted if you are using, for example, a server with dynamically generated pages. However, the generated pages must contain at least the same HTML as the sample shown below.
These files are placed in relevant folders:
  1. AppName.html - Create this in the top-level directory of your app's project.
  2. AppName.css - Create this in the CSS\ folder of your app's project.
  3. AppName.ts - Create this in the Scripts\TS\Apps\ folder of your app's project.
  4. AppNameStarter.ts - Create this in the Scripts\TS\Apps\Starters\ folder of your app's project.
Using this structure you can easily find all the different components of your app.

Create the files as specified above before continuing

What is an app
An app in the context of TypeScript UI is a class which implements IApp. It has a Run method which takes two arguments:
  • args - A list of parameters (that you choose) to start your app with. This can allow different app starters to pass different arguments to customise how the app runs.
  • container - The jQuery wrapper object of the DOM element your app should be contained within. Usually this is the body element.
What is an app starter
An app starter is used to load your app when the page loads. Having multiple apps starters for the same app can be useful if you want to write one app but customise how it runs for different pages. Using different app starters (which pass different args values) on different pages can achieve this.

2. Adding HTML to AppName.html
TypeScript UI has developed a standard format for app pages. The format ensures that:
  • Users who do not have a compatible browser receive a relevant error message even if the library fails to load.
  • All apps have a standard grey background that is obviously a background and not the app - this is helpful for debugging and is also obvious to users if the app fails to load.
TypeScript UI also includes some other libraries for things such as detecting mobile browsers and CSS3 support.

The standard HTML for an app is:
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" class="no-js">
<head runat="server">
    <title>TypeScript UI</title>
    
    <link href="CSS/UI.css" rel="stylesheet" type="text/css"/>
    <link href="CSS/Skins/Blue.css" rel="stylesheet" type="text/css"/>
    <link href="CSS/Apps/MyApp.css" rel="stylesheet" />
    
    <script src="Scripts/JS/jQuery/jquery-2.0.1.min.js"></script>
    <script src="Scripts/JS/jQuery/jquery-ui-1.10.3.custom.min.js"></script>
    
    <script src="Scripts/TS/Lib/TypescriptUI.js"></script>
    <script src="Scripts/TS/Apps/App1.js" type="text/javascript"></script>

    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0"/>
    <meta name="apple-mobile-web-app-capable" content="yes" />
</head>
<body>
    <script src="Scripts/TS/Apps/Starters/App1Starter.js" type="text/javascript"></script>
    
    <div class="NoJSMessage">
        <p>
            This page runs as a web app designed for HTML5/CSS3. Please make sure you have JavaScript enabled and are using any of the following browsers:
        </p>
        <ul>
            <li>Google Chrome</li>
            <li>Microsoft Internet Explorer (9 or above)</li>
            <li>Mozilla Firefox</li>
            <li>Opera</li>
            <li>Safari (PC or Mac)</li>
        </ul>
        <p>For mobile access please use any of the following:</p>
        <ul>
            <li>Android : Default / Chrome / Firefox / Boat Browser / Dolphin / UC Browser</li>
            <li>iPhone / iPad / iPod : Defailt browser or Chrome</li>
        </ul>
    </div>
</body>
</html>

Add this HTML to your AppName.html file
  • You should replace App1.js with AppName.js
  • You should replace App1Starter.js with AppNameStarter.js

3. Adding CSS to AppName.css
There is none to add! All of the CSS for standard apps & styling is in the libraries UI.css so by default you don't need to add any CSS to your AppName.css file.

4. Adding TypeScript to AppName.ts
AppName.ts will contain all the main logic for your app. At a minimum it contains:
  • 4 references to the main TSUI library files
  • Exported app class that implements the IApp interface. The app class should/must also contain:
    • MainContainer - The main container element for the app.
    • StartArgs - The string array of arguments passed to the app when it started.
    • Run method implementation
Add the following TypeScript to your AppName.ts file:
/// <reference path="../Lib/Build/IApp.d.ts" />
/// <reference path="../Lib/Build/Animation/AnimationRefs.d.ts" />
/// <reference path="../Lib/Build/UI/UIRefs.d.ts" />
/// <reference path="../Definitions/jquery.d.ts" />

module OrganisationName
{
    export class App1 implements IApp
    {
        private MainContainer: JQuery = null;
        private StartArgs: string[] = null;

        Run(args: string[] = [], container: JQuery = $("body")): void
        {
            this.StartArgs = args;
            this.MainContainer = container;

            this.MainContainer.addClass("App1");

            console.log("App1 loaded.");
        }
    }
}
  • You should replace App1 with the name of your app
  • You should replace OrganisationName with the name of your organisation (or your name if you are an individual)
5. Adding TypeScript to AppNameStarter.ts
AppNameStarter.ts will contain the default app starter code for your app. Currently, this is a function which runs when the page is ready and creates a new instance of your app and finally calls the Run method. The default container used is the body element.

Add the following TypeScript to AppNameStarter.ts
/// <reference path="../App1.ts" />
/// <reference path="../../Definitions/jquery.d.ts" />

var TheApp = null;
$(function ()
{
    TheApp = new OrganisationName.App1();
    TheApp.Run();
});
  • You should replace App1 with the name of your app
6. Setting up the build process
TypeScript UI has batch scripts to do the following build steps:
  1. Compiling TypeScript to JavaScript (uses TS compiler)
  2. Minify JavaScript files (uses UglifyJS2)
To add your new app to the build process, follow these steps:
  • Edit Scripts\TS\Apps\Build_Apps.bat with Notepad
Replace the line:
CALL tsc "MyApp.ts" "DemoApp.ts"
With:
CALL tsc "MyApp.ts" "DemoApp.ts" "AppName.ts"
Add the following line before the echo Build complete.
CALL uglifyjs -o "AppName.min.js" "AppName.js"
  • You should replace AppName with the name of your app
  • Done! - This has set up your first app and the build process.
    • To build your app, open a command prompt in the Apps directory and run "Build_Apps.bat".
    • To view your app, open App1.html

5. Where to find sample apps

All the sample apps (including the one for this tutorial - Sample 0) are added to your project when you create it. They can be found in Scripts\TS\Sample Apps\. The help navigate them more easily there is a Sample Apps.html page which links to all the sample apps and gives brief descriptions of each of them.

6. Library Structure / What it contains

The library is structured so that each conceptually different area has its own module. A full and up-to-date list of modules can be found on the main Documentation page. At the time of writing the modules were:
  • TSUI.Animation - Animation code including jQuery animators and canvas animation.
  • TSUI.Apps - App structure code.
  • TSUI.Collections - Collections code including things such as a generic List implementation.
  • TSUI.Data - Data handling code (primarily Data Binding code).
  • TSUI.Events - TSUI's custom event system. Includes all events, event handlers and event args implementations.
  • TSUI.Exceptions - TSUI's custom exceptions system.
  • TSUI.Logging - TSUI's custom debug/exception logging system including Logger implementation. Outputs stuff to browser's built in console.
  • TSUI.UI - The main UI code. Contains all interfaces and classes for all controls.

7. Where to find Documentation

All documentation can be found from the Documentation tab at the top of the page (which is no doubt how you found this tutorial). Technical is structured by module and links can be found further down the Documentation page/.

Last edited Sep 8, 2013 at 1:30 PM by EdwardNutting, version 1

Comments

No comments yet.