Styling and customising the dock

Revision as of 07:23, 31 May 2010 by Sam Hemelryk (talk | contribs)

Jump to: navigation, search

Moodle 2.0

The dock is a new addition to Moodle 2.0, it allows the user to move blocks from the flow of the page onto a special bar that is displayed in a constant position on the side of the page by default. This document looks at how to style the dock using CSS, as well as how to customise or manipulate it within JavaScript.

Styling the dock

Styling the dock is really no different to styling anything else within a web site however there are a couple of things that may slow you down and reading the following document may help you in your understanding of how the dock works and how you should go about styling it.

The following items are things that you should be aware of before starting to style the dock:

  1. When a block is docked the dock attempts to ensure that existing styles for the block are still applied by adding the standard block .block_blockname. Because of this trick we don't need to look at the actual content of a docked item it will always be the same as the block.
  2. The dock remembers what blocks are docked by saving the user's choices within the database using AJAX calls. This can be looked at to minimise display jumping within a theme's layoutfile. Read on to learn how.
  3. The dock uses CSS classes to transition the different states. These CSS classes control things such as the whether the dock is visible, whether the panel is visible, and how we know which item is being viewed. Read the section on state classes to learn more about these.
  4. The structure of the dock is built entirely by JavaScript. Because of this you will need a tool such as FireBug to inspect it within a page as it won't be there until JavaScript has run.
  5. Although the base theme doesn't support the dock it does contain some core CSS to structure the dock by default.

So lets get started and look at the structure.

The structure of the dock

Dock structure

The first image to the left graphically describes the hierarchical structure of the dock. The first thing you will notice about this image is that it doesn't describe what each element is for. It is just to illustrate the html structure without at styles or transformation.

So what are the important elements here?

This is the bar on the left. Positioned by default to be fixed position in the top left hand corner of the screen and 30px wide.
This box contains all of the buttons which when clicked or hovered over will display the docked item. Or more technically causing the docked item panel to be shown.
This represents one of possibly several docked item buttons containing the title of the docked item. There are two things to note about this element: First it is repeated for every docked item. Second the x within the id is the item instance and should not be used for styling.
This contains any special controls for the dock and by default is displayed at the bottom of the dock. As of Moodle 2 Preview Release the only control here is to undock all docked items.
This is the panel in which docked items are shown. Although it is within the dock is it positioned outside of the page relative to the button for the item it is currently showing. This element is based loosely off the YUI3 overlay.

The layout of the dock

Dock layout

The second image on the left shows the layout of these elements within the standard theme.

So what has gone on here? First up ignore the bright colours and margins. I have put these colours in simply to highlight everything and ensure there is space between elements so I can show them apart.

So immediately you notice that the dock is in the top left of the screen and the is fixed width. This is achieved by setting a strict with of 30px and setting the position of the #dock to fixed. The reason that everything is within the one #dock element is because it makes positioning everything very simple, now that we have set the position of #dock we don't need to worry about anything other than the panel which we'll get to shortly. You should also note that because of the strict width and position you need to be careful when applying styles to this element as it can have nasty effects on everything else.
Next you should notice that the .dockeditem_container doesn't extend to the bottom of the dock. Because there is not special positioning here it is behaving as div's normally do and this is the perfect place to really start styling your dock.
After that within the structure we have div.controls. This element is positioned absolutely at the bottom of the dock, is 100% wide (so the full width of the dock) and uses text-align:center to ensure that the controls are centred.
Simply representing a button that can be hovered over or clicked to display the docked item the only important thing to note about this is that you should change the cursor to a pointer so that it is clear you can interact with it.
After #dock this is the most serious element in the dock. This element will contain the docked item and needs to positioned to the left of the dock and at the same height as the title of the item that is being displayed. Luckily you don't need to worry about the top position of the element that will be automatically adjusted by JavaScript however you will need to push the element to the left. This can be done easily by setting the position of the element to relative, and then setting left to 100%. Note you shouldn't style this element unless you know what you are doing, like the main dock element the smallest change can cause some terrible effects.
This element is there specifically to give you the themer an easy place to start styling the panel.
This element contains the title of the docked item plus controls to undock or close it.
Contains is the main content area for the panel.

State classes

There are several state classes that the dock makes use of to achieve things such as the visibility of the dock, visibility of the panel, and which item is active. The following table illustrates where these state classes are used.

Element Class Description Default CSS
body has_dock This class is added to the body element when the dock is visible. Margin-left: 30px
#dock nothingdocked This class is added to the dock when there is nothing docked. visibility: hidden; display: none;
#dock .dock_position_style A special class is added to describe the docks desired position e.g. dock_left_vertical
.dockeditem activeitem This class is added to the item that is currently being shown. Change the background colour
.dockeditem firstdockitem This class is added to the first dock item.
.dockeditem h2 filterrotate Added when the title is being rotated by an IE filter [Internet Explorer only]
#dockeditempanel dockitempanel_hidden Added to the panel when it is not being shown. visibility: hidden; display: none;
.dockeditempanel_content oversized_content Added when the panel required scrolling to show everything. Set the overflow method

The core CSS

What to keep in mind when styling the dock

Customising the dock

Where to start

Extending the dock through events

Using custom methods for the dock

More information