DEV Community: CraftkitJS

Template for making package namespace - craftkit code pattern

CraftkitJS — Fri, 27 Nov 2020 14:52:23 +0000

In craftkit application, modules can be also used in HTML context. To avoid conflict of module name, you would like to define your package namespace.

This post illustrates key snippet about namespace, using implementation of your own package under the Craft.Widget namespace.

Steps

Define package namespace Craft.Widget.Example
Implement Craft.Widget.Example.View as a subclass of Craft.UI.View
Place the View on the screen
Overview, defining your own top level namespace

Files

Craft.Widget.Example/
├── package.json
├── index.js
├── index.min.js
├── main.js
├── View.js
├── webpack.config.js
└── index.html

package.json

This is minimum version of package.json with craftkit.

{
  "name": "Craft.Widget.Example",
  "description": "",
  "version": "0.1.0",
  "dependencies": {
    "@craftkit/craft-uikit": "^3.1.4"
  },
  "devDependencies": {}
}

index.js

The entry point of Node.js module.

'use strict';

const Example = require('./main.js');

module.exports = Example.default || Example;

index.min.js

The entry point of HTML context. The namespace should be injected into the window object. This is done by Craft.usePackage function, and callbacked by it inject function. (When you define your own top level namespace, you should also define those functions to inject packages under the namespace. See the bottom of this post.)

'use strict';

const Example = require('./main.js');

window.Craft.usePackage(Example.default);

module.exports = Example.default || Example;

main.js

Both Node.js and HTML context enter to this script at first.

To be able to make another packages join to this namespace, you should define inject function to the exporting object.

import { View } from './View.js';

const Packages = {
    View : View
};

Packages.inject = function(Craft){
    Craft.Widget = Craft.Widget || {};
    if( !Craft.Widget.Example ){
        Craft.Widget.Example = Packages;
    }
};

export default Packages;

View.js

Main logic of this package.

This class will be accessible by Craft.Widget.Example.View.

import * as Craft from '@craftkit/craft-uikit';

export class View extends Craft.UI.View {
    template(componentId){
        return `
            <div class="root">
                This is Example
            </div>
        `;
    }
}

webpack.config.js

Write out package for HTML context.

var path = require('path');

module.exports = {
    mode: 'development',
    entry: './index.min.js',
    output: {
        path: path.resolve(__dirname,'./'),
        filename: 'craft-widget-example.min.js',
        library: 'Example',
        libraryTarget: 'window',
        globalObject: 'window'
    },
    externals: {
        '@craftkit/craft-uikit' : 'Craft',
    }
};

index.html

HTML use case.

<html>
<head>
    <meta name="viewport" content="width=device-width, height=device-height, initial-scale=1.0, viewport-fit=cover"/>

    <script src="https://unpkg.com/@craftkit/craft-uikit/dist/craft-uikit.min.js"></script>

    <script src="./craft-widget-example.min.js"></script>

    <script>
        window.onload = function(){
            Craft.Core.Bootstrap.boot({
                didBootApplication : function(options){
                    Craft.Core.Defaults.ALLOW_COMPONENT_SHORTCUT = true;
                    var rootViewController = new Craft.UI.DefaultRootViewController()
                    Craft.Core.Context.setRootViewController(rootViewController)

                    rootViewController.appendView(
                        new Craft.Widget.Example.View()
                    );
                }
            });
        };
    </script>
</head>
<body id="CraftRoot">
</body>
</html>

Run

webpack --config webpack.config.js

Then open ./index.html by browser.

Node.js context

In Node.js context, namespace is controlled under its rules.

To use full package name, call Craft.usePackage for your package.

import * as Craft from '@craftkit/craft-uikit';
import * as Example from './craft-widget-example';
Craft.usePackage(Example);

class MyPage extends Craft.UI.View {
    viewDidLoad(callback){
        this.appendView(new Craft.Widget.Example.View());
    }
}

Define your own namespace

When you define your own top level namespace, like MyCompany.MyApp.Example, you may define something like this:

MyCompany/main.js

const MyCompany = {};

MyCompany.usePackage = function(packages){
    packages.inject(MyCompany);
};

export default MyCompany;

MyCompany.MyApp.Example/main.js

import { View } from './View.js';

MyCompany.MyApp = {
    View : View
};

Packages.inject = function(MyCompany){
    MyCompany.MyApp = MyCompany.MyApp || {};
    if( !MyCompany.MyApp.Example ){
        MyCompany.MyApp.Example = Packages;
    }
};

export default MyCompany;

index.min.js

'use strict';

const Example = require('./main.js');

window.MyCompany.usePackage(Example.default);

module.exports = Example.default || Example;

index.html

rootViewController.appendView(new MyCompany.Widget.Example.View());

YourApp.js

import * as MyCompany from '/mycompany';
import * as Example from './mycompany-myapp-example';
MyCompany.usePackage(Example);

class MyPage extends Craft.UI.View {
    viewDidLoad(callback){
        this.appendView(new MyCompany.MyApp.Example.View());
    }
}

How to identify your view instance by its packagename

