Layout Customizer Integration - Layout and Permissions - v0.4

This page describes the two JavaScript objects require to initialize and work with the Layout Customizer component. For specific information about the Layout Customizer API, see Layout Customizer API - v0.4.

Organizing chunks of content

The Layout Customizer is a special case of a Reorderer. It can be used to provide the ability to organize arbitrary chunks of content, or "modules," provided they are laid out according to certain guidelines.

The Layout Customizer understands each particular layout that it is working with via two Javascript objects that describe it: the layout object and the dropTargetPerms object. To use the Layout Customizer, you will have to create these objects to pass in on initialization. The format of these objects is described below.

Conceptually, the Layout Customizer considers each content module to be a "child" of its containing column. So in the example to the left, Modules 1, 2 and 3 are "children" of Column 1, and Modules 4 and 5 are "children" of Column 2. The columns themselves must be contained within some form of container.

The Javascript object that describes the layout does so by specifying the IDs of the DOM elements and the relationships between them. The format for the layout object for the example on the left is:

var layout = {
    id:"module_container",
    columns:[
        { id:"column_1", children:["module-1", "module-2", "module-3"]},
        { id:"column_2", children:["module-4", "module-5"]}
    ]
};

You may have noticed that we keep saying "potential drop target." This is because the Layout Customizer also allows for some content modules to be "locked," so that they cannot be moved, and other modules cannot move them out of their spot. For example, if Module 1 in our layout were locked, it could not be moved away from the top of Column 1, and equally importantly, other portlets could not be moved into the top spot of Column 1 (because that would move Module 1 out of that spot). If this were the case, the drop target shown above Module 1 would disappear, because that space would no longer be a valid drop target.

The Layout Customizer also allows for modules to have different precedence, which complicates things even more, but we'll leave that topic for later.

Note: If your layout does not include any locked portlets or precedence, you do not need to know about or use the permissions object described below.

Row 0: Permissions for Module 1
The first row of the array (index 0) will describe the permissions for Module 1. Each number in that row corresponds to one of the drop targets (numbered in the diagram to the left).

Since Module 1 is locked an cannot be moved, it does not have permission to move into any of the drop target locations, so every entry in the row will be 0:

var perms = [
  [0,0,0,0,0,0,0], // permissions for Module 1: can't move anywhere
  ...
];

Row 1: Permissions for Module 2
The second row of the array (index 1) will describe the permissions for Module 2.

Since Module 1 is locked, Module 2 cannot be placed above it, in drop target location 0, so the first number in the second row will be 0. Module 1 can be moved to any of the other drop targets, so the rest of the numbers will be 1:

var perms = [
  [0,0,0,0,0,0,0], // permissions for Module 1: can't move anywhere
  [0,1,1,1,1,1,1], // permissions for Module 2: can't move before Module 1
  ...
];

So in this example, Module 4 (precendence 60) could be moved ahead of Module 2 (precedence 50), but not ahead of Module 1 (precedence 80).

Permissions for Module 5
Let's look at the example of Module 5. Because it's precendence is 0, it cannot be placed in targets 0, 1 or 4 because that would place it ahead of a module with a higher precedence. The other targets are free game.

So the row in the array would look like this:

var perms = [
  ...
  [0,0,1,1,0,1,1], // permissions for Module 5
  ...
];