appzio-node v0.0.2

Appzio JavaScript Library

This library brings Appzio's UI development technology to JavaScript developers that want to use the platform.

Developed with Node 9, it takes advantage of all the latest features of the JS ecosystem to provide a modern development workflow.

How does it work?

Even though this library enales a JS developer to create their own UIs and business logic it is not independent. Appzio's Node port works tightly coupled with the PHP core in order to provide access to the already established Appzio ecosystem, functionality and components.

Whenever a request is fired from the client it is always received by the PHP core. It then starts a series of operations to process the action. If the action you are currently developing is marked as a Note action, the Core will hand off the UI creation responsibility to JavaScript.

The connection itself is done using Redis. Our testing benchmarks proved that using a pub/sub to transmit data is the best solution for the development time that we had available. PHP will publish a configuration message to a channel on which the JavaScript library is subscribed and listening.

Here JS does its magic (we'll get to this later in the docs) and saves the response in a key in Redis. PHP then decodes the response saved in Redis and uses it to finalize the response.

Additional steps that are done on PHP's side is to traverse the whole layout and parse any External Components (will be explained later in the docs), handle images and other expensive operations that shouldn't be done by JavaScript or there is no need for reimplementation.

Architecture

The startup process of the JS library is a lot like what you will find in the PHP core. To summarize - it parses the configuration object that is passed to it and executes code based on that.

We will not go intro further details here for ideally you will never have to deal with this level of abstraction.

In order to create your first JS Appzio module/action you will need to use the init function which is exported by default.

This init function takes a single parameter which is an object containing references to the modules that you want to load. The value that is passed for each key - value pair is the actual module while the key is the identifier which will be used to fetch it.

Module Structure

There is no actual convention on the structure that your mode should have by generally you want it to export references to: 1. Controllers 2. Models 3. Views 4. Themes (Nested modules)

Controllers

Controllers are where you should handle your business logic handling. Like any traditional MVC, controllers will receive some data from the request and return a view by passing some data to it.

Models

Models should ideally be only concerned with data and database management. Each model that extends the base model provided by the library will have access to a number of useful methods for managing variables and session.

Views

The views are responsible for the generation of your layout. Probably most of your time will be spent in those files. Each view will have access to methods called header, scroll, footer, onload which allow the addition of components to the corresponding areas on the client screen. Each of those functions can take one or more components as arguments so you have complete freedom of how you structure your layout.

Components

The components are in the core of the platform and your goal as a developer using Appzio will be to compose a snappy and intuitive UI using components as building blocks.

In order to keep this core piece of functionality as simple os possible - most of the built in components are implemented using pure JavaScript functions.

You probably won't be implementing any core components but it's useful to know how it all works under the hood.

Each component uses the Component function. It is a higher order function that takes another function as an argument. Since all comp's are created more or less in the same way, Component takes care of the parsing and preparation logic and uses the function passed to it to apply the component specific logic.

For ease of use the core components are implemented using anonymous functions but feel free to use named ones if it would make your development and debugging easier.

Each component returns an object that has a type property (a string identifier), style_contents if any are specified and content depending on its type. Some components use arrays as content, some use strings.

const Text = Component(config =>
  Object.assign({}, { type: 'msg-plain' }, config))

The Text component implements a single change in its custom function - it specifies the type to signal the client that this is a simple text component.

The result of calling the Component function is then stored in the Text variable. It can now be called by using the arguments of the returned function by Component

const Component = fn => {
  return (content, params, styles) => {
    // ... parsing is done here

    return fn(config)
  }
}