CraftkitJS — Wed, 18 Nov 2020 08:23:13 +0000

Instance of Craft.UI.View is placed on the DOM-tree with unique ID,
and it is registered in the window object. The ID is used for instance method call.

Instance ID is always identical. But to be able to identify your instance by its ID expression, you can use packagename class variable.

without packagename

class Example extends Craft.UI.View {
    template(componentId){
        return `
            <div id="root" class="root">
                Hello World!
            </div>
        `;
    }
}

var view = new Example();
view.loadView();
Craft.Core.Context.getRootViewController().appendSubView(view);

This class is placed as:

The instance of Example class is named as Example_2, class name with trailing serial number. This is unique across your application, even if you add more instances of Example class, or even if you add Example class included in another package.

with packagename

To identify class of your instance by its ID, you can use packagename class variable.

class Example extends Craft.UI.View {
    constructor(options){
        super(options);
        this.packagename = 'craftkit.devtoblog.Example';
    }
    template(componentId){
        return `
            <div id="root" class="root">
                Hello World!
            </div>
        `;
    }
}

var view = new Example();
view.loadView();
Craft.Core.Context.getRootViewController().appendSubView(view);

This is placed as:

In this case, instance of Example class is placed as craftkit_devtoblog_Example_4.

You can use this to survey instance pool.

NOTE

The packagename is not restricted by module name itself.

Handling popstate by Route object - craftkit code pattern

CraftkitJS — Tue, 10 Nov 2020 14:25:41 +0000

In craftkit application, routing is managed by RootViewController, a special type of ViewController.

It defines interface for handling popstate event, by resolveRoutingRequest(route) method.

When you implement your own RootViewController, you have to implement this method.

The routing request is encapsulated by Route object, and it is passed to the method.

Route object

param	desc
launch	true if called from RootViewController#bringup
path	parsed path
event	defined if this is called by browser back/forward with popstate event

Parsing and normalizing Route.path is responsibility of your RootViewController implementation. (This is not the same as location.pathname)

To control History correctly, you have to check popstate event and launch flag like this:

let event  = route ? route.event  : null;
let launch = route ? route.launch : false;

if( launch ){
    // your are in launching sequence, and you should update history
    window.history.replaceState({},title,path);
}else{
    if( !event ){
        // called by browser back/forward with popstate event
        window.history.pushState({},title,path);
    }
}

This is idiom.

Every time you implement your application's RootViewController, your will write this kind of block.

Example

class Apple extends Craft.UI.View {
    template(componentId){
        return `
            <div class="root">🍎</div>
        `;
    }
}
class Orange extends Craft.UI.View {
    template(componentId){
        return `
            <div class="root">🍊</div>
        `;
    }
}
class PageController extends Craft.UI.DefaultRootViewController {
    constructor(options){
        super(options);
        this.data = {
            map: {
                apple: new Apple(),
                orange: new Orange()
            }
        };
    }
    resolveRoutingRequest(route){
        let path = route.path || 'apple'
        let view = this.data.map[path];
        this.replaceView(view);
        if( route.launch ){
            // launching the app
            window.history.replaceState({},'','#/'+path);
        }else{
            if( !route.event ){
                // in app navigation
                window.history.pushState({},'','#/'+path);
            }
        }
    }
}

This example code can be run on playground like following:

var rootViewController = new PageController();
Craft.Core.Context.setRootViewController(rootViewController);

rootViewController.bringup();

bringup method starts resolving Route object from popstate.
In this case, default view 🍎 is shown.

Then, focus url bar (command-l), and change trailing 'apple' to 'orange'.
🍊 is shown.

Push back button, 🍎 is shown again.

NOTE

Path normalization is supported by Craft.Core.HashRouter and Craft.Core.PathRouter. This is GoF Strategy pattern.

HashRouter is default. You can set it at the boot time of your application.


// in your bootloader

Craft.Core.Bootstrap.boot({
    router : Craft.Core.HashRouter,
    didBootApplication : function(){
        Craft.Core.Defaults.ALLOW_COMPONENT_SHORTCUT = true;
        let rootViewController = new PageController();
        Craft.Core.Context.setRootViewController(rootViewController);
        rootViewController.bringup();
    }
})

// in your RootViewController 

let normalized_path = Craft.Core.Context.getRouter().normalize(path);

if( route.launch ){
    window.history.replaceState({},'',path);
}else{
    if( !route.event ){
        window.history.replaceState({},'',path);
    }
}

See GitHub for more about boot setting.

https://github.com/craftkit/craft-uikit

Cascading ViewController as a Facade pattern - craftkit best practice

CraftkitJS — Mon, 09 Nov 2020 14:19:22 +0000

ViewController is cascaded to its sub views
ViewController can be described as Facade object

Cascading ViewController

When you append a sub-view to View, its ViewController is automatically cascaded.

This is done by Craft.Core.Component#appendSubView(|appendView).

if( this.viewController ){
    component.setViewController(this.viewController);
}

When you append a sub-view to ViewController, the controller is set to the sub-view.

This is done by Craft.Core.DefaultViewController#appendSubView(|appendView).

So, to implement your own ViewController, you have to inherit DefaultRootViewControler.

component.setViewController(this);

Appending ViewController to View or ViewController is same as above.

So, multiple ViewController on the same page(=DOM), like ModalViewController on PageController, run intuitively.

ViewController as Facade

To avoid complex object relation across your components, it is recommended to design your application by Delegate pattern.

Here is an example application using Delegate pattern.
This application places 9 panels on the screen. Click one, show selected num.

class PanelController extends Craft.UI.DefaultViewController {
    viewDidLoad(callback){
        for( let i=0; i<9; i++ ){
            let p = new Panel({
                delegate:this, num:i
            });
            this.appendView({
                id : 'container',
                component : p
            });
        }
        if(callback){ callback(); }
    }
    focus(num){
        this.shadow.getElementById('focus').innerHTML = num;
    }
    style(componentId){
        return `
            #container {
                width: 318px;
                display:flex; flex-direction:row; flex-wrap:wrap;
                margin-right:auto; margin-left:auto;
            }
        `;
    }
    template(componentId){
        return `
            <div>
                <div>
                    Selected: <span id="focus"></span>
                </div>
                <div id="container"></div>
            </div>
        `;
    }
}
class Panel extends Craft.UI.View {
    constructor(options){
        super(options);
        this.delegate = options.delegate;
        this.data = { num:options.num };
    }
    style(componentId){
        return `
            .root {
                box-sizing:border-box;
                width:100px; height:100px; margin:3px;
                background-color:#eee;
                display: flex;
                justify-content: center;
                align-items: center;
            }
        `;
    }
    template(componentId){
        return `
            <div class="root">
                <div onclick="${componentId}.delegate.focus(${componentId}.data.num)">
                    select: ${this.data.num}
                </div>
            </div>
        `;
    }
}

ViewController is always cascaded.

So, you can write above sample like this.

class PanelController extends Craft.UI.DefaultViewController {
    viewDidLoad(callback){
        for( let i=0; i<9; i++ ){
            let p = new Panel({
                num:i // without delegate
            });
            this.appendView({
                id : 'container',
                component : p
            });
        }
        if(callback){ callback(); }
    }
    focus(num){
        this.shadow.getElementById('focus').innerHTML = num;
    }
    style(componentId){
        return `
            .root { box-sizing:border-box; }
            #container {
                width: 318px;
                display:flex; flex-direction:row; flex-wrap:wrap;
                margin-right:auto; margin-left:auto;
            }
        `;
    }
    template(componentId){
        return `
            <div class="root">
                <div>
                    Selected: <span id="focus"></span>
                </div>
                <div id="container"></div>
            </div>
        `;
    }
}
class Panel extends Craft.UI.View {
    constructor(options){
        // constructor without delegate
        super(options);
        this.data = { num:options.num };
    }
    style(componentId){
        return `
            .root {
                box-sizing:border-box;
                width:100px; height:100px; margin:3px;
                background-color:#eee;
                display: flex;
                justify-content: center;
                align-items: center;
            }
        `;
    }
    template(componentId){
        return `
            <div class="root">
                <!-- call via viewController -->
                <div onclick="${componentId}.viewController.focus(${componentId}.data.num)">
                    select: ${this.data.num}
                </div>
            </div>
        `;
    }
}

In this code, PanelController looks more like implicit Facade pattern than Delegate pattern.

NOTE

Above examples are runnable on playground.

var view = new PanelController();
view.loadView();
Craft.Core.Context.getRootViewController().appendSubView(view);

🛺 Try CraftKit Playground:
https://github.com/craftkit/craftkit-playground

Style sharing and object oriented CSS - craftkit code pattern

CraftkitJS — Thu, 05 Nov 2020 15:03:41 +0000

craftkit encapsulates its CSS by ShadowDOM. So you can use simple CSS class name for your component.

And the CSS is defined by style() instance method. So you can append definition to its super class.

This spec allows you to implement object oriented styling. Now the time to say goodbye to CSS name convention.

This post describes how to inherit style. In other words, how to share style sheet across Craft.UI.View in your application.

Style Method overriding

class Hello extends Craft.UI.View {
    style(componentId){
        return `
            .root {
                margin: 50px;
            }
            .text {
                color: black;
            }
        `;
    }
    template(componentId){
        return `
            <div id="root" class="root">
                <h1>Hello</h1>
                <p class="text">World!</p>
            </div>
        `;
    }
}

class HelloRed extends Hello {
    style(componentId){
        return super.style(componentId) + `
            .text {
                color: red;
            }
        `;
    }
}

In HelloRed instance, margin:50px is cascaded, and color:red is applied as usual CSS rule.

class Aloha extends Craft.UI.View {
    style(componentId){
        return `
            .root {
                margin: 70px;
            }
            .text {
                color: blue;
            }
        `;
    }
    template(componentId){
        return `
            <div id="root" class="root">
                <h1>Aloha</h1>
                <p class="text">World!</p>
            </div>
        `;
    }
}

class AlohaRed extends Example {
    style(componentId){
        return super.style(componentId) + `
            .text {
                color: red;
            }
        `;
    }
}

