This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Tutorials

Show your user how to work through some end to end examples.

This is a placeholder page that shows you how to use this template site.

Tutorials are complete worked examples made up of multiple tasks that guide the user through a relatively simple but realistic scenario: building an application that uses some of your project’s features, for example. If you have already created some Examples for your project you can base Tutorials on them. This section is optional. However, remember that although you may not need this section at first, having tutorials can be useful to help your users engage with your example code, especially if there are aspects that need more explanation than you can easily provide in code comments.

1 - Authentication

A short tutorial that demonstrates how to use the built-in authentication system in alt-seven.

alt-seven authentication tutorial

In order to enable built-in authentication, you must configure your application with the correct options. Here is a sample of the authentication options to be passed to the framework:

	remote: {
		modules: app.remote,
		loginURL: "/api/auth/login",
		logoutURL: "/api/auth/logout",
		refreshURL: "api/auth/refresh"
	},

In addition to the authentication methods, the a7 model must be enabled for authentication to work. See the page on configuring your application to understand all the options available to you.

In the login form, the programmer can then specify success and failure parameters, which can be methods, event names, or router destinations. In the below example, the loginform sends the username and password and then specifies success and failure methods to run after the authentication method returns from the server.

handleClick: function(event) {
        let state = loginform.getState();
        loginform.showMessage("");
        a7.events.publish('auth.login', {
          username: loginform.state.username,
          password: loginform.state.password,
          success: function( json ){
            main.runApp();
		  },
          failure: function( json ){
            state.message = json.message;
            state.username = "";
            state.password = "";
            loginform.setState( state );
            loginform.fireEvent("mustRender");
		  }
        });
      }

Success and failure could also be specified as events, such as:

  success: "auth.loginSuccess",
  failure: "auth.loginFailure"

or as router destinations:

  success: "auth/loginSuccess",
  failure: "auth/loginFailure"

The programmer must then create the events or router destinations named:

  a7.events.subscribe( "auth.loginSuccess", function( obj ){
    // handle login success tasks 
  });

Note that routes are simply URL destinations that are mapped to events. The purpose of routes is to give the user a URL in the browser’s location bar.

Routes mapped in an application may look like this:

export var routes = [
	[ '/auth/loginSuccess', 'auth.loginSuccess' ],
	[ '/', 'main.home' ]
];

If routes are enabled in the application, the strings will be assumed to be route destinations, otherwise they will be treated as events.

2 - Configuring Your Application

A short tutorial that demonstrates how to configure your alt-seven application.

alt-seven configuration options tutorial

You configure your alt-seven application by passing an options structure to the a7.init method. There are a host of options that you can tailor to your needs.

The structure accepts these configuration options, listed with their data types and default values:

  • auth

    • sessionTimeout (milliseconds)

  • console

    • enabled (boolean, false)

    • wsServer (host, “”)

    • container (object, “”)

    • top (integer, 100)

    • left (integer, 500)

    • width (integer, 500)

    • height (integer, 300)

    • logging

      • logLevel (list (“ERROR,FATAL,INFO,TRACE,WARN”), “ERROR,FATAL,INFO”)
      • toBrowserConsole (boolean, false)

  • model (object, a7.model)

  • remote

    • modules ( structure, {})

  • router

    • useEvents (boolean, true)
    • routes ( object, undefined)

  • ui

    • renderer (string (Mustache, Handlebars, templateLiterals), templateLiterals )
    • timeout (milliseconds, 600000)

All options have a default value, so in the simplest example, you can call a7.init( {} );.