obi.io
Layout & Templates

New KOBI documentation is available: https://adeo-ccdp.gitbook.io/kobi/

Foreword about micro frontend architecture.

KOBI has been designed from the beginning to follow micro frontends architecture concepts.
A sort of basic summarized idea of micro frontends is to allow you to think about your page as an assembly of components:

page layout page layout

KOBI make some strong assumptions on the implementation so as to handle some of the key constraints that come with this kind of architecture:

  • ensures visual and ergonomic consistency through page
  • handle common resources: CSS & JS
  • communication between components
  • retrieves all components in an efficient way
  • …
Here is a brief introduction to micro frontends and possible ways of achieving it: Micro frontends

Site’s HTML Templates

The journey to designing this kind of pages with KOBI starts with an HTML template. The HTML template will then be used to create Page Models in Designer and those Page Models will be used to create your site Pages.

Template files are hosted by the Site application.

HTML templates define a base HTML structure for a site with common HTML tag (<html>, <head>, <body>).
KOBI propose some special tags that you will want to add inside your template :

  • <kobi:container> : to be able to add components in your page from Designer
  • <kobi:fragment> : to add a component that will be used in every models/pages based on this template
  • <kobi:application> : to embed a complete application
  • <kobi:include> : to include an html file
  • <kobi:css> : to inject the static css files from your components
  • <kobi:js> : to inject the static js files from your components

Templates location

Your templates should be hosted in your Site application under a configurable folder (/sites-templates by convention).
Your templates base path and resources should be registered to be usable, be sure to read the Site registration section.

Templates inclusion

KOBI will look for the registered main resource in your templates folder, eg : global.html. But for readability purpose you may want to split your files and use the <kobi:include> instruction to have this kind of structure :

/site-templates
        ├─ global.html
        ├─ head.html
        └─ body.html

Templates files

Following the structure above you should have this kind of files under /site-templates :

global.html

1
2
3
4
5
6
7
8
9

<!DOCTYPE html>
<html lang="fr">
    <head>
        <kobi:include path="head.html"/>
    </head>
    <body>
        <kobi:include path="body.html"/>
    </body>
</html>

head.html

1
2
3
4
5

    <meta charset="UTF-8">
    <link rel="stylesheet" type="text/css" href="/static/css/common.css"/>
    <kobi:css/>
    <script src="/static/js/common.js"></script>
    <kobi:js/>

body.html

1

    <kobi:container anchor="main"/>

The final rendered template (accessible as / in designer since it’s at the root of your templates folder) will look like that :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

<!DOCTYPE html>
<html lang="fr">
    <head>
        <meta charset="UTF-8">
        <link rel="stylesheet" type="text/css" href="/static/css/common.css"/>
        <kobi:css/>
        <script src="/static/js/common.js"></script>
        <kobi:js/>      
    </head>
    <body>
        <kobi:container anchor="main"/>
    </body>
</html>

This is your first template to work with in Designer. But you can extends this to many more !

Templates extension

To add a new template usable in designer, for example a navigation template that include a Header and a Footer components, create a new folder named navigation under /site-templates with a body.html file inside :

/site-templates
        ├─ navigation
        │        └─ body.html
        ├─ global.html
        ├─ head.html
        └─ body.html

/navigation/body.html

1
2
3

    <kobi:fragment anchor="header" definition="io.kobi.sample.Header"/>
    <kobi:container anchor="main"/>
    <kobi:fragment anchor="footer" definition="io.kobi.sample.Footer"/>

When using the /navigation template in Designer, the body.html will be used instead of the root one. This result in the following complete HTML file :

/navigation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

<!DOCTYPE html>
<html lang="fr">
    <head>
        <meta charset="UTF-8">
        <link rel="stylesheet" type="text/css" href="/static/css/common.css"/>
        <kobi:css/>
        <script src="/static/js/common.js"></script>
        <kobi:js/>
    </head>
    <body>
        <kobi:fragment anchor="header" definition="io.kobi.sample.Header"/>
        <kobi:container anchor="main"/>
        <kobi:fragment anchor="footer" definition="io.kobi.sample.Footer"/>
    </body>
</html>

Static resources

If you want to refer to static resources in template, you have to use absolute path of your resources, ie : /static/js/common.js.
It is important all of your static resources to be stored in a folder and not at the root path.
KOBI need to know wich path(s) deliver static resources to be able to rewrite url with a mounting point and then to route request on your application.

/static
      ├─ js
      │   └─ common.js
      └─ css
          └─ common.css

Page Model

Page Model can be interpreted as an implementation of a template. It is created through the KOBI Designer interface with which you can configure components declared in HTML template through <kobi:fragment> tag or add any components in container through <kobi:container> tag.

A Page Model can inherit an other Page Model and so on.

Below, a Root Page model based on “/” template (explained above) and a “Header & Footer” Page Model who inherits from Root Page model and based on “/navigation” template. Two others Page Model, “Product” and “Application”, who inherits from “Header & Footer” Page Model.

page model page model

A Page Model can be inherited by a Page (Page created with KOBI Designer), or directly used to diplay a final page (virtual page not created with KOBI Designer). For instance, we will use one or few Page Model to display all product pages (it is not necessary to create as many Page as there is product in your referential).

User guide for page models is accessible here.

Page

A Page can be interpreted as an implementation of a Page Model and can not exist alone, It is created through the KOBI Designer interface with which you can add components in container previously created in parent Page Model.
Each page has its own url.

We may have different available variation (composition of a page) eligible depending criterias, the main criteria (and the only criteria at the moment this documentation is written) is the timeline.

In the following exemple, a different variation is displayed to the customer while the sales period for the sales page.

User guide for pages is accessible here.

What's on this Page