Child pages
  • Layout Customizer Integration - Layout and Permissions - v0.4

Documentation for a historical release of Infusion: 1.3
Please view the Infusion Documentation site for the latest documentation.
If you're looking for Fluid Project coordination, design, communication, etc, try the Fluid Project Wiki.

Skip to end of metadata
Go to start of metadata

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.

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.

On this Page
Still need help?

Join the fluid-talk mailing list and ask your questions there.

Layout

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.

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"]}
    ]
};

Let's look at this object in more detail:

The layout object contains two members: id and columns. The id member is simply the ID of the main container. In this example, let's say that's module-container.

The 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:

columns:[
    { id:"column_1", children:["module-1", "module-2", "module-3"]},
    { id:"column_2", children:["module-4", "module-5"]}
]

The object in each row has two members, id and 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:

{
    id       : "column_1",
    children : ["module-1", "module-2", "module-3"]
}

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.

Drop Targets

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

So now that you understand the notion of a drop target, we can get to the subject of the drop target permissions object itself. The Javascript object that describes the various drop target permissions is a two-dimensional array of binary numbers (i.e. 0s and 1s) where

  • 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.

Locked Modules

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:

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
  ...
];

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:

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