foundation-layout

Layout is a mechanism to manage a coordination among components/elements to look/behave in a certain way.

Markup

[data-foundation-layout]

When foundation-contentloaded event is triggered, the element having data-foundation-layout attribute is processed according to FoundationLayouts.layout.

Selector Rule:

[data-foundation-layout]

Event

foundation-layout-perform

Triggered after the layout is performed. See also Granite.UI.Foundation.Layouts.layout.

Granite.UI.Foundation.Layouts

A singleton object is exposed at Granite.UI.Foundation.Layouts, having the following interface:

/**
 * Layouts is a registry that holds all the layouts.
 * Layout is mechanism to manage a coordination among components/elements to look/behave in a certain way.
 *
 * The recommended way to register a layout is using foundation-registry
 * using "foundation.layouts" name and the config satisfying <code>FoundationLayoutsAdapter</code>.
 *
 * @example
 * $(window).adaptTo("foundation-registry").register("foundation.layouts", {
 *   name: "foundation-layout-mode",
 *   doLayout: function(el, config) {},
 *   clean: function(el, config) {}
 * });
 */
interface FoundationLayouts {
  /**
   * Registers a layout for the given name.
   *
   * @param name The name of the layout
   * @param layouter The function to do the actual layout
   * @param cleaner The function to clean up when the layout is removed
   */
  register(name: string, layouter: Function, cleaner? Function): void;

  /**
   * Performs a layout logic based on layouter function registered.
   * The value of <code>data-foundation-layout</code> attribute of the given element will be used as the layout JSON config,
   * which <code>name</code> property is used as the lookup key of registered layouter.
   * The el and config are passed to layouter function as <code>layouter(el, config)</code>.
   * This method triggers <code>foundation-layout-perform</code> event after performing the layout.
   *
   * @param el The element acts as the root element of the layout
   */
  layout(el: Element): void;

  /**
   * Switches the layout from existing layout to the new one given by newConfig.
   * The old layout is cleaned first by calling {@link #cleanAll}.
   * The new layout is then performed as per {@link #layout}.
   *
   * @param el The element acts as the root element of the layout
   * @param newConfig The config to be used for the new layout
   */
  switchLayout(el: Element, newConfig: FoundationLayoutsConfig): void;

  /**
   * Removes the layout of the given element.
   * It will remove the following from the element:
   * (1) the layout class, based on name
   * (2) the <code>data-foundation-layout</code> attribute
   *
   * @param el The element acts as the root element of the layout
   */
  clean(el: Element): void;

  /**
   * Removes the layout of the given element by calling the cleaner function registered under the layout name,
   * which is defaulted to {@link #clean} when no cleaner is registered.
   *
   * @param el The element acts as the root element of the layout
   */
  cleanAll(el: Element): void;
}

/**
 * The config to configure the layout. The only requirement is the {@link #name} property.
 * Each layout MAY define additional properties. Please consult its documentation accordingly.
 */
interface FoundationLayoutsConfig {
  /**
   * The name of the layout.
   */
  name: string;
}

interface FoundationLayoutsAdapter {
  /**
   * The name of the layout.
   */
  name: string;

  /**
   * The function to do the actual layout.
   *
   * @param el The root element of the layout
   * @param config The config of the layout
   */
  doLayout: (el: Element, config: FoundationLayoutsConfig) => void;

  /**
   * The function to clean up when the layout is removed.
   *
   * @param el The root element of the layout
   * @param config The config of the layout
   */
  clean: (el: Element, config: FoundationLayoutsConfig) => void;
}

Relationship Graph

digraph "foundation-layout" { rankdir=BT; "foundation-layout-control" -> "foundation-layout" [label="controls"]; }