Hello and Aloha have same CSS class definition, but its instance can exist simultaneously without conflict.

Pseudo multiple inheritance

Craft.UI.View is also a plain JavaScript class. So you can't define multiple inheritance for you view class.

But style method is defined dynamically, and resolved by same principle of CSS. So you can implement pseudo multiple style inheritance something like this:

// file: HeaderStyling.js

export class HeaderStyling {
    static css(){
        return `
            h1 { color:red; }
        `;
    }
}

//file: ParagraphStyling.js

export class ParagraphStyling {
    static css(){
        return `
            p { line-height: 2em; }
        `;
    }
}

Import and load them in your style method.

import { HeaderStyling } from 'HeaderStyling.js';
import { ParagraphStyling } from 'ParagraphStyling.js';

class Hello extends Craft.UI.View {
    style(componentId){
        return HeaderStyling.css() + ParagraphStyling.css() + `
            p { color: blue; }
        `;
    }
    template(componentId){
        return `
            <div id="root" class="root">
                <h1>Hello</h1>
                <p>World!</p>
            </div>
        `;
    }
}

Dynamic style injection

Above example imports style classes statically. Of course, it can be injected dynamically something like this:

class HelloController extends Craft.UI.View {
    viewDidLoad(callback){
        this.appendSubView(new Hello({
            styles: [HeaderStyling,ParagraphStyling]
        }))
    }
}

class Hello extends Craft.UI.View {
    constructor(options){
        super(options);
        this.injectedStyles = options.styles;
    }
    style(componentId){
        return this.injectedStyles.map( css => css.css() ).join('') + `
            p { color: blue; }
        `;
    }
    template(componentId){
        return `
            <div id="root" class="root">
                <h1>Hello</h1>
                <p class="text">World!</p>
            </div>
        `;
    }
}

Load external CSS

adoptedStyleSheets is no yet supported by Safari. To load external CSS file from remote, at first you have to append it to header, and then append it to this.shadow.

var link = document.createElement('link');
link.href = 'https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/all.min.css';
link.rel = 'stylesheet';
document.head.appendChild(link)

This is for console test. (You may preload in your index.html)

Then, define view that is appending CSS to its this.shadow in constructor.

class Hello extends Craft.UI.View {
    constructor(options){
        super();

        const link = document.createElement('link');
        link.href = 'https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/all.min.css';
        link.rel = 'stylesheet';
        this.shadow.appendChild(link);
    }
    template(componentId){
        return `
            <div id="root" class="root">
                <h1>Hello</h1>
                <i class="fas fa-globe"></i>
            </div>
        `;
    }
}

NOTE

Above examples are runnable on playground.

var view = new Hello();
view.loadView();
Craft.Core.Context.getRootViewController().appendSubView(view);

🛺 Try CraftKit Playground:
https://github.com/craftkit/craftkit-playground

Accessing instance variable from template literal - craftkit code pattern

CraftkitJS — Wed, 04 Nov 2020 06:21:04 +0000

Template for craftkit is defined by template method. It only requires returning HTML starting with single node. Usually you will use JavaScript template literal to define your view's structure. (see more: GitHub document)

template method gets a String argument componentId. It is bound to its instance via widnow[componentId] if you set Craft.Core.Defaults.ALLOW_COMPONENT_SHORTCUT = true.

So below two codes have same behavior.

Access via this:

class Example extends Craft.UI.View {
    constructor(options){
        super(options);
        this.data = { val:'Hello!' };
    }
    template(componentId){
        return `
            <div id="root" class="root">
                ${this.data.val}
            </div>
        `;
    }
}

Access via componentId:

class Example extends Craft.UI.View {
    constructor(options){
        super(options);
        this.data = { val:'Hello!' };
    }
    template(componentId){
        return `
            <div id="root" class="root">
                ${window[componentId].data.val}
            </div>
        `;
    }
}

When you access to the instance variable, it is natural style to use this.

But in JavaScript function context, this points function itself. So you have to use componentId to access inside its instance.

class Example extends Craft.UI.View {
    action(str){
        alert(str);
    }
    template(componentId){
        return `
            <div id="root" class="root">
                <div onclick="${componentId}.action('World!')">
                    Hello
                </div>
            </div>
        `;
    }
}

Take a look:

<!-- Good -->
<div onclick="${componentId}.action('World!')">
    Hello
</div>

<!-- Uncaught TypeError: this.action is not a function -->
<div onclick="this.action('BUG!')">
    Hello
</div>

<!-- Uncaught TypeError: Cannot read property 'val' of undefined -->
<div>
    componentId is evaluated as String
    ${componentId.data.val}
</div>

BTW, the argument componentId can be named as you like.

class Example extends Craft.UI.View {
    constructor(options){
        super(options);
        this.data = { val:'Hello!' };
    }
    action(str){
        alert(str);
    }
    template(self){
        return `
            <div id="root" class="root">
                <div onclick="${self}.action('World!')">
                    ${this.data.val} traditional looks and feel
                </div>
            </div>
        `;
    }
}

NOTE

Above examples are runnable on playground.

