j2inn-app

FIN application framework

The core FIN application framework.

The types and components in this project are used to create a UI application that can integrate seamlessly as part of the FIN framework.

Concepts

The shell UI refers to the outer UI that renders an application's view...

-------------------------------Shell---------------------------------
| Header                                    | x |                   |
|      App launcher  /  Target selector     | x |  Sidebar target   |
|                                           | x |     selector      |
|-------------------------------------------| x |                   |
|                                           | x |                   |
|                           Sidebar apps -> | x |                   |
|                                           | x |                   |
|                                           | - |                   |
|                                           | x |                   |
|                                Dynamic -> | x |                   |
|                             sidebar apps  | x |    Sidebar app    |
|        Main app view                      | - |       view        |
|                                           | x |                   |
|                             Quicklinks -> | x |                   |
|                                           | x |                   |
|                                           |   |                   |
|                                           |   |                   |
|                                           |   |                   |
|                                           |   |                   |
---------------------------------------------------------------------

Main app views

• Application views are selected via the app launcher.
• Clicking an icon in the app launcher loads a new main app view.

Sidebar app views

• Sidebar app icons can be clicked on to load a sidebar app view.
• Dynamic sidebar apps can be added from a main app view. These sidebar apps only exist for the lifetime of the main app view.

Quicklinks

Quicklinks are also registered dynamicaly by a main app view. A quicklink can be any command a user want to invoke.

Targets

The server has a database of records. Each record has a unique id. For instance, there could be a record to represent a piece of equipment, a point or a site. Application views can work relative to a record. For an application a record's id is known as a target.

A target can be selected for a main application view via the target selector. Once a target has been selected, an application view can react to that target accordingly. For instance, a user loads a graphic and selects a boiler from the target selector. The graphic is using the information from the target (boiler) to display information. If the user then selects a different boiler, the graphic will then use that data to display its data.

A sidebar can also use the target from the target selector. A developer also has the option of allowing a user to select an alternative target via the sidebar target selector. This is useful for when a user wants to display some information about one thing on the left and then have something else on the right.

All target information can be accessed via the app root store...

const store = useAppRootStore()

// Current main target...
console.log(store.target)

// Current sidebar target...
console.log(store.targetSidebar)

Types

App

The core interface for an application. An application's views are used to render the application's UI in a shell.

As well as defined application views, a user can also define a store that can be used throughout the application to hold stateful information.

App View

An application has many views. An application view can show in the main or sidebar areas. Each application view has its own icon.

Any application views for main can also specify a category that provides a form of organizational grouping.

App Store

An application may need to share information between its different views. This can be down using an app store. An app store is declared on the app.

An application store can be accessed via the useAppStore() react hook. For example...

const store = useAppStore<MyAppStore>()

At J2 Innovations we use Mobx that enables mutations in our stores to automatically update our React based UI.

App Root Store

To access information regarding the shell UI and environment, a developer can use the application root store. This is accessed via the useAppRootStore() hook...

const store = useAppRootStore()

// Print out the currently selected target.
console.log(store.target)

UI Components

Several useful UI components are provided so application views can have a common look and feel.

AppMainViewHeader

This can be used in an application's main view to render a common header. Any child components are rendered in the view headers top left hand corner. Here's an example main application view that uses this view header...

return (
  <>
    <AppMainViewHeader {...props}>
      <TodoListCommands />
    </AppMainViewHeader>
    <TodoList />
  </>
)

By default, the view header will display the application's icon and name.

AppSidebarViewHeader

This can be used in an application's sidebar view to render a common header. This component can also render child components. The showTargetSelector boolean property can be used to additionally render the sidebar target selector.

return (
  <>
    <AppSidebarViewHeader {...props} showTargetSeletor={true}>
      <TodoListCommands />
    </AppSidebarViewHeader>
    <TodoList />
  </>
)

Please note, it's recommended the sidebar target selector should only be shown if the application developer wants the user to select a different target from the main one.

AppViewTabs

A useful way to render tags in an application's main view.