Importing pattern library HTML into your project
The tgam-patterns NPM package contains everything that’s required to create an instance of a given component in your project. Component HTML is distributed in the form of Handlebars templates, so you’ll need to install and configure Handlebars in order to make use of it.
TODO: document how to install and configure Handlebars, and how to register the partials and helpers that are required in order for the templates to compile properly.
Another option is to manually copy and paste component HTML from the pattern library website, directly into your project. This is our preferred workflow, for the time being, primarily because it’s less complex. This may change in the future, however.
Here’s a brief overview of the pros and cons of each approach, as well as some considerations for the future:
Method 1: Importing HTML
Rather than manually copying and pasting component HTML from the pattern library website, our project could import Handlebars templates from the tgam-patterns package and compile them into HTML. Or, perhaps we could add a “Component API” to Panther (a set of functions that return HTML markup). Various arguments would be passed into the Component API functions (i.e. class names, text strings, etc.), which would result in different markup being returned. Lonely Planet employed this strategy with their “Rizzo” engine. Either way, the following pros and cons apply:
Pros
- Maintenance: Easier to maintain because the HTML lives in a single place. Updates are automatically applied to all instances of the code, in every project that uses the pattern library.
- Consistency: Developers are not able to directly modify the code, which means it’s not possible for them to implement patterns incorrectly (i.e. typos, missing classes in the markup). They also aren’t able to create a million subtle variations of a single pattern, which would be difficult to maintain over time.
Cons
- Frustration: Because developers aren’t able to modify the code directly, it’s difficult for them to add things like
ariaanddataattributes to individual instances of patterns. The only way for them to do this is to modify the Handlebars template inside the pattern library codebase, or to modify the Component API function that returns the markup (i.e. add a new argument to the function signature and write some additional logic inside the function body). Another option would be to circumvent the Handlebars template or Component API entirely, by “forking” the pattern (copying and pasting the HTML that the template or function generates and working with that HTML directly).
Method 2: Copying and pasting HTML
Pros and cons
- Developers are free to make subtle adjustments to pattern markup, but must remain disciplined when doing so. Care must be taken not to alter patterns too much, otherwise we could end up with a disparate array of mutated “Frankenpatterns” that are a nightmare to maintain. If a developer encounters a scenario where they need to dramatically alter an existing pattern, then they are free to do so in order to satisfy their short-term requirements. However, they should bring this to the attention of the UX Design team and collaborate with them to design a proper, documented, tested pattern to replace their non-standard solution.