Creating an application

Where it all starts.

The application instance

Every Boyo Core application starts by creating a new application instance with the createApp function:

import { createApp } from '@boyojs/boyo-core';

const app = createApp({
    /* options */
});

The created instance contains the necessary methods to register components, plugins, directives... or to retrieve information about the app, like it's status (runnin or not), the prefix being used, the root element the app has been mounted on etc... .

The function accepts a single argument: the application options.

Application options

The application allows us to configure a few app-level options, for example defining the prefix to be used throughout the app.

Here's the list of all available options:

  • name (default: boyo:app): Name the instance being created. It can be usefull in certain situations when you have multiple apps, it'll allow you to differentiate between them.

  • prefix (default: o-): The token to be used to identify Boyo Core specifique attributes and when creating custom elements, the prefix to be used for their node name.

<span data-o-component="demo">...</span>
<data-o-demo>...</data-o-demo>

import { createApp } from '@boyojs/boyo-core';

const app = createApp({ prefix: 'data-o-' })
    .component('demo', () => {...})
    .customElement('demo', () => {...});
  • argument (default: :): The token to be used to identify a directive argument.
<span o-component="..." o-demo#arg-here="...">...</span>

import { createApp } from '@boyojs/boyo-core';

createApp({ argument: '#' }).directive('demo', () => {...});
  • modifier (default: .): The token to be used to identify directive modifiers.
<span o-component="..." o-demo&mod1&mod2="...">...</span>

import { createApp } from '@boyojs/boyo-core';

createApp({ modifier: '&' }).directive('demo', () => {...});
  • Lifecycle callbacks:
    • onMounting
    • onMounted
    • onRunning
    • onPaused
    • onUnpaused
    • onUnmounting
    • onUnmounted
    • onDestroying
    • onDestroyed

Conviniently, lifecycle callbacks can be passed as options, allowing you to hook into the mounting process of the app. The callback will receive one argument: the app itself.

import { createApp } from '@boyojs/boyo-core';

createApp({
    onMounting(app) {
        console.log(app.status()); // 'mounting'
    },
    onMounted(app) {
        console.log(app.status()); // 'mounted'
    },
    onRunning(app) {
        console.log(app.status()); // 'running'
    },
    // ...
}).mount();

Mounting the App

An application instance won't initialize anything until its .mount() method is called. The method takes an optional "root" element as argument, which can either be an actual DOM element or a selector string that will be passed directly into document.querySelector:

<div id="app"></div>

createApp().mount('#app');

If no argument is passed, the document.documentElement, which is the <html> element, will be used as the app's root element.

The .mount() method should always be called after all app configurations and asset registrations are done. Also note that its return value, unlike the asset registration methods, is the root element instead of the application instance.

Lifecycle events

Events on the document object will be dispatched every time there is a status change on an application.

The event dispatched will be an instance of CustomEvent and as it's .detail will be passed the app instance.

Here's a list of all the event names:

  • boyo:app:mounting
  • boyo:app:mounted
  • boyo:app:running
  • boyo:app:paused
  • boyo:app:unpaused
  • boyo:app:unmounting
  • boyo:app:unmounted
  • boyo:app:destroying
  • boyo:app:destroyed
document.addEventListener('boyo:app:mounting', ({ detail: app }) => {
    console.log(app.status()); // 'mounting'
});
document.addEventListener('boyo:app:mounted', ({ detail: app }) => {
    console.log(app.status()); // 'mounted'
});
document.addEventListener('boyo:app:running', ({ detail: app }) => {
    console.log(app.status()); // 'running'
});

// ...

Please note that the event names are independant of the given app name. Changing the app's name via its options will not change the events being dispatched.

The application properties and methods

The application exposes a few properties and methods for public use:

  • instances (static instances(): AppInstancesRegistry): Retrieve all the created and currently mounted app instances.
  • defaultOptions (static defaultOptions(): Required<AppOptions>): Retrieve the default options used for every app.
  • key (key(): string): Retrieve the app's uniquely generated key.
  • name (name(): string): Retrieve the app's given name.
  • options (options(): Required<AppOptions>): Retrieve the actual options used for the app.
  • prefix (prefix(value = ''): string): Retrieve the prefix used for the app. When an argument is passed, the returned value will be the argument prefixed with the app's configured prefix.
  • argument (argument(): string): Retrieve the argument used for the app.
  • modifier (modifier(): string): Retrieve the modifier used for the app.
  • root (root(): Element | null): Retrieve the root element onto which the app is mounted.
  • status (status(): AppStatus | null): Retrieve the current app status.
  • observer (observer(): DomObserver | null): Retrieve the custom DomObserver instance used by the app.
  • plugin (plugin(callback: PluginCallback): App): Register a plugin.
  • plugins (plugins(values: PluginCallback[]): App): Register multiple plugins in one go.
  • pluginRegistry (get pluginRegistry(): AppPluginsRegistry): Retrieve the plugin registry.
  • directive (directive(key: string, callback: DirectiveCallback): App): Register a directive.
  • directives (directives(values: Record<string, DirectiveCallback>): App): Register multiple directives in one go.
  • directiveRegistry (get directiveRegistry(): AppDirectivesRegistry): Retrieve the directive registry.
  • component (component(key: string, callback: ComponentCallback): App): Register a component.
  • components (components(values: Record<string, ComponentCallback>): App): Register multiple components in one go.
  • componentRegistry (get componentRegistry(): AppComponentsRegistry): Retrieve the component registry.
  • customElement (customElement(key: string, options: AppCustomElementRegistryOptions | ComponentCallback): App): Register a custom element.
  • customElements (customElements(values: Record<string, AppCustomElementRegistryOptions | ComponentCallback>): App): Register multiple custom elements in one go.
  • customElementRegistry (get customElementRegistry(): AppCustomElementsRegistry): Retrieve the custom element registry.
  • mount (mount(root?: null | string | Element): Element): Initiate the mounting process. Kick-starting the lifecycle of the app. The mounting process only happens if the instance has been newly created or if it had been previously unmounted.
  • pause (pause(): void): Pause a "mounted", "running" or "unpaused" app. Also pauses the observer, meaning no reaction will occur on any DOM update.
  • unpause (unpause(): void): Unpause a previously "paused" app.
  • unmount (unmount(): void): Unmount a previously "mounted", "running", "paused" or "unpaused" app.
  • destroy (destroy(): void): Completly "destroy" an app. While an unmounted app can be "re-mounted", a destroyed app cannot.

Multiple application instances

You are not limited to a single application instance on the same page. The createApp API allows multiple Boyo applications to co-exist on the same page, each with its own scope for configuration and global assets:

const app1 = createApp();
const app2 = createApp();

app1.mount('#app-1');
app2.mount('#app-2');