How does the Craft Grid System work?

Question

Plugins are able to extend Craft and embrace the existing UI nicely. While I'm comfortable extending it in many ways, I don't feel like I could clearly explain to somebody else how the grid system works on the back end and have recently seen a few CP UIs rendered on larger screens (2400px+) that suggest that I may not fully understand how it behaves between devices.

After you extend the CP layout:

{% extends "_layouts/cp" %}

You can build a grid using grid, item, and pane classes and various attributes. Here is an example with likely too many attributes just to put several of them out there into the discussion:

<div class="grid first" data-max-cols="3">
  <div class="item" data-position="left" data-min-colspan="2" data-max-colspan="3">
    <div id="fields" class="pane">
      ...
    </div>
  </div>
  <div class="item" data-position="right" data-colspan="1">
    <div class="pane meta">
      ...
    </div>
  </div>
</div>

Here are a few of the questions I wonder about while working with the grid:

• How many columns does the grid support?
• Are there any considerations to keep in mind as our plugin's UI adjusts to mobile layouts or big screens with high resolutions?
• How do data-position="left" and data-position="right" work? When do we need to use them?
• How do the data-colspan attributes work? Are there defaults in place for data-colspan, data-min-colspan, data-max-colspan?
• Are there any other features of the grid I'm overlooking or leaving out?

Answer 1

This is somewhat of a guess, but is based on what I could find. It might not answer everything but it might be a start :)

From what I can work out the grid work is worked out around the values you provide yourself, if you look at app/resources/js/craft.js on line 10244 this seems to be where the grid starts.

On line 10339 is the refreshCols function which seems to be responsible of figuring out how wide items are are where they should be placed.

It looks like Craft will take the values you supply data-max-cols="3" data-min-colspan="2" etc and try to work out the best possible layout (This is where data-position gets dealt with aswell) ...

line 10466
// Figure out all of the possible colspans for each item,
// as well as all the possible positions for each item at each of its colspans
...

line 10532
// Now find the layout that looks the best.
// First find the layouts with the highest number of used columns
....

etc etc, so it looks like there aren't really any set defaults, you just gotta play around with the numbers and see what works best for the layout you are trying to achieve.

Lastly, on line 10775 is:

defaults: {
    itemSelector: '.item',
    cols: null,
    maxCols: null,
    minColWidth: 320,
    mode: 'pct',
    fillMode: 'top',
    colClass: 'col',
    snapToGrid: null,
    onRefreshCols: $.noop
}

I realise I could be looking in the wrong direction and apologies if this doesn't completely answer your question, but hopefully it will provide an insight.