Bobril - Integration to Another Web Application

Do you like Bobril framework, but your web application is developed in another framework? Do not despair! There is a solution.

Contents

• Motivation, why you should use Bobril
• Basic theory of integration
• Necessary steps for Bobril components integration
• Example of implementation in your application

Motivation

Bobril is inspired by ReactJS and Mithril. Bobril is quick. So, if you want to speed up critical parts of your application, Bobril is a good choice. If It seems that Bobril is incompatible with your application, don't be afraid, everything what Bobril needs to work is a single DOM element (e.g. div) as a container. Nothing more.

Before you continue reading, answer these questions by yourself:

• Do you want to boost speed of critical parts of your application?
• Do you want to implement your application in easy readable and straight form?
• Do you want to use component based framework?

If the answer is YES, than continue reading...

Basic Theory of Integration

We will use bobril-build tool to compile from TypeScript. You can find more information about bobril-build here.

Read useful information here too.

What Bobril needs to work in your web application:

• container (e.g. div element)
• global JavaScript variable (namespace)- Bobril and your application can communicate through this global variable each other

Important for integration are methods: b.init and b.addRoot

• b.init method must be called only once in webapp, but exactly once. If you don’t call it, Bobril will not render anything (you can set render element as a second parameter to b.init too)
• b.addRoot ensures that Bobril renders itself to yourDivReference element (see the code example below):

b.addRoot(() => {
    return [
        b.styledDiv("Hello world")
    ];
, yourDivReference};

Necessary Steps for Bobril Components Integration

Your Bobril components are probably located in NPM registry. You download them through npm or yarn package manager. All components you want to use are defined in package.json. In a typical Bobril application, you can just import them and immediately use. But how to connect these components with your application?

You can’t use Bobril components in your application directly.

Preparation of Bobril Component for Integration

Naming conventions of files are up to you.

Create Wrapper of Bobril Component

• You can imagine wrapper as a "mini Bobril application“
• It is necessary for integration.
• For Bobril "Component1“ create wrapper component "WrapperComponent1“
• Example: You want to integrate component called "Component1“ (which is shared between projects and is implemented in pure bobril). You have to create component "WrapperComponent1“. This wrapper (mini-application) will ensure the bridge between your app and bobril.

Hint: If you want to create a composition of components (e.g., whole new page implemented in bobril), you can create one wrapper for the whole page.

Example of Component WrapperComponent1 for component Component1

• Name of wrapper component: WrapperComponent1
• Filename of wrapper component: wrapper-component1.ts

import * as b from 'bobril';
import * as Component1 from 'component1

export function createComponent1(settings: IComponent1Config): IComponent1Api {
    b.addRoot(
        () => {
            return [
                Component1.create({
                    name: setings.name,
                    color: setting.color
                })
            ]
        },
        settings.parentElement // It is reference to element, you create in you app
    );

    return {
        // expose some API to external system
    };
}

Define Common Namespace in Your Project – via Global JavaScript Variable

In the samples below, the namespace is called bobril_integration, but the name is up to you.

• Through this global variable, the integration will be implemented

Create an integration project:

• Classic Bobril project
• Simple project, that will only compile all necessary bobril components to a one bundle file and expose these components via bobril_integration namespace variable.

Sample of Package.json of Integration Project

• See the "dependencies" section. It defines exposed Bobril components. You will see that these components will be available through bobril_integration namespace variable.

{
  "name": "bundle-project",
  "version": "0.0.1",
  "dependencies": {
    "wrapper-component1": "1.x.x",
    "wrapper-component2": "*",
    "wrapper-component3": "0.x.x"
  },
  "main": "src/app.ts",
  "bobril": {
    "example": "examples",
    "head": "<script>window.bobril_integration = {};</script>",
    "prefixStyleDefs": "bobril-"
  }
}

As you can see, there is one important file in the integration project.

Main File of Integration Project - App.ts

• The name of the file is up to you, but it is recommended to use app.ts

• Don’t forget to edit "main": "src/app.ts" to correct path of app.ts in package.json

import * as b from 'bobril';
import { createComponent1 } from 'wrapper—component1';
import { createComponent2 } from 'wrapper-component2';
import { createComponent3 } from 'wrapper-component3';

// Call there b.init only once, so in components wrapper, you dont have to call it again
b.init(()=> []);

// global exports for External App
declare var bobril_integration: any;

//bobril_bundle namespace
bobril_integration.bobril_bundle = bobril_integration.bobril_bundle || {};

// create component "export"
bobril_integration.bobril_bundle.component1 = createComponent1;

// create component "export"
bobril_integration.bobril_bundle.component2 = createComponent2;

// create component "export"
bobril_integration.bobril_bundle.component3 = createComponent3;

This file, exactly defines how components will be exposed to the external system.

Example: bobril_integration.bobril_bundle.component1 = createComponent1;

Compilation of Integration Project

Execute bb b command in the root directory, than a.js and a.png sprite with all necessary images will be generated. Copy this source to your project.

You should have bundled all components in bundle file and images in sprite file.

Example of Implementation In Your Application

Inject bundle.js to Your Project

• Insert to index.html
• It has to be on the top of the file
  JavaScript

  <script type="text/javascript" src="externalResources/a.js"></script>

Usage of Bobril Component

• Create a div container in your framework
  JavaScript

  var containerForBobril = $("<div/>")

• Call bobril_integration.bobril_bundle.component({...})
  JavaScript

  var bobwaiComponentAPI = bobril_integration.bobril_bundle.component1({
     name: "Name",
     color: "#00FF00",
     parentElement: containerForBobril
  });

Full Example

var containerForBobril = $("<div/>")
$("body").append(containerForBobril)

var bobwaiComponentAPI = bobril_integration.bobril_bundle.component1({
   name: "Name",
   color: "#00FF00",
   parentElement: containerForBobril
});