Layout dynamimic JS API

The JavaScript API is accessed through the methods on the root layout object and allows for saving/loading the layout state, and dynamically adding items to the layout at runtime.

@customElement({
  name: 'my-layout',
  template: html<MyLayout>`<rapid-layout ${ref('layout')}></rapid-layout>`,
})
export class MyLayout extends GenesisElement {
  layout: FoundationLayout; // notice the TypeScript type is `FoundationLayout`
  doSomething() {
    this.layout.addItem( ... ) // access the layout imperatively
  }
}

Before discussing this API, it's useful to understand a number of concepts.

Dynamic registration and adding items

To have a pane displayed on the layout system, it must be registered with the layout system. When using the declarative API, the layout system takes care of this for you, but as you start to add items dynamically and then serialize the layout, you need to consider which panes are registered. See this contained example, which allows the user to add pre-determined items to the layout dynamically.

tip

If you are only using the declarative API, and not using any dynamic integrations with JavaScript, then you do not need to set the registration names of any items, as all the same items will be registered when you load a previously saved layout. If you are dynamically adding items as well, it is highly recommended that you set the registration names of items manually. This makes it easier to figure out what is and is not registered.

• When using the declarative API, use the registration attribute on the <foundation-layout-item> component.
• When using the JavaScript API, set the registration optional parameter on the registered element config.

Saving and loading layout

You can use the JavaScript API to save and load layout states manually. This only describes the state of the dynamic layout itself. It is the responsibility of each component within the layout to serialize its own state, if required. To enable autosaving the layout see here.

Methods

For more information on the methods in the table below, see the Methods section of the API docs.

Method	Modifiers	Description
addItem(config, placement)		Dynamically add a new item to the layout. The user can move the new plane to whenever they want once it has been added.
getLayout()		Gets a minified string containing the config describing the current layout of the layout object to later restore in function
layoutRequiredRegistrations(layout)	static	Gets all the required element registry function names for a set of config; see the tip below
loadLayout(layout, handleMissingItem, disableCache)		Restores a layout described in the config from getLayout()
registeredItems()		Gets all the currently registered names
registerItem(registration, elements)		Register a collection of Element and associate them with an ID with the layout system for later use.
removeItems(registration, force)		Removes all instances of a specified registered item from the layout.
tryActivatePopoutMode()		(BETA) If in a popout window from the dynamic layout, this function will run the flow to put the component in popout mode. This function is automatically called if using the declarative HTML API; if you are only using the JavaScript API, then you must call this function manually.
tryLoadLayoutFromLocalStorage()		Try to load a layout from local storage, or return false. Only required if manually calling FoundationLayout.registerItem()

tip

To get all the currently registered names, use registeredItems(). Do not use .layoutRequiredRegistrations(layout: SerialisedLayout) for this purpose, because it does not pick up items that are currently registered with the layout system, but which are not shown on the layout.