Builtins

Here we cover some of built-in components.

Most of them are optional, so they might be deleted from your project if you are non planning on using them.

Utils

This is the only required component, as some internal logic depends on it.

Utils class is built mostly on model-like principle. However, its log method causes side-effects as it writes to the console, so you cannot really call it a model. It implements some of very useful utilities to be used across the entire application:

• log(text: string, type: LogType = LogType.INFO): - A beautiful logging function for writing formatted output to the console. It has 5 logging modes:
  • INFO (default) - Just a casual informational log to the console
  • OK - Is used to identify a successful operation
  • WARNING - Shows that something might have gone wrong, and you should take a look on it
  • EROOR - Useful for printing all kinds of errors an exceptions
  • DIVIDER - A big '=' string, with optional title text
• format(string: string, ...args: string[]) - Formates string using placeholders. Example: hello {0}! to hello world!, where world is your argument.
• generateID() - An utility to generate universaly unique ids.
• convertTo(proto: any, data: any) - Returns data converted to a given prototype. With respect to object prototypes, array types and primitive types. Supports JSON conversions. If proto is undefined the data returns unchanged. Used in bind decorator.
• sleep(ms: number) - A promise based delay function which is a wrapper over native setTimeout.

Offliner

An optional browser-only controller.

With a few lines of code and a help from workbox webpack plugin. It makes your application work offline like a true PWA!

Hasher

An optional browser-only controller.

Helps you manage data stored in the URL's hash string. It uses the format: key:value,second_key:second_value ....

Public interface:

• initialize(defaults: Record<string, string> = {}) - Component initialization. Accepts default values as initial configuration.
• get(property: string) - Returns the value of a hash property.
• set(property: string, value: any, stateless: boolean = false) - Sets the value of a hash property. stateless defines should a state update not be pushed to the history after the set is completed (defaults to false).
• exists(property: string) - Checks whether a property exists.
• freeze(frozen: boolean = true) - Disallows any changes to hash until it is unfrozen.
• properties - An object containing all the current properties stored in hash.
• hash - Raw hash data (without any routing paths).

Events:

• loaded - Emits when hash is loaded and all the defaults were applied. Gives you properties as an event argument.
• changed - Emits when any value in hash changes. Gives you properties as an event argument.

Tabber

An optional browser-only controller.

Lets you create tabs with ease. To use it you just need to define tab names and the default tab (optional):

div(controller="tabber")
    div(tab="page1" default)
    div(tab="page2")
    div(tab="page3")

Now you can change them with an exposed change function:

tabber.change("page2");
tabber.change("page3");

Or with ctrl shortcut:

div(controller="tabber")
    div(tab="page1")
    div(tab="page2")
    div(tab="page3")
    button(onclick="ctrl.change('page1')") Go to 1
    button(onclick="ctrl.change('page2')") Go to 2
    button(onclick="ctrl.change('page3')") Go to 3

Only the selected tab is rendered, the rest have display: none CSS property.

If you specify false as an initialization argument, tabs will not be hidden on the app load.

Events:

• changed - Emits when a tab was changed. Gives you a name of the new tab as an event argument.

Router

An optional browser-only controller.

Allows you to create client-side routes for your application right in the layout:

div(route="home" default)      //- `/` or `/home`
div(route="feed")              //- `/feed`
    div(route="posts" default) //- `/feed` or `/feed/posts`
    div(route="news")          //- `/feed/news`
div(route="settings")          //- `/settings`
    div(route="profile")       //- `/settings/profile`
    div(route="404")           //- when no other route found in `/settings/*`, like `/settings/picture`, `/settings/profile/my`
div(route="404")               //- when no other route found, like: `/nothing`, `/feed/my`

Router has a special default attribute and route="404" features. Their behavior is quite intuitive if you look at the code above. Moreover, you can use some special pattern characters:

• . - Any part of a route. Like for /home/.: /home/test or /home/anything are valid routes, but not /home or /home/test/something.
• ? - Any part of a route that might not even exist. Similar to the example above, but /home is valid in this case.
• + - Any count of a route parts more than 0. For /home/+: /home/test/something or /home/a/b/c/d - valid, but not /home
• * - Any count of a route parts. Similar to the example above, but /home is valid in this case.

Keep in mind that when the router encounters + or * it stops parsing the route. So /home/anything/one is valid for /home/*/two and /home/+/two.

You can specify a subtitle for each route:

title MySite                                   //- The main title of your site
div(route="home")                              //- MySite
div(route="feed" subtitle="Feed")              //- MySite - Feed
    div(route="posts" subtitle="Feed (posts)") //- MySite - Feed (posts)
    div(route="news")                          //- MySite - Feed
div(route="404" subtitle="Not Found")          //- MySite - Not Found

As you see, the default title pattern is {0} - {1}, where {0} is your main title and {1} is a route's subtitle. The pattern could be changed on initialization or with titleFormat property. titleFormat is processed with Utils.format function

Public interface:

• initialize(defaultPath?: string, titleFormat?: string) - Component initialization. Accepts a default path (a redirect from "/" page) and a custom title format.
• navigate(path: string, stateless: boolean = false) - Navigates to a specified path (hash data is not modified in this process). stateless defines should a state update not be pushed to the history after the navigation (defaults to false). This method is exposed.
• path - Current router path.
• titleFormat - Format string for titles.