var view = new Example();
view.loadView();
Craft.Core.Context.getRootViewController().appendSubView(view);

🛺 Try CraftKit Playground:
https://github.com/craftkit/craftkit-playground

Dynamic styling of Shadow Host - craftkit code pattern

CraftkitJS — Tue, 03 Nov 2020 14:50:53 +0000

Usually, it is enough to define style only for the .root and its children. But sometimes, you want to edit style for host element. Here is patterns for this.

Define Shadow Host style

To define Shadow Host style, just write CSS in :host as usual.

class Example extends Craft.UI.View {
    style(componentId){
        return `
            :host {
                padding-top: env(safe-area-inset-top);
                padding-left: env(safe-area-inset-left);
                padding-right: env(safe-area-inset-right);
            }
        `;
    }
}

Direct Host style modification

You can directly update Host element styling via this.shadow.host.style[*].

class Example extends Craft.UI.View {
    updateShadowHostWidth(){
        this.shadow.host.style.width = '200px';
    }
    style(componentId){
        return `
            :host {
                width: 100px;
            }
        `;
    }
}

Swap Shadow Host CSS class

If you would like to change style of Host element on the fly, your target class should be defined in the parent component to be able to affect the shadow element.

class Example extends Craft.UI.View {
    viewDidLoad(callback){
        this.appendView(new ExampleCore());
        if(callback){ callback(); }
    }
    style(componentId){
        return `
            .light { color:#333; background-color: #fff; }
            .dark { color:#fff; background-color: #333; }
        `;
    }
}

class ExampleWrapped extends Craft.UI.View {
    constructor(options){
        super(options);
        this.data = { mode:0 };
    }
    toggleMode(){
        if( this.data.mode++ % 2 ){
            this.shadow.host.classList.add('light')
            this.shadow.host.classList.remove('dark')
        }else{
            this.shadow.host.classList.add('dark');
            this.shadow.host.classList.remove('light')
        }
    }
    style(componentId){
        return `
            :host { color:#333; background-color: #fff; }
            .root { 
                width:100px; marign-left:auto; marign-right:auto;
            }
        `;
    }
    template(componentId){
        return `
            <div id="root" class="root" 
            onclick="${componentId}.toggleMode()">
                Hello!
            </div>
        `;
    }
}

Discouraged pattern

You can write something like the following code, but the code goes back and forth. So, this pattern should be avoided.

class ExampleWrapper extends Craft.UI.View {
    constructor(options){
        super(options);
        this.data = { mode:1 };
        this.views = { example:null };
    }
    viewDidLoad(callback){
        this.views.example = new ExampleWrapped({delegate:this});
        this.appendView(this.views.example);
        if(callback){ callback(); }
    }
    toggleMode(){
        if( this.data.mode++ % 2 ){
            this.views.example.darkMode();
        }else{
            this.views.example.lightMode();
        }
    }
    style(componentId){
        return `
            .light { color:#333; background-color: #fff; }
            .dark { color:#fff; background-color: #333; }
        `;
    }
}

class ExampleWrapped extends Craft.UI.View {
    constructor(options){
        super(options);
        this.delegate = options.delegate;
    }
    lightMode(){
        this.shadow.host.classList.add('light')
        this.shadow.host.classList.remove('dark')
    }
    darkMode(){
        this.shadow.host.classList.add('dark');
        this.shadow.host.classList.remove('light')
    }
    style(componentId){
        return `
            :host { color:#333; background-color: #fff; }
            .root { 
                width:100px; marign-left:auto; marign-right:auto;
            }
        `;
    }
    template(componentId){
        return `
            <div id="root" class="root" 
            onclick="${componentId}.delegate.toggleMode()">
                Hello!
            </div>
        `;
    }
}

NOTE

Above examples are runnable on playground.

var view = new Example();
view.loadView();
Craft.Core.Context.getRootViewController().appendSubView(view);

🛺 Try CraftKit Playground:
https://github.com/craftkit/craftkit-playground

Data injection - How to update a view by remote data - craftkit best practice

CraftkitJS — Mon, 02 Nov 2020 14:51:14 +0000

Data will always come from outside of application asynchronously. So we are always plagued by way of loading data, and making its view. If you don't care about lag of data load, your interface easily stack.

Best practice: Data injection

The best practice for this problem is "load data then make its view" pattern. (called as "Data injection" pattern)

It is best to implement controller class to load remote data, that makes its factorized view (Factorize pattern) after loaded data.

In other word, this is a kind of GoF Facade pattern, or minimized MVC structure. Usually, this controller represents reusable package.

If factorized view classes need to load remote data, the request should be delegated to the controller class. (Delegate pattern)

This will make complexity aggregated in the controller.

Example

Here is a sample remote data same as craftkit best practice - How to manage sub views for array data.

https://craftkit.dev/craftkit-playground/sampledata/simple_products.json

[
    { name: 'Apple', price: 10 },
    { name: 'Orange', price: 13 },
    { name: 'Strawberry', price: 20 },
    { name: 'Pear', price: 9 }
]

Here is a sample implementation to load and show remote product list.

class ProductListController extends Craft.UI.View {
    constructor(options){
        super(options);
        this.data = { products:[] };
        this.views = { current:null };
    }
    viewDidLoad(callback){
        this.loadData();
        this.renderReloadBtn();
        if( callback ){ callback(); }
    }
    loadData(){
        this.renderLoading();

        let xhr = new XMLHttpRequest();
        xhr.onload = (e) => {
            this.data.products = JSON.parse(xhr.response);
            this.renderProductList();
        };
        xhr.open('GET','https://craftkit.dev/craftkit-playground/sampledata/simple_products.json');
        xhr.send();
    }
    renderLoading(){
        let view = new Loading();
        this.replaceView({id:'list',component:view});
        this.views.current?.unloadView(); // for chrome
        this.views.current = view;
    }
    renderProductList(){
        let view = new ProductList({delegate:this});
        this.replaceView({id:'list',component:view});
        this.views.current?.unloadView(); // for chrome
        this.views.current = view;
    }
    renderReloadBtn(){
        this.appendView({
            id: 'btn',
            component: new ReloadBtn({delegate:this})
        });
    }
    style(componentId){
        return `
            #btn { background-color:#eee; }
        `;
    }
    template(componentId){
        return `
            <div id="root" class="root">
                <div id="list"></div>
                <div id="btn"></div>
            </div>
        `;
    }
}

class Loading extends Craft.UI.View {
    template(componentId){
        return `
            <div>Loading...</div>
        `;
    }
}
class ReloadBtn extends Craft.UI.View {
    constructor(options){
        super(options);
        this.delegate = options.delegate;
    }
    reloadData(){
        this.delegate.loadData();
    }
    style(componentId){
        return `
            .root { cursor:pointer; }
        `;
    }
    template(componentId){
        return `
            <div id="root" class="root" 
                onclick="${componentId}.reloadData();">
                Reload data
            </div>
        `;
    }
}

class ProductList extends Craft.UI.View {
    constructor(options){
        super(options);
        this.delegate = options.delegate;
        this.views = { products:[] }
    }
    viewDidLoad(callback){
        this.delegate.data.products.forEach( p => {
            let view = new Product(p);
            this.appendView(view);
            this.views.products.push(view);
        });
    }
}
class Product extends Craft.UI.View {
    constructor(options){
        super(options);
        this.data = options;
    }
    template(componentId){
        return `
            <div id="root" class="root">
                ${this.data.name} : ${this.data.price}
            </div>
        `;
    }
}

Sometimes, controller is represented as Page object to be shown in navigation stack. Sometimes, controller is represented as micro-fronend UI component.

NOTE

Above examples are runnable on playground.

var view = new ProductListController();
view.loadView();
Craft.Core.Context.getRootViewController().appendSubView(view);

🛺 Try CraftKit Playground:
https://github.com/craftkit/craftkit-playground

How Component and componentId covers and exposes its structure - inside craftkit

CraftkitJS — Wed, 28 Oct 2020 14:48:46 +0000

Prop	desc.
this.view	shadow host
this.shadow	shadow root
this.root	component root based on `template`

this.view, this.shadow and this.root are Craft.UI.View's basic property that is defined by Craft.Core.Component the top level class of all views.

this.view is the top level DOM element of your component, having unique componentId. This is the Shadow Host of your component.

this.shadow is Shadow Root of your component, attached to this.view (Shadow Host) by open mode.

this.root is the first child of your template, and it is appended to the this.shadow (Shadow Root).

Your template is under the Shadow Root. Therefore CSS class name and DOM ID never conflict across the craftkit application. This is the first key technology of craftkit to enable comfortable OOP by encapsulating Component definition.

For example:

class Vehicle extends Craft.UI.View {
    whoami(){
        return this.shadow.getElementById('text').innerHTML;
    }
    style(componentId){
        return `
            .root { color:red; }
        `;
    }
    template(componentId){
        return `
            <div id="root" class="root">
                <span id="text">I'm Vehicle</span>
            </div>
        `;
    }
}
class Bike extends Vehicle {
    style(componentId){
        return super.style(componentId) + `
            .root { color:blue; }
        `;
    }
    template(componentId){
        return `
            <div id="root" class="root">
                <span id="text">I'm Bike.</span>
            </div>
        `;
    }
}
class Car extends Vehicle {
    style(componentId){
        return super.style(componentId) + `
            .root { color:purple; }
        `;
    }
    template(componentId){
        return `
            <div id="root" class="root">
                <span id="text">I'm Car.</span>
            </div>
        `;
    }
}

Bike and Car both cascade .root CSS class from Vehicle, but both root class independently applied and never conflict.

By the principle of Shadow DOM specification, you cannot access inside of your component DOM element via its ID from out side of your component.

But your can access inside of your component's element via componentId from any where you want.

Instantiated component is registered to the Craft.Core.ComponentStack by its unique componentId. If you set Craft.Core.Defaults.ALLOW_COMPONENT_SHORTCUT to true at boot time, you can also use the componentId as global variable. This is the second key technology of craftkit.

This feature is used to call instance method from rendered template.

class DangerousTruck extends Car {
    ignite(){
        this.shadow.getElementById('text').innerHTML = "🚛🔥🔥🔥";
    }
    cooldown(){
        this.shadow.getElementById('text').innerHTML = "I'm COOL Truck 😄";
    }
    style(componentId){
        return super.style(componentId) + `
            .root { color:purple; }
        `;
    }
    template(componentId){
        return `
            <div id="root" class="root">
                <span id="text" onclick="${componentId}.ignite()">
                    I'm dangerous Truck.
                </span>
            </div>
        `;
    }
}

When you click the text, it ignites the truck!

Of course, you can call ignite method from global by something like this:

Object.keys(Craft.Core.ComponentStack.container)
.filter( id => id.match('Dangerous') )
.map( danger => window[danger].cooldown() )

※ Object.keys for Craft.Core.ComponentStack.container returns array of componentId. This is String. So it is accessing from window object.

NOTE

Above examples are runnable on playground.

var bike_view = new Bike();
bike_view.loadView();
Craft.Core.Context.getRootViewController().appendSubView(bike_view);

var car_view = new Car();
car_view.loadView();
Craft.Core.Context.getRootViewController().appendSubView(car_view);

bike_view.shadow.getElementById('text').innerHTML; //-> I'm Bike
bike_view.whoami();                                //-> I'm Bike

car_view.root.style.color = 'purple' //-> make 'I'm Car.' purple

var truck_view = new DangerousTruck();
truck_view.loadView();
Craft.Core.Context.getRootViewController().appendSubView(truck_view);

truck_view.ignite(); //-> 🚛🔥🔥🔥

🛺 Try CraftKit Playground:
https://github.com/craftkit/craftkit-playground

How to update view - craftkit code pattern

CraftkitJS — Mon, 26 Oct 2020 14:45:56 +0000

Currently, Craft.UI.View mainly provides UI classes to encapsulate its method, data and DOM structure. View component is automatically rendered by ViewController according to view's lifycycle method implementation.

After you append view on the screen, you have to update its view (=DOM) by your self. (Therefore this is named as craft kit)

Shadow access pattern

Most primitive pattern is finding DOM element via this.shadow.

class CounterView extends Craft.UI.View {
    constructor(options){
        super(options);
        this.data = { count:0 };
    }
    countup(){
        this.data.count++;
        this.shadow.getElementById('counter').innerHTML = this.data.count;
    }
    template(componentId){
        return `
            <div id="root" class="root">
                <span id="counter">${this.data.count}</span>
            </div>
        `;
    }
}

In the latest chrome, you can use replaceChildren instead of innerHTML.

renderView pattern

Most basic pattern is using Craft.UI.View#renderView method.

This example is just replacing above this.shadow.getElementById to renderView.

class CounterView extends Craft.UI.View {
    constructor(options){
        super(options);
        this.data = { count:0 };
    }
    countup(){
        this.data.count++;
        this.renderView();
    }
    template(componentId){
        return `
            <div id="root" class="root">
                ${this.data.count}
            </div>
        `;
    }
}

Every time you call countup() method, template is rendered again. This pattern is useful while your data is simple.

If your view does not have this.data at the time it is instantiated, your template will be defined by optional chain somthing like this: ${this.data.YourDataSet?.count}.

Swap and renderView pattern

In more complex application, you might swap template dynamically.

class CounterView extends Craft.UI.View {
    constructor(options){
        super(options);
        this.data = { count:0 };
        this.templates = {
            even : `
                <div id="root" class="root">
                    Some complex even view: ${this.data.count}
                </div>`,
            odd  : `
                <div id="root" class="root">
                    Some complex odd view: ${this.data.count}
                </div>`,
        };
        this.crr_template = this.templates.even;
    }
    countup(){
        this.data.count++;
        if( this.data.count % 2 == 0 ){
            this.crr_template = this.templates.even;
        }else{
            this.crr_template = this.templates.odd;
        }
        this.renderView();
    }
    template(componentId){
        return this.crr_template;
    }
}

renderView() renders template defined by this.crr_template.

Factorize pattern

This pattern defines more macro structure.

Also described in the post "How to manage sub views for array data", let's break down your template structure until it is almost atomically resolved.

class CounterView extends Craft.UI.View {
    constructor(options){
        super(options);
        this.data = { count:0 };
        this.views = { numbox:null };
    }
    countup(){
        this.data.count++;
    }
    updateNumBoxView(){
        let view = new NumBox({num:this.data.count});
        this.replaceView({
            id        : 'container',
            component : view,
        });
        this.views.numbox.unloadView();
        this.views.numbox = view;
    }
    viewDidLoad(callback){
        this.updateNumBoxView();
        if(callback){ callback(); }
    }
    template(componentId){
        return `
            <div id="root" class="root">
                <div id="container"></div>
            </div>
        `;
    }
}

class NumBoxView extends Craft.UI.View {
    constructor(options){
        super(options);
        this.data = options;
    }
    template(componentId){
        return `
            <div id="root" class="root">
                ${this.data.count}
            </div>
        `;
    }
}

Every time you update count, new view component will be created and placed in the #id:container. Call unloadView if you have to expire its memory.

Combined

Actual web application will load its data from remote api, or will be generated by user in run time, or so on. So you may have to combine several patterns.

class CounterView extends Craft.UI.View {
    constructor(options){
        super(options);
        this.data = { count:0 };
        this.views = { 
            even : new EvenNumBoxView({ delegate:this }),
            odd  : new OddNumBoxView({ delegate:this })
        };
    }
    viewDidLoad(callback){
        this.updateNumBoxView();
        if(callback){ callback(); }
    }
    countup(){
        this.data.count++;
        this.updateNumBoxView();
    }
    updateNumBoxView(){
        if( this.data.count % 2 == 0 ){
            this.views.even.renderView();
            this.replaceView({
                id        : 'container',
                component : this.views.even,
            });
        }else{
            this.views.odd.renderView();
            this.replaceView({
                id        : 'container',
                component : this.views.odd,
            });
        }
    }
    template(componentId){
        return `
            <div id="root" class="root">
                <div id="container"></div>
            </div>
        `;
    }
}

class EvenNumBoxView extends Craft.UI.View {
    constructor(options){
        super(options);
        this.delegate = options.delegate;
    }
    template(componentId){
        return `
            <div id="root" class="root">
                Some complex even view structure: 
                ${this.delegate.data.count}
            </div>
        `;
    }
}

class OddNumBoxView extends Craft.UI.View {
    constructor(options){
        super(options);
        this.delegate = options.delegate;
    }
    template(componentId){
        return `
            <div id="root" class="root">
                Some complex odd view structure: 
                ${this.delegate.data.count}
            </div>
        `;
    }
}

In this example, EvenNumBoxView and OddNumBoxView delegate data management to CounterView. (This is called as "delegate pattern")

NOTE

Above examples are runnable on playground.

var view = new CounterView();
view.loadView();
Craft.Core.Context.getRootViewController().appendSubView(view);
view.countup();

🛺 Try CraftKit Playground:
https://github.com/craftkit/craftkit-playground

How to manage sub views for an array data - craftkit best practice

CraftkitJS — Thu, 22 Oct 2020 07:34:35 +0000

Sometimes, your sub-views has listed view created by array data.

In such case, you have two choice to create view for them. One is make loop in the template, one is break down to simple view.

Here is a comparison of sample product list:

var products = [
    { name: 'Apple', price: 10 },
    { name: 'Orange', price: 13 },
    { name: 'Strawberry', price: 20 },
    { name: 'Pear', price: 9 }
];

Loop pattern

class ProductList extends Craft.UI.View {
    constructor(options){
        super(options);
        this.data = { products:options.products };
        this.views = {};
    }
    template(componentId){
        return `
            <div id="root" class="root">
                ${ this.data.products.map( (product,idx) => `
                    <div id="idx" class="product">
                        ${product.name} : ${product.price}
                    </div>
                `).join('')}
            </div>
        `;
    }
}

Factorize pattern

class Product extends Craft.UI.View {
    constructor(options){
        super(options);
        this.data = options;
        this.views = {};
    }
    template(componentId){
        return `
            <div id="root" class="root">
                ${this.data.name} : ${this.data.price}
            </div>
        `;
    }
}

class ProductList extends Craft.UI.View {
    constructor(options){
        super(options);
        this.data = { products:options.products };
        this.views = { products:[] };
    }
    viewDidLoad(callback){
        this.data.products.forEach( p => {
            let view = new Product(p);
            this.appendView(view);
            this.views.products.push(view);
        });
    }
}

Write looping block directly in the template method is shorter than Factorise pattern. But when you control product view after appended it, you have to write something like this:

var target = this.shadow.getElementById('1');
target.root.style.color = 'red';

Or, you have to get the idx from the product map. This is only useful for a quick program and simple list.

Therefore, the best practice of managing sub-views for an array data is Factorise pattern.

Always, this brings good results and ease to maintain.

🛺 Try CraftKit Playground:
https://github.com/craftkit/craftkit-playground

How to manage sub-views - craftkit best practice

CraftkitJS — Thu, 22 Oct 2020 07:30:56 +0000

When you make complex user interface, your view has many sub-views under it. In such case, you can hold many sub-view's instance in your class directly.

But the best practice of managing sub-views is to set them into this.views.

This is the same practice as this.data management.

Craft.UI.View and its super-class Craft.Core.Component has many field by default. Those fields are designed to not conflict with user land usage. But sometimes it might be occurred.

To prevent field confliction, you are recommended to set your sub-views in this.views.

class Header extends Craft.UI.View {
    constructor(options){
        super(options);
        this.views = {};
    }
    viewDidLoad(callback){
        let title = new Title();
        this.appendSubView(title);
        this.views.title = title;

        let backbtn = new BackBtn();
        this.appendSubView(backbtn);
        this.views.backbtn = backbtn;

        if( callback ){ callback(); }
    }
    updateTitleText(text){
        this.views.title.setText(text);
    }
}

🛺 Try CraftKit Playground:
https://github.com/craftkit/craftkit-playground