JSDoc: Namespace: caplin/layout

Namespace: caplin/layout

caplin/layout

The layout package provides a service to manage layouts in a single page web application. The module:caplin/layout/LayoutService interface defines the methods that are available to you, and you can access the service through the caplin.layout-service alias. There is currently no default implementation for the layout service.

The package also contains tools for testing code that uses the layout service. You can use the caplin.layout.testing.LayoutModelFixture in acceptance tests to test how an application interacts with the layout service. There is also a workbench tool caplin.layout.workbench.LayoutManagerWorkbenchTool that visually displays how code interacts with the layout service and provides fine-grained control over the workings of the layout service.

A new layout can be created using module:caplin/layout/LayoutService#openNew. Calling openNew with no arguments creates an empty layout which can optionally accept a module:caplin/layout/LayoutTemplate. The newly created layout will be based on the accepted layout template: a list of available templates can be accessed using module:caplin/layout/LayoutService#getTemplates.

There are three different methods for accessing existing layouts:

module:caplin/layout/LayoutService#getAvailable: A list of all saved layouts the user has.
module:caplin/layout/LayoutService#getOpen: A list of layouts the user currently has open in the application.
module:caplin/layout/LayoutService#getSelected: The user's currently selected layout.

The API also provides several methods for managing a layout's lifecycle:

module:caplin/layout/LayoutService uses emitr and provides events for the monitoring of layouts' lifecycles. See module:caplin/layout/LayoutService#EVENT_NAMES for more information on the available events.

A module:caplin/component/Component can be inserted into a layout using module:caplin/layout/Layout#insertComponent

and changes to those layout can then be saved using module:caplin/layout/LayoutService#save and module:caplin/layout/LayoutService#saveAs.

Here are some example uses of the API:

var layoutService = caplin.core.ServiceRegistry.getService('caplin.layout-service');

// get a list of currently open layouts
var openLayouts = layoutService.getOpen();

// get a list of available layouts
var availableLayouts = layoutService.getAvailable();

// add a listener to the layoutService for the opening of layouts
layoutService.on(caplin.layout.LayoutService.EVENT_NAMES.OPENED, function(layout, index) {
    // add the layout to our list of open layouts
    openLayouts.splice(index, 0, layout);
    // log some details about the opened layout
    console.log('Opened:', layout.getName(), index);
});

// open an existing layout
var myLayout = availableLayouts[0];
layoutService.open(myLayout);

// insert a component into the layout
myLayout.insertComponent(myComponent);

// save the layout
layoutService.save(myLayout);

// create a new empty layout
layoutService.openNew();

// save a layout with a new name
var myNewLayout = layoutService.getSelected();
layoutService.saveAs(myNewLayout, "My New Layout");

// close a layout
layoutService.close(myNewLayout);

// delete a layout
layoutService.dispose(myNewLayout);