MODX with Twitter Bootstrap

By David Walker (Google profile)

Twitter Bootstrap is a handy user interface framework which provides "simple and flexible HTML, CSS, and Javascript for popular user interface components and interactions". And like most things Web, it plays very nicely with MODX.

The easy way: Theme.Bootstrap

MODX user Basil Naumkin aka Bezumkin has provided the absolute quickest way to get Bootstrap into MODX. His Theme.Bootstrap creates a Bootstrap layout for you and also does some nice things with the Wayfinder and Breadcrumb add-ons (of which more below).

The longer way: Bootstrap CSS as resources

The other way to integrate Bootstrap into MODX is to turn Bootstrap's CSS files into resources. This is particularly worth doing if you plan on creating a number of MODX sites. Indeed, in many cases it's worth putting your CSS in a MODX resource even if you don't use Bootstrap. Once the CSS is in one or more resources, you can re-use your work over and over again and change it very easily.

You can turn several CSS files into one.
You can reorganise your CSS files without having to change references – just refer to the stylesheets with the [ [~XXX] ] syntax.
You can replace colours, sizes, fonts and even repeated CSS patterns (such as gradient boxes) with chunks. This gives you write-once, display-everywhere for much of your styling.

To start the process, import the Bootstrap CSS and JavaScript. Then turn the CSS files into MODX resources with:

A new resource of content type "CSS".

You can use the name "bootstrap" or something else.
MODX will automatically add the ".css" file extension to your resource alias.
Ensure the resource has "Hide from menus" ticked.

A new CSS template containing just [ [*content] ].

The Bootstrap JavaScript files are best left as files somewhere in the assets folder; there's nothing much gained from putting them in MODX's database.

The MODX manager now uses Google Minify to automatically compress the CSS and JS in the manager, so you needn't worry about the .min versions of the CSS and JavaScript.

Bootstrap with chunks

Once Bootstrap is imported, you can go about replacing Bootstrap's existing colours, sizes, fonts and repeated CSS patterns with chunks. Use a search-and-replace tool like NotePad++.

Additional CSS

You will almost certainly have some CSS of your own to add. Try to keep all additional CSS away from the Bootstrap CSS in one of two ways:

Create a separate CSS file and reference it after your Bootstrap CSS file in your HTML templates. That way, anything you create that is inconsistent with Bootstrap's CSS will override it. When two CSS files referenced in the same HTML page, the latter reference overrules the former.
Put your additional CSS in chunks and reference them in your CSS template. Put the chunk references after the main content, because if two CSS rules are in the same file, then all else being equal, the latter overrules the former.

If your additional CSS is in chunks, then you'll have a single CSS file. If your extra CSS is in its own file, you can use getResources to combine them. Either way, you'll end up with a single MODX stylesheet, which will minimise HTTP requests to the server and help your pages load faster.

Keeping MODX layout portable and reusable

Elements in categories

By keeping all your sub-categories within a single major category, you will make it as easy as possible to duplicate your MODX site through the use of tools such as myComponent.

Property sets

MODX snippets and other elements have property sets associated with them – collections of values that can be configured and referenced. If you don't know about these, it's worth learning, because they give you the maximum flexibility and ability to upgrade without overriding your previous work.

The best way to change snippet-related layout is often to duplicate the default property set for that snippet, rename it, and write a bunch of new layout chunks. These chunks are traditionally called tpl chunks and have names starting with "tpl". Then you can change the references within your new property set to point to new tpl chunks. Finally, you invoke the new property set in your snippet call using the @PropertySetName syntax.

Wayfinder, BreadCrumb, Articles, SimpleSearch and getResources/getPage

Now you can exploit Bootstrap's clever and flexible layout in conjunction with some of MODX's most important snippets.

