Introduction

In short

• x4js is a TypeScript framework.
• x4js is light: your application only ships the components it imports.
• x4js is designed for applications, in the browser or locally with Electron. You can build web sites with it, but that is not what it is made for.
• x4js is open source, under the MIT license.

Concept

The basic idea is that you do not manipulate HTML directly: you create objects that contain other objects. Code defines the structure of the elements (containers, menus…) and style, which is CSS, defines the appearance.

In x4js, every element derives from a base element, Component.

Its constructor takes a single, typed parameter that holds everything needed to create it. You will almost always use these two:

• cls: the CSS classes of the element, for example "my-class my-other-class";
• content: either child elements, or text.

In general, you define a class for the main page, then one class for each sub-page or dialog.

In practice, to create the header of a future application, you write:

import { Button, HBox, Icon, Label } from 'x4js';

// HBox is a horizontal container
const header = new HBox( {
  cls: "header-bar",    // this element gets the css class 'header-bar'
  content: [
    new Icon( { iconId: "var:app-icon" } ),
    new Label( { flex: 1, text: "My application" } ),  // a flex element fills the available space
    new Button( { label: "Menu" } ),
  ]
});

As you can see, no HTML. You focus on your application and not on a mix of HTML and JavaScript, and an editor such as VS Code assists you efficiently while typing, since everything is typed.

The components used here (Icon, Label and Button) come with x4js. There are more than fifty of them, enough to build a standard application. You can of course write your own, which is very simple.

The application

One special element is Application. It is a singleton: there is only one per application. To get going, you declare an application and give it its main view.

import { Application } from 'x4js';

const app = new Application( );
app.setMainView( header );

Events

Components, like the application, can be a source of events. Buttons, for example, fire a click event. These events are typed and known to the code editor.

To be notified when the header button is clicked, replace its creation with:

new Button( { label: "Menu", click: ( ) => this.onClick( ) } )

The onClick method is called on every click. You can of course define your own events.

Note

The application is an event source too: pages can subscribe to it and send messages that concern the whole application. See State and messages.

Properties

Components have a number of properties, set at construction and changed afterwards through their methods. To change the text of a label:

const status = new Label( { text: "Initial text" } );

status.setText( "New text" );

Note

A component is a persistent object: it is created once, then updated through its methods. Nothing is recomputed automatically. When you write a component, it is up to that component to update its display when one of its values changes, which is very simple to do.

Low-level access

When you write new components, being able to interact with the DOM is essential. Every component has a dom property, on which you can call all the standard methods. The component nevertheless provides many convenient wrappers, and a very simple mechanism to handle DOM events.

this.setAttribute( "tabindex", 0 );    // add the tabindex attribute
this.setWidth( 100 );          // change the size
this.addDOMEvent( "click", ( ev ) => this.onDOMClick( ev ) );

x4js also defines a few synthetic events, such as created, removed and resized, which are handy for dynamic components.

In application code this access remains the exception: component methods cover the common needs. It is mostly used to write your own controls, see Custom controls.

Tools

x4js offers a number of tools that are useful day to day:

• Point, Size, Rect and Color for geometry and colors;
• functions to extract or format dates;
• a translation manager, see Translation;
• tools to create and manipulate SVG;
• a drag and drop manager;
• named timers, available on every component.

The framework also gives access to styles, to read or change the content of the CSS, for example CSS variables.

Finally, you have the sources of everything: the package ships as TypeScript.

A few rules

Let us get the rules out of the way. There are very few, and it is better to follow them when developing with x4js.

1. An element never knows its parent. It notifies whoever owns it.
2. No cosmetics in code, as far as you can. Cosmetics have no place in code, that is the job of styles.
3. No hard-coded texts if you write components. You do not know which language they will be used in, and most software must be multilingual today. Save time, do it from the start: x4js has a native module for it.
4. No fighting with CSS. An element is not placed correctly, you need negative margins or !important? Check your CSS, the problem is not in the code.
5. Keep it simple. x4js has few concepts: components, state, events, data stores. Do not add an architecture on top until a real problem calls for it.

Next

• Getting started: create a project and run it.
• Interface design: split a screen into containers.