This documentation refers to the v0.4 released version of the Layout Customizer code. For documentation specific to the trunk, please see Layout Reorderer Selectors Tutorial.
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.
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.
The Layout Customizer works with modules of content that are organized into columns, as in the image below. In this example, we have five content modules organized into two columns: three in the left column and two in the right.
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.
Let's look at this object in more detail:
The layout object contains two members:
id member is simply the ID of the main container. In this example, let's say that's
columns member is itself an object that describes the columns and their contents. It is an array, where each element in the array is in turn an object that describes one column. In our example, we have two columns, so the array has two rows, each containing an object:
The object in each row has two members,
children. Since each of these object describes one column, the
id member is the ID of that column. The
children member is an array of the IDs of all of the children of that column. In our example, the first column has three children (modules 1 through 3), so the object describing it looks like this:
In the snippet above, the object has been spread out over a few lines to make it easier to see, but it's the same as in the earlier snippets.
The term "drop target" here refers to the place where a module can be move to, or "dropped":
- There is one drop target before each module.
- There is one drop target at the bottom of each column.
The drop targets for our example are shown by the red markers in the diagram below.
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.
Drop Target Permissions
- each row describes the permissions for one module, i.e. the first row describes where the first module can or can't go
- each column in that row describes the permissions for one of the drop targets, i.e. the first column refers to the first drop target, the second column refers to the second drop target, etc.
Let's look at an example in detail: Suppose Module 1 in our two-column example is locked. This means that it cannot be moved out of the top position in Column 1, and nothing can be moved above it in Column 1.
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:
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:
Modules with Varying Precendence
The Layout Customizer also allows users to give module different precedence. Modules cannot be moved ahead of a module with a lower precedence.
Let's look at an example: The diagram below shows our example layout with various precedences. The higher the number, the higher the precedence (and if nothing is said, precedence is 0).
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: