API REFERENCE

Mui Layout API

Layout is the entry point to build your layout. If you use ES6 with npm, you can write import Layout from '@mui-treasury/layout'.


Overview

Layout from @mui-treasury/layout is a function that return LayoutBuilder interface.

Interface

type Layout = (config?: LayoutConfig) => ILayoutBuilder;

Layout can accept initial config, this is useful when you want to use config file like JSON for different environments. It is recommended to use configuration API below and then call scheme.getJSON to generate JSON file.

Usage Example

import Layout from '@mui-treasury/layout'

const scheme = Layout()

scheme is a layout builder that can configure different part of layout such as Header, EdgeSidebar, InsetSidebar and many more.

Layout builder API





  • scheme.clone : get a snapshot of layout config at the time it is called.


  • scheme.debug : debug current layout config, log to console as table.

For Content and Footer, there is no need to configure because it is auto generated and there is no promising feature for them at this point. So to make it simple, you can just import the components and that’s it.

import styled from 'styled-components';
import { getLayoutComponents } from '@mui-treasury/layout';

const { Root, Content, Footer } = getLayoutComponents(styled)

const App = () => {
  return (
    <Root scheme={yourScheme}>
      <Content>...</Content>
      <Footer>...</Footer>
    </Root>
  )
}

enableAutoCollapse

If your layout has Permanent or Persistent EdgeSidebar with collapsible: true, you can enable autoCollapse using this function. It accepts 2 parameters, sidebarId and a breakpoint

Interface

type enableAutoCollapse = (
  sidebarId: string,
  breakpoints: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
) => void;

Usage

scheme = Layout()

scheme.configureEdgeSidebar(builder => {
  builder
    .create('primarySidebar', { anchor: 'left' })
    .registerPersistentConfig('sm', {
      width: 256, // recommended width
      collapsible: true,
      collapsedWidth: 64,
      headerMagnetEnabled: true,
      persistentBehavior: 'fit'
    });
  // you can register more breakpoint, if needed.
});

scheme.enableAutoCollapse('primarySidebar', 'md')

After your app mounted to DOM, there is a hook inside layout that will check the current viewport. If it appears that the current viewport is <= breakpoint specified in the function, sidebar will collapse. Next, when viewport changes, hook will recalculate and uncollapse the sidebar if viewport > breakpoint or collapse if viewport <= breakpoint

clone

This function will snapshot the config at specific point. Mostly, you might want to call this fn outside of react component so that you can make sure that it is not changed at every render and then use it other place.

scheme.configureEdgeSidebar(builder => {
  builder
    .create('primarySidebar', { anchor: 'left' })
    .registerPersistentConfig('sm', {
      width: 256, // recommended width
      collapsible: true,
      collapsedWidth: 64,
      headerMagnetEnabled: true,
      persistentBehavior: 'fit'
    });
  // you can register more breakpoint, if needed.
});

// result from debug() won't change even though you register more config
scheme.configureHeader(builder => {
  builder
    .create('appHeader')
    .registerConfig('xs', { position: 'sticky' })
});

const snapshot = scheme.debug() // snapshot an object of layout config

scheme.debug() // snapshot a new config

const OtherComponent = () => (
  <div>{JSON.stringify(snapshot.header)}</div>    
)

Because it use JSON.parse(JSON.stringify(…)), so every time you call debug() you will get a new object.

getJSON

In case you want to move configuration into a config file, call this function and copy to your config.json. Then import that file and pass as initial value to Layout

import Layout, { Root } from '@mui-treasury/layout';
import config from 'path/to/config.json';

const scheme = Layout(config)

const App = () => (
  return (
    <Root scheme={scheme}>...</Root>
  )
)

However if you need to change config based on url or some local state, you need to do it at client side (inside react component).

This is an example result in console. image

debug

This function is a handy utils when you want to debug your layout config at certain time. It print config as table like this.

image

Because it use JSON.parse(JSON.stringify(...)), so every time you call debug() you will get a new object.