Layout Swap

caution

works only with @micro-lc/composer@^2 and @micro-lc/orchestrator@^2

<bk-layout-swap></bk-layout-swap>

The Layout Swap allows swapping between different document fragments / compose configurations

The use case this component addresses is when two or more configurations live in the same page but they need to be rendered conditionally, using another component to swap them, such as the Tabs or the Button.

At any time, all components of all layouts are included in the page.

The Layout Swap allows to hide the components of all layouts but one. The visible layout can be switched via the event layout/change.

caution

this component, due to the fact it must be loaded in advance, is bundled separately at /bk-layout-swap.esm.js

How to configure

A content should be specified for Layout Swap. Note that content is not a property of the Layout Swap.

{
  "tag": "bk-layout-swap",
  "properties": {
    "layout": "table"
  },
  "content": [
    {
      "tag": "div",
      "attributes": {
        "slot": "table"
      },
      "content": {
        ...
      }
    },
    {
      "tag": "div",
      "attributes": {
        "slot": "calendar"
      },
      "content": {
        ...
      }
    }
  ]
}

Each layout must be a unique HTML element with a slot property set to the layout it represents. The content of the layout stays inside the relative HTML element.

The resulting configuration is equivalent to the following HTML snippet:

<bk-layout-swap bootstrap-layout="layout1">
  <div slot="table">
    <bk-table />
  </div>
  <div slot="calendar">
    <bk-calendar />
  </div>
</bk-layout-swap>

Property layout controls the default layout to make visible by default.

Difference with Layout Container

There are differences between the Layout Container and this component:

1. the inner elements are never in shadow DOM -> disable-shadow-dom is not needed
2. there's no composing on layouts after the initialization
3. this component does not handle the communication layer of components. eventBus is injected by the composer on each component. To isolate components the property eventBus must be tuned locally for each component. An example is available showing how to handle multiple eventBus.

Examples

Example: Basic usage

The use case this component addresses is when two or more configurations live in the same page but they need to be rendered conditionally, using another component - such as the Tabs or the Button to swap them.

For instance, to swap between a table view like

[
  {
    "tag": "bk-table",
    "properties": {
      "dataSchema": {
        "type": "object",
        "properties": {
          "_id": {"type": "string"},
          "name": {"type": "string"}
        }
      }
    }
  }
]

and a calendar component

[
  {
    "tag": "bk-calendar"
  }
]

It is possible to use Buttons, both firing the layout/change event, with the payload layout: table and layout: calendar to reach either layout.

[
  {
    "tag": "bk-button",
    "properties": {
      "content": "Go to Table",
      "action": {
        "type": "event",
        "config": {
          "events": {
            "label": "layout/change",
            "payload": {
              "layout": "table"
            }
          }
        }
      }
    }
  },
  {
    "tag": "bk-button",
    "properties": {
      "content": "Go to Calendar",
      "action": {
        "type": "event",
        "config": {
          "events": {
            "label": "layout/change",
            "payload": {
              "layout": "calendar"
            }
          }
        }
      }
    }
  }
]

This structure can be inserted within a Layout Swap.

When a layout/change event is fired the Layout Swap shows only the matching branch amongst its direct children according to the slot attribute. The initial layout is controlled either by the layout property or the bootstrap-layout attribute.

The configuration looks like this:

{
  "tag": "bk-layout-swap",
  "properties": {
    "layout": "table"
  },
  "content": [
    {
      "tag": "div",
      "attributes": {
        "slot": "table"
      },
      "content": {
        "tag": "bk-table",
        "properties": {
          "dataSchema": {
            "type": "object",
            "properties": {
              "name": {"type": "string"}
            }
          }
        }
      }
    },
    {
      "tag": "div",
      "attributes": {
        "slot": "calendar"
      },
      "content": {
        "tag": "bk-calendar"
      }
    }
  ]
}

Example: Handle communication with multiple event-bus

Let's say we have two layouts with different CRUD clients and we'd like to scope them on different channels

• a couple of Buttons must have the same bus of the Layout Swap to swap layouts
• a Table must talk with an instance of a CRUD Client
• a Calendar must talk with another instance of a CRUD Client

That summarizes to

{
  {
    "tag": "bk-button",
    "properties": {
      "content": "Go to Table",
      "action": {
        "type": "event",
        "config": {
          "events": {
            "label": "layout/change",
            "payload": {
              "layout": "table"
            }
          }
        }
      }
    }
  },
  {
    "tag": "bk-button",
    "properties": {
      "content": "Go to Calendar",
      "action": {
        "type": "event",
        "config": {
          "events": {
            "label": "layout/change",
            "payload": {
              "layout": "calendar"
            }
          }
        }
      }
    }
  },
  {
    "tag": "bk-crud-client",
    "properties" {
      "reflectToUrl": false,
      "eventBus": "eventBus.pool.table",
      "basePath": "/table-base-path",
      "dataSchema": {
        "type": "object",
        "properties": {
          "_id": {"type": "string"}
        }
      }
    }
  },
  {
    "tag": "bk-crud-client",
    "properties" {
      "reflectToUrl": false,
      "eventBus": "eventBus.pool.calendar",
      "basePath": "/calendar-base-path",
      "dataSchema": {
        "type": "object",
        "properties": {
          "title": {"type": "string"},
          "startDate": {"type": "string", "format": "data-time"},
          "endDate": {"type": "string", "format": "data-time"}
        }
      }
    }
  },
  {
    "tag": "bk-layout-swap",
    "properties": {
      "layout": "table"
    },
    "content": [
      {
        "tag": "div",
        "attributes": {
          "slot": "table"
        },
        "content": {
          "tag": "bk-table",
          "properties": {
            "eventBus": "eventBus.pool.table",
            "dataSchema": {
              "type": "object",
              "properties": {
                "_id": {"type": "string"}
              }
            }
          }
        }
      },
      {
        "tag": "div",
        "attributes": {
          "slot": "calendar"
        },
        "content": {
          "tag": "bk-table",
          "properties": {
            "eventBus": "eventBus.pool.calendar"
          }
        }
      }
    ]
  }
}

Notice how the eventBus property is used to appropriately scope communication channels between components.

info

reflectToUrl property is used to prevent the CRUD Client instance from writing to the URL at the same time, which may cause clashing.

API

Properties & Attributes

property	attribute	type	default	description
layout	bootstrap-layout	string	-	default layout to view on landing and then current layout

Listens to

event	action
layout/change	requires the connection of the layout which is referenced in the event payload

Emits

None