Documentation Level: 
Advanced
Documentation Status: 
Incomplete

Adding a new layout

If you wanted to create a new layout that could be used on specific pages of your site, you would:

  1. Navigate to the Layout list page at Administer > Structure > Layouts
  2. Click the "Add layout" link.
  3. Add a name for your new layout (example: "About Us")
  4. Click on a Layout to select it
  5. Type the path which you want to apply this layout to (example: about-us)

Add Layout

Visibility Conditions

Visibility Conditions are rules which allow you to determine under what conditions parts of the Layout system are allowed to appear. Visibility conditions are found in three different settings:

  • When creating a layout - allows this layout to selectively apply to different situations
  • When managing a menu path - conditions set at the menu level will prevent access to the entire page and all layouts configured in it.
  • When adding a block to a layout - allows this block to be shown only in certain situations

List of available visibility conditions

  • Front Page
  • Site language
  • URL Path
  • User permission
  • User: role
  • User: ID
  • Entity: ID
  • Entity: type

Layout visibility conditions

During creation or editing of a layout, visibility conditions can be added to determine access to the layout. If the user does not have access Backdrop will return a "Page not found" error.

Set multiple layouts on one path using visibility conditions

Multiple layouts can be made on the same path. This may seem unintuitive but is reasonable - because of visibility conditions. Although multiple layouts are on the same path, one may apply if condition A is true while the other when condition A is false. For example, two layouts may be active for your path 'company-details', but one may only show when the site user is anonymous, while the other only shows for other registered  users. This makes it possible to show entirely different sets of blocks and content based on the user role.

If there are multiple layouts at one path, the first one which is not invisible to the user is shown. Layouts can be re-ordered though, to guarantee the order of selection. If no layouts meet the visibility conditions, Backdrop will return a "Page not found" error.

For example, our menu path 'company-details' has three layouts defined:

  • the "Guest layout" is only visible to anonymous users
  • the "Editors layout" only to registered users of role 'editor' and 'executive'
  • the "Executive layout" only to registered users of role 'executive'

If an anonymous visitor attempts to visit http://my-site/company-details, he will only get the first layout, the Guest layout.

If an editor visits, he will only get the Editor layout

If an executive visits he will also get the Editor layout since this is the first layout which is visible. If however the layout order is switched so that the Executive layout is second, the executive will get the Executive layout since this is now the first visible layout.

Menu path visibility conditions

Conditions set on the menu path determine access to the whole path. If we have conditions set on this path a user who does not meet any of the visibility conditions will not have access to that path and will get an "Access denied" error from Backdrop, even if he meets the selection criteria for the individual layouts in this path.

So if for example a visibility condition was set on the 'company-details' menu path so  that only users with site language set to French were allowed access, any English-language visitors, editors or executives visiting this path would get an "Access denied" error. However, French users accessing this path would then have access based on the individual layout-based visibility conditions as described in the previous section.

If an anonymous visitor attempts to visit http://my-site/company-details, he will get an “Access denied” error, since anonymous users don’t have a language set.

If an editor visits, he will only get the Editor layout

If an executive visits he will also get the Editor layout unless we switched the layouts as described above..

Block visibility conditions

During creation or editing of a block, visibility conditions can be added to determine access to the block. If the user does not have access Backdrop will simply hide the block.

Adding a block visibility condition

  1. This example shows how to add conditions to a block, but the process is identical for adding menu level and layout conditions.
  2. Navigate to the layout list page at '/admin/structure/layouts' and click 'edit' on the default layout (or another layout as needed)
  3. Click 'Configure' on the block drop button; the blog edit dialog should open
  4. Scroll down to the 'Visibility conditions' fieldset, click it to expand, then click the "Add visibility condition" link; the Visibility Conditions form dialog should load
  5. In the select list, select a listed condition, for example, "Front page"; the options for this condition should load
  6. Select an option ("Current path is: The front page" for example)
  7. Click the "Add visibility condition" button
  8. Verify that your new condition is now listed
  9. Click "Save configuration" to go back to the layout edit page
  10. Click "Save layout" to save changes

Visit the front page of your site to verify that the block is shown; visit any other page to verify that it no longer shows.

Contexts

Credit to http://www.gizra.com/content/ctools-context-tutorial/

Context is Backdrop's way of letting a block declare to the Layout system if it requires a node or a user or other data source to extract data. If the context is not present Backdrop will then not even bother loading the block

Blocks without satisfied context will not appear in the block list, so a user can’t add them by mistake.

Backdrop has a great feature which allows individual fields from a node to be displayed as separate blocks. These blocks are then available in the Layout UI's "Add block" list as Field blocks. You could identify Field blocks in the block list by their naming format which is the word "Field:" followed by the field name and then the field machine name in brackets, such as "Field: Image (field_image)". But if you went into the Default layout you would find no Field Blocks listed in the block list. Why? Because Field blocks have declared that for them to work, the page must be the display page of a node or some other entity. Since the default layout can be used on any page, that page may not be an entity page, therefore Backdrop hides Field Blocks from the default layout's block list.

If you want to use Field blocks then, you need to create a layout which provides an entity to Field Blocks. Qualifying layouts would be ones where the "path" of the layout is of the format '<entity>/%' for example 'node/%' or 'user/%'. This tells Layouts that this layout must be ready to deliver an entity context to its blocks, where the entity type is the first part of the path (eg 'node') and the entity ID is the second part of the path.

So for a layout with the path 'node/%', visiting the "Add block" page would show those Field Blocks which have required the 'node' entity, such as "Field: Image (field_image)". If this block is placed in the layout sidebar and the layout saved, visiting a path such as 'node/55' would allow this image to be displayed (providing as well an image had actually been uploaded in the Image field, of course) in the sidebar as its own block.

Example: Adding an image Field Block

  1. Create a "Post" type node, give it any name, and type some body content
  2. In the image field, upload an image and save the node
  3. Be sure to recall the new node’s URL (in the address bar)
  4. Now create a new layout by visiting '/admin/structure/layouts' and click "Add layout"
  5. Add a name for the layout and choose any template with a sidebar (any template will do but we like a sidebar for this demo)
  6. For the path, type in 'node/%' without the quotes
  7. Click "Save layout" to be redirected to the blocks page
  8. Now in the sidebar region, click the "Add block" link and search for the image block "Field: Image (field_image)" and insert it into the layout by clicking the "Add block" button. More information about configuring Field blocks is available in the “Configuring blocks: examples” tutorial.
  9. Click "Save layout"

Visit the URL of the node you create in the first step to see that the image is now in the sidebar as its own block