README

This is the entry point for new Pattern Lab Fluid Edition projects!

Pattern Lab Fluid Edition

This package is an edition of Pattern Lab for the TYPO3 Fluid template engine.

Installing

Please note: The Pattern Lab Fluid edition exclusively uses Composer to manage project dependencies. No pre-built packages are available - the application can only be installed with Composer.

Use Composer to create a project

Pattern Lab uses Composer to manage project dependencies.

1. Install Composer

Please follow the directions for installing Composer on the Composer website.

2. Install the Pattern Lab Fluid Edition

Use Composer's create-project command to install the edition as base for new projects:

cd install/location/
composer create-project namelesscoder/patternlab-fluid-edition your-project-name && cd $_

This will create a folder named your-project-name, install the Fluid edition to that folder and walk you through the install process.

You will be asked to choose a starter kit - at the current time only one such starter kit is available. Select and install it to complete the installation process.

Updating Pattern Lab

Updating the Fluid edition of Pattern Lab can be done with composer update.

Special usage instructions for Fluid

The Pattern Lab Fluid Edition comes with a few extra features as demonstrated by this configuration example:

config/config.yml

fluidNamespaces:
    f:
        - TYPO3\CMS\Fluid\ViewHelpers
    myns:
        - My\Package\ViewHelpers
emulatedViewHelpers:
    My\Special\TagGeneratingViewHelper:
        tagName: "a"
        attributeMap:
            specialTargetArgumentName: "href"
        outputsTagContent: true
        forceClosingTag: true
    My\Special\NormalViewHelper:
        outputsTagContent: true

Briefly described, these options allows:

Registering additional namespaces that Fluid will see (inline imports are still fully possible!)
Emulate ViewHelpers from packages which have special requirements e.g. for DB access

The ViewHelper emulation is only superficially configurable; generally speaking the best advise is to structure your templates so that things like URLs (which are usually framework-specific) do not get generated by ViewHelpers but are instead passed as arguments to partials. But for those cases where a ViewHelper must be included and an output emulated, these options can be used.

The options allow:

Changing the tag name of TagBasedViewHelpers.
Mapping arguments to attributes of resulting tags (e.g. your ViewHelper receives an ID as target, mapping that to for example href will produce valid HTML - but with broken link targets).
Configure whether or not an emulated ViewHelper is designed to output the tag contents.
Forcing a generated tag to be self-closing or not (for example if the ViewHelper generates <script> this must be set to false to produce a <script></script> tag instead of <script />).

It is also possible to create drop-in ViewHelpers by making new PHP class files in source/_viewhelpers/ and using the special plio namespace, e.g. if you created a file MySpecialViewHelper.php with a class called MySpeciaViewHelper then this class can be used as <plio:mySpecial /> in templates without needing to import the namespace.

Drop-in ViewHelpers can use completely arbitrary folder nesting and namespaces which makes it easier to prototype such classes without being able to autoload them through normal means, and without having a target package for them as is normally required.

ViewHelper argument validation and execution

There are two levels of emulation which may apply to ViewHelpers:

Original class is completely missing, which fully emulates the ViewHelper
Original class exists but cannot be rendered, which only partially emulates the ViewHelper

What this means is that fully emulated ViewHelpers do not validate arguments at all and will only behave as they are configured to behave using settings above. But, partially emulated ViewHelpers will validate arguments being used to verify that required arguments are present and will attempt to render themselves - but any failure while rendering causes the emulated output to take over. For example, this can be failures stemming from missing dependencies or lack or an environment expected by the application the ViewHelper belongs to.

In short: if you wish ViewHelper arguments to be validated and those ViewHelpers which have no special dependencies to be fully functional, make sure you also add the package providing these ViewHelpers as dependency for your local project - and configure or import the namespace in templates. If the class can be loaded, argument descriptions can be loaded and validated as well.

Helpful Commands

These are some helpful commands you can use on the command line for working with Pattern Lab.

List all of the available commands

To list all available commands type:

php core/console --help

To list the options for a particular command type:

php core/console --help --[command]

Generate Pattern Lab

To generate the front-end for Pattern Lab type:

php core/console --generate

Watch for changes and re-generate Pattern Lab

To watch for changes and re-generate the front-end for Pattern Lab type:

php core/console --watch

Start a server to view Pattern Lab

You can use PHP's built-in web server to review your Pattern Lab project in a browser. In a seperate window type:

php core/console --server

Then open http://localhost:8080 in your browser.

Install a StarterKit

To install a near-empty StarterKit as a starting point for your project type:

php core/console --starterkit --init

To install a specific StarterKit from GitHub type:

php core/console --starterkit --install <starterkit-vendor/starterkit-name>

Credits

This work was kindly sponsored by Busy Noggin.

namelesscoder / patternlab-fluid-edition

Maintainers

Details