node package manager


How many ways are there to build a button with Assemble? Many.


How many ways are there to assemble a button? This project is an exercise in separation of concerns regarding structure, style, content and data.

The primary goal is to clearly demonstrate how to use Assemble for constructing UI components from templates and data. In general, examples progress from simple to advanced and each example builds upon the previous one, both in terms of features and complexity.


For the purposes of this project let's agree that:

  • component refers to a user interface abstraction, such as a navbar, modal dialog, or (as with the main attraction of this project) a button.
  • style refers to CSS, including pre-processors (here we use LESS, possibly SASS).
  • structure refers to HTML, including templates (here we use Handlebars templates).
  • content refers to any audial (sound), visual (video or images) or textual content that can be experienced directly by the user on a website or web application.
  • data, as distinguished from "content", refers to any data that is used for configuration and will not be directly experienced by the user. So while "Click Me!" would be considered the "content" of a button, any "modifier classes" of the button stored in JSON or YAML would be considered "data". To be pragmatic, sometimes "data" and "content" are clumped together, but we try to differentiate when it makes sense.


Separation of concerns

As a rule of thumb, each example in the project demonstrates a different approach to separating concerns between content, structure and style, and in general each example will build upon the last in order to demonstrate:

  • increasing levels of complexity
  • progressively higher levels of abstraction
  • when applicable, different approaches or conventions for accomplishing the same goal, allowing you to decide what is or isn't "idiomatic" as it relates to your own projects

Not all examples explicitly focus on "separation of concerns" as the sole purpose of the example. Some examples show how to leverage JavaScript helpers alongside advanced templates, some offer alternatives for maintaining metadata about a component, while others are simply intended to help non-programmers get started or to give experienced programmers ideas.

Flow and Philosophy

Examples attempt to progress from "basic" to "advanced" beginning with button-000. If you feel that the buttons are not ordered properly, please let us know. The lower-numbered examples should be more approachable to non-programmers, while the higher-numbered examples might be more interesting to programmers who have more experience with templating frameworks.

Since the project is expressly intended to be instructive, and not opinionated, by necessity some of the examples should not be idiomatic. So no judgement is made regarding how much abstraction is necessary, good, bad, idiomatic or otherwise. Some examples feature very little abstraction, others more, and some of the examples we have planned will demonstrate a radical degree of abstraction.

Some examples will include commentary, which might include suggestions for decreasing abstraction, using a different format to supply data, and so on, but the intent is to offer alternatives for consideration, not to make assersions about which method is best. Ultimately the opinions will be left to you.


Have an idea for an example? Please let us know or consider adding it yourself.

The easist way to show your support for the project is to "star" it.

To add an example, just fork the project, make your changes and do pull request. We only ask that you attempt to number the example appropriately according to the relative level of complexity of the example, using the existing examples as a rule of thumb.

Also, in lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using grunt.


Jon Schlinkert

Release History


Copyright (c) 2013 Jon Schlinkert, and the authors of examples utilized herein.

Licensed under the MIT license.