Aikau Mini Examples - Horizontal Layout

[ddraper]

Introduction

This is one post in a series of short examples of things that can be done using the Aikau framework. The series is not intended to provide complete documentation but simply to show how to solve frequently encountered problems, implement repeating UI patterns, show case how to use existing widgets or how to create new ones.

Real World Use Case

There are many occasions where you might want to have a row of user interface components where you want each component to either retain the same width or dynamically adjust its dimensions as the browser window is resized. A typical example might be where you want a fixed with navigation sidebar and a dynamically resizing view port.

This isn't easily achievable with CSS and normally requires some JavaScript intervention. The Aikau alfresco/layout/HorizontalWidgets module make it easy to achieve these types of layout in a declarative and reliable fashion.

Simple Example

In this example we’re going to create a row of titled windows where each is configured with a slightly different width behaviour.

Fixed Widths

First lets define a widget with a fixed width:

var fixedWidth = {
  name: 'alfresco/layout/ClassicWindow',
  widthPx: '300',
  config: {
    title: 'Always 300px'
  }
};‍‍‍‍‍‍‍

The important thing to note here is that the width is defined outside of the “config” object. This is because it is an attribute relevant to the parent widget (the alfresco/layout/HorizontalWidgets instance) and not the widget itself). By specifying a “widthPx” attribute we are setting a fixed width that should not change as the window is resized.

Percentage Widths

Now let’s define a widget with a dynamic width:

var dynamicWidth = {
  name: 'alfresco/layout/ClassicWindow',
  widthPc: '50',
  config: {
    title: '50% after fixed deductions'
  }
};
‍‍‍‍‍‍‍

This time we use the “widgetPc” attribute to set a percentage as the width. This will be a percentage of the available horizontal space after all fixed width widgets and widget margins have been deducted - it is not a percentage of the full window or parent width.

Automatic Widths

Now let’s define a couple more widgets that will automatically be assigned a width:

var auto1 = {
  name: 'alfresco/layout/ClassicWindow',
  config: {
    title: 'Share remainder'
  }
};

var auto2 = {
  name: 'alfresco/layout/ClassicWindow',
  config: {
    title: 'Share remainder'
  }
};


‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Neither of these widgets use the “widthPx” or “widthPc” attribute so will automatically be given an even share of whatever space is remaining after all fixed widget widths, widget margins and calculated percentage widget widths are deducted.

In this case because we have defined a width with a percentage width of 50% each of these widgets should get 25% of the remaining space after the other deductions are made.

Widget Margins

Finally, lets add all of the widget definitions into an “alfresco/layout/HorizontalWidgets” instance and give each widget a left and and right margin of 5 pixels:

model.jsonModel = {
  widgets: [
    {
      name: 'alfresco/layout/HorizontalWidgets',
      config: {
        widgetMarginLeft: '5',
        widgetMarginRight: '5',
        widgets: [ fixedWidth, dynamicWidth, auto1, auto2 ]
      }
    }
  ]
};‍‍‍‍‍‍‍‍‍‍‍‍

Example In Action

This is defined in a JavaScript controller for a WebScript mapped to the /horizontalLayout URL. When deployed to a Share (or any Surf based Aikau application) this can be accessed by the URL: http://localhost:8081/share/page/dp/ws/horizontalLayout

This video shows it in action.

This entire example can be downloaded here for you to try out. Simply drop the JAR into your 'share/WEB-INF/lib' directory and restart the server.

Download a PDF version of this here.