Hacking Patternlab (draft)

This is a quick overview of what happens when compiling patternlab patterns, so new developers can get a grip of the code more easily.

Lets start in lib/patternlab.js with the build() method at the bottom of the file:

buildPatterns(deletePatternDir);
new ui().buildFrontend(patternlab);

This would initially build all the patterns on the first run (empty public folder). If running gulp or grunt with the patternsonly task, then the UI (and with that the View All pages) is not rebuilt.

buildPatterns(false)

1. Load the graph (PatternGraph.loadFromFile()). Note that this does not fill anything in patternlab.patterns! We would need to serialize the pattern objects for that, too.

Currently this means that only the COMPILE_STATE is loaded for each pattern. 2. Now various templates files are read into the patternlab object, including the viewAll template 3. processPatternsIterative is called, which in turn calls pattern_assembler.process_pattern_iterative(path.relative(patterns_dir, file), patternlab);. This will load/resolve:

- Pseudopatterns and various other JSON
- `template` (the template contents), `stylePartials`, `parameteredPartials`
- the `compileState`
- any pseudopatterns (PP) (calling `pseudopattern_hunter.find_pseudopatterns(currentPattern, patternlab);`, discovering PP lineage and add the pseudo-patterns to the `patternlab` object)

for each Pattern. 5. Back to buildPatterns(false):528, processAllPatternsRecursive(pattern_assembler, paths.source.patterns, patternlab); is called, effectively calling pattern_assembler.process_pattern_recursive(path.relative(patterns_dir, file), patternlab); -> pattern_assembler.decomposePattern(pattern, patternlab). - This may recursively expand any partial templates if specified by the template engine resposible for the pattern - find any pattern lineages via lineage_hunter.find_lineage(pattern, patternlab); - finally adds the pattern to the patternlab object, if not existing yet. 6. Back to buildPatterns(false): Process global head and foot pattern, parse data links, cascade pattern states and render head/foot. 7. If incremental builds are enabled, patternsToBuild = [modifiedPatterns], otherwise (e.g. cleanPublic = true), mark all patterns in the patternlab for rebuild 9. for each pattern, call renderSinglePattern(pattern, head) 10. - if (!pattern.isPattern || pattern.compileState === CompileState.CLEAN) { do nothing - set compileState to BUILDING - merge global data (data.json) and pattern data - render pattern header - render the pattern itself into patternPartialCode via pattern_assembler.renderPattern(pattern, allData) - :410 render footer with pattern data. This includes the meta data for the pattern for the UI - writePatternFiles(headHTML, pattern, footerHTML); - Mark pattern compile state as CLEAN

11. Finally store the graph.
12. Export the patterns if necessary

So what happens is that when compiling only changed patterns, the patternPartialCode is empty for all other patterns!

ui_builder.buildFrontend(patternlab);

Back to patternlab.build(), new ui().buildFrontend(patternlab); is called, which does not know of anything graph-like yet.

The constructor does nothing and returns an object instead of this!

1. call resetUIBuilderState:

/**
 * Reset any global data we use between builds to guard against double adding things
 */
function resetUIBuilderState(patternlab) {
  patternlab.patternPaths = {};
  patternlab.viewAllPaths = {};
  patternlab.patternTypes = [];
}

2. render user head and foot (again!), merge with gloabl head/foot

3. Find all pattern groups

   For each pattern in patternlab.patterns

   1. addPatternType: add the group any a list of patterns in the group to patternlab.patternTypes, forming a menu group
   2. addPatternSubType to the same for pattern.patternSubGroup
   3. effectively aways call addToViewAllPaths, which adds the pattern to patternlab.viewAllPaths[group][subgroup].items and an all path to the pattern.patternType
   4. add the pattern to the group ("the menu in the UI")

4. buildViewAllPages(headerHTML, patternlab, styleguidePatterns); where styleguidePatterns are the pattern groups

   For each group

   1. For each subgroup in that group

      1. Build viewall footer
      2. Sort subtype patterns
      3. viewAllHtml = buildViewAllHTML(patternlab, subtypePatterns, patternPartial);. This renders the View all HTML of the subgroup with the styleguidePatterns as partials. This unnessecarily re-renders all the patterns in the current "View All" page within the render engine. We already compiled these before and have the contents on disk! The difference could be in the data, how does that even work?

   2. Back to the group (not subGroup)

   3. render footer

   4. buildViewAllHTML for the group

   5. write HTML to disk

   6. return a list of all patterns in the group