Thursday, May 30, 2013

Boilerplates and Builders in TYPO3 Neos

I will edit this article to edit the In-Scope and Out-of-Scope sections as needed. I wanted to publish this sooner rather than later.

GSoC Deliverables

In-Scope for this GSoC

I plan to deliver the following packages:
  • TYPO3.BuilderAbstract
  • TYPO3.TemplateBuilder
  • TYPO3.ZurbBoilerplate
  • TYPO3.BootstrapBoilerplate
Important features / components:
  • RoundTripService (very basic)
    • TemplateBuilder ties into the Fluid parser
  • MigrationService (very basic)
  • Backend Package Manipulation
    • Copy boilerplate package contents into a Deriative package
  • Boilerplate Configuration in YAML
    • Options layer that allows for multiple "presets" (like in TYPO3.Form). In the context of the TemplateBuilder, those "presets" should be exposed in the UI as a "theme" layer of options.
    • File manipulation indicators (a way to say that you inserted a fluid widget at a particular point in a template. These will be stored in the YAML files as Eel/FlowQuery because XPath only works for XML, and we will work with more than XML)
  • Fluidify SourceTemplates in TemplateBuilder (the backend for something like TemplaVoila)
Note: These are the names I prefer right now, though they've gone through several iterations. If these are not clear, please let me know. TYPO3.BuilderAbstract used to be called TYPO3.Boilerplate. TYPO3.TemplateBuilder used to be called TYPO3.FluidBuilder. SourceTemplates used to be called RawTemplates, NakedTemplates, or NakedBoilerplates.

Out-of-Scope for this GSOC

I will not have time to work much, if at all, on these:
  • Anything that works with TypoScript
  • Much of the UI (may be partially working thanks to TYPO3.Ice - but that's not my focus)
    • Including the TemplaVoila-like UI to select the various parts of a SourceTemplate file

Package Dependencies

Diagram of Package Dependencies
Boilerplates depend on the Builder that understands the files in them. Builders depend on the BuilderAbstract.
Builders extend the basic package manipulation of BuilderAbstract to handle particular filetypes
(eg TemplateBuilder handles Fluid files, and eventually will deal with SASS/LESS/CSS, etc).
BuilderAbstract also provides generic services Builder services (eg RoundTripService, MigrationService).
The PackageBuilder will probably orchestrate the other Builders when building a package, as they are complementary.
Derivative Packages never depend on the Boilerplates they are based on. They get modified copies of boilerplate files.

Producing a Derivative Package

This shows how Derivative Packages are made with the TemplateBuilder. The user has several choices:
(1) Selects a SourceTemplate (HTML/CSS) that will be converted to Fluid Templates in a Derivative Package
(2) Copy Fluid Templates from a Boilerplate Package and customize in a Derivative Package
(3) Start with nothing, and generate a Fluid Templates in a Derivative Package,
but insert some Fluid Widgets from a Boilerplate Package

I produced these images in yED. I can provide the original .graphml files if requested.