WayfinderX: Use Bootstrap Nav and Booststrap Navbar to create menus. You can just create new tpl chunks (tplWayfinderRow andtplWayfinderRowInner) and reference them in your snippet call.
BreadCrumb: Use Bootstrap Breadcrumbs to style the breadcrumbs. You can create new tpl chunks and reference them in your snippet call. However, since BreadCrumb 1.3.0, to change containerTpl will require you to create a new property set. (Note also that Breadcrumb by ben_omycode is a different add-on to the original Breadcrumbs - with an "s" - by splittingred.)
SimpleSearch: Use Bootstrap Pagination to style the results pagination. As with Wayfinder, to get search results from SimpleSearch you can simply create new tpl chunks and reference them in your snippet call. However, SimpleSearch does things in yet another way: its default layout elements are hard-coded into the snippet, but new layout elements will replace them when you add named chunks, such as pageTpl, or just by referencing the layout markup in a snippet call. See the SimpleSearch documentation.
Articles: You'll probably want Articles pagination in an Articles Container to be the same as other pagination. Bad luck. Articles uses yet another technique to deliver pagination – fields for different pieces of markup, entered in a tab on the Articles Container page. The container for all this markup is sadly hard-coded in Articles (discussion here). The result is that you'll need to:

Include in your stylesheet CSS for a UL with a class of "pagelist", and several other items beside. You can simplify the task by copying and renaming the 1KB of CSS from Bootstrap's "pagination" classes.
Add CSS to your stylesheet to style the Articles tag listings.
Add a CSS class in the "Archives" sub-tab of the Articles Container page to style the Articles archive listings.

getResources/getPage: Style as for Articles if you have used Bootstrap-styled Articles elsewhere.

Finding it all too hard? Use Theme.Bootstrap, or download it and use its navigation chunks.

CSS with Less

Bootstrap uses the Less CSS preprocessor to speed up the creation of stylesheets. But MODX already allows us to do a lot of what Less does, through the technique described above.

There are two good arguments for using Less, though, one weak and one strong.

Less lets you do maths. You could do that with MODX and PHP, but only after lots of work. Counterargument: you don't really need much math in CSS layouts anyway. I get colours from a colour wheel, not just by mechanically changing hue, saturation and brightness.

The stronger argument is that Less will let you produce semantic markup for Bootstrap. See the discussion at the Bvision blog:

"... along with Bootstrap has emerged an ugly, insidious and destructive developer antipattern: embedding Bootstrap's CSS classes directly in HTML. Not just end-developers: nearly every library that implements support for Bootstrap does it. Twitter's documentation, in fact, encourages you to do it, even though other frameworks realized this was a problem as far back as 2009.

"First of all, by embedding appearance-oriented code into our HTML, [we remove] the benefits of keeping code in separate layers for content, presentation and behavior: by structuring HTML around what content means, rather than how it looks, you can later change the way it looks without having to edit both the HTML and the CSS.

"The second problem is this: by hard-coding Bootstrap's class names into your HTML, you're marrying your code to Bootstrap. Bootstrap's very name should indicate that developers should consider it a starter library: something to get you out the gate faster, not your permanent design solution."

This view has a lot to recommend it. You can turn Bootstrap classes into semantic classes pretty easily. In practice, though, the people most attracted to Bootstrap so far are developer types who don't really need to change much from the standard Bootstrap defaults. Most Bootstrap sites have a family look to them.

Bvision offer a solution to Bootstrap's non-semantic code that you implement via Less. Not everyone sees Bootstrap's non-semantic markup as a huge problem, though. In truth, most of my semantic-ness now happens in a collection of MODX chunks. The Bootstrap HTML around them is made semantic wherever I have time to do it, but I'd be hard-pressed to cost-justify even the minimal time it takes to make the changes.

Pop-up image gallery with Bootstrap and TinyMCE

Want to put have users put thumbnails in their pages and then pop up a larger version of the image? Bootstrap Image Gallery lets you leverage Bootstrap's existing modal dialogue to create this effect and integrate with the rest of your Bootstrap-modified look-and-feel in the process. See an example.

A few little tricks:

Instead of using DIVs around your thumbnail image, you can also use SPANs – useful if you want to float an image in the corner of a paragraph.
Or you can simply put a "gallery" attribute in the DIV tage that encloses the whole content area.
The link to your modal dialogue needs 'rel="gallery" '. You can add REL attributes in the "Relationship page to target" dropdown in the "Advanced" tab of the TinyMCE editor's link editor. But "Gallery" isn't an option in that dropdpwn. You'll need to manually edit the list of available options in the appropriate MODX TinyMCE plugins files at \assets\components\tinymce\jscripts\tiny_mce\plugins\modxlink\link.htm.