The page navigation is complete. You may now navigate the page content as you wish.
Skip to main content

AppFrame

GitHub

A layout component used as top-level “frame“ for the application.

How to use this component

The AppFrame is a pure layout component that can be used to build the top-level “frame“ of an application. The frame's child containers (“header”, “sidebar“, “footer“, etc.) are agnostic of the content, and don‘t have intrinsic sizes (apart from the ones that are required to make it work as top-level application frame).

Basic use

The most basic invocation of an application “frame” looks like this:

header
main
footer 
<div class="doc-app-frame-mock-viewport">
  <Hds::AppFrame as |Frame|>
    <Frame.Header>
      {{! your "header" content goes here, this is just a mock placeholder }}
      <Doc::Placeholder @height="60px" @text="header" @background="#e5ffd2" />
    </Frame.Header>
    <Frame.Sidebar>
      {{! your "sidebar" content goes here, this is just a mock placeholder }}
      <Doc::Placeholder @width="120px" @height="100%" @text="sidebar" @background="#e4c5f3" />
    </Frame.Sidebar>
    <Frame.Main>
      {{! your "main" content goes here, this is just a mock placeholder }}
      <Doc::Placeholder @height="100%" @text="main" @background="#d2f4ff" />
    </Frame.Main>
    <Frame.Footer>
      {{! your "footer" content goes here, this is just a mock placeholder }}
      <Doc::Placeholder @height="60px" @text="footer" @background="#fff8d2" />
    </Frame.Footer>
  </Hds::AppFrame>
</div>

Optional containers

Depending on the UI implementation of the product where the component is used, it's possible to omit certain containers simply by not yielding them. For example, this would be the “frame” of an application that doesn't have an “header”:

main
footer 
<div class="doc-app-frame-mock-viewport">
  <Hds::AppFrame as |Frame|>
    <Frame.Sidebar>
      <Doc::Placeholder @width="120px" @height="100%" @text="sidebar" @background="#e4c5f3" />
    </Frame.Sidebar>
    <Frame.Main>
      <Doc::Placeholder @height="100%" @text="main" @background="#d2f4ff" />
    </Frame.Main>
    <Frame.Footer>
      <Doc::Placeholder @height="60px" @text="footer" @background="#fff8d2" />
    </Frame.Footer>
  </Hds::AppFrame>
</div>

Programmatic control of the containers‘ rendering

Using the exposed API of the component, it's possible to programmatically control the rendering of some of the containers. An example of programmatic control of the rendering of the sidebar could be this:

main
footer 
<div class="doc-app-frame-mock-viewport">
  <Hds::AppFrame as |Frame|>
    {{! conditional control of the rendering of the "sidebar" }}
    {{#if this.yourSidebarBooleanFlag}}
      <Frame.Sidebar>
        <Doc::Placeholder @width="120px" @height="100%" @text="sidebar" @background="#e4c5f3" />
      </Frame.Sidebar>
    {{/if}}
    <Frame.Main>
      <Doc::Placeholder @height="100%" @text="main" @background="#d2f4ff" />
    </Frame.Main>
    <Frame.Footer>
      <Doc::Placeholder @height="60px" @text="footer" @background="#fff8d2" />
    </Frame.Footer>
  </Hds::AppFrame>
</div>

If for some reason it's not possible to use conditional logic to control the yielding of the containers, we provide an alternative way using special has[Container] arguments to programmatically control the rendering (see the component API specifications for details):

main
footer 
<div class="doc-app-frame-mock-viewport">
  <Hds::AppFrame @hasSidebar={{false}} as |Frame|>
    <Frame.Sidebar>
      <Doc::Placeholder @width="120px" @height="100%" @text="sidebar" @background="#e4c5f3" />
    </Frame.Sidebar>
    <Frame.Main>
      <Doc::Placeholder @height="100%" @text="main" @background="#d2f4ff" />
    </Frame.Main>
    <Frame.Footer>
      <Doc::Placeholder @height="60px" @text="footer" @background="#fff8d2" />
    </Frame.Footer>
  </Hds::AppFrame>
</div>

Modals container

We also provide an extra container that can be used to display content that sits on top of all the other elements of the page (typically modal elements):

If the “modal“ container is empty, a display: none style is applied to it.

header
modal
main
footer 
<div class="doc-app-frame-mock-viewport">
  <Hds::AppFrame as |Frame|>
    <Frame.Header>
      <Doc::Placeholder @height="60px" @text="header" @background="#e5ffd2" />
    </Frame.Header>
    <Frame.Sidebar>
      <Doc::Placeholder @width="120px" @height="100%" @text="sidebar" @background="#e4c5f3" />
    </Frame.Sidebar>
    <Frame.Main>
      <Doc::Placeholder @height="100%" @text="main" @background="#d2f4ff" />
    </Frame.Main>
    <Frame.Footer>
      <Doc::Placeholder @height="60px" @text="footer" @background="#fff8d2" />
    </Frame.Footer>
    <Frame.Modals>
      {{! your "modal" content goes here, this is just a mock placeholder }}
      <div class="doc-app-frame-fake-overlay" />
      <div class="doc-app-frame-fake-modal">
        <Doc::Placeholder @width="100%" @height="100%" @text="modal" @background="#ffffffb5" />
      </div>
    </Frame.Modals>
  </Hds::AppFrame>
</div>

If the content is injected dynamically—eg. via JavaScript or via Ember "portals"—you can assign an ID to the HTML element so that it can be targeted in the DOM by the code:

<div class="doc-app-frame-mock-viewport">
  <Hds::AppFrame as |Frame|>
    <Frame.Sidebar>
      ...
    </Frame.Sidebar>
    <Frame.Main>
      ...
    </Frame.Main>
    {{! assign an ID to the element to target it in the DOM }}
    <Frame.Modals id="app-frame-modals" data-test-modals-container />
  </Hds::AppFrame>
</div>

Component API

Name
hasHeader
Type
boolean
Default
  • true (default)
Description
Controls the rendering of the header container.
Name
hasSidebar
Type
boolean
Default
  • true (default)
Description
Controls the rendering of the sidebar container.
Name
hasFooter
Type
boolean
Default
  • true (default)
Description
Controls the rendering of the footer container.
Name
hasModals
Type
boolean
Default
  • true (default)
Description
Controls the rendering of the modals container.
Name
…attributes
Description
This component supports use of ...attributes.

Contextual components

The frame's elements acting as containers are passed into the AppFrame as yielded components, using the Header, Sidebar, Main, Footer, and Modals keys.

Name
<[Frame].Header>
Type
yielded component
Description
Optional container that yields its content inside the <header> element.

This sub-component supports use of ...attributes.

Name
<[Frame].Sidebar>
Type
yielded component
Description
Optional container that yields its content inside the <aside> element.

This sub-component supports use of ...attributes.

Name
<[Frame].Main>
Type
yielded component
Description
Required container that yields its content inside the <main> element.

This sub-component supports use of ...attributes.

Name
<[Frame].Footer>
Type
yielded component
Description
Required container that yields its content inside the <footer> element.

This sub-component supports use of ...attributes.

Name
<[Frame].Modals>
Type
yielded component
Description
Required container that yields its content inside a special <div> element that can be used to contain modal elements.

This sub-component supports use of ...attributes.

On this page: