namelesscoder / patternlab-fluid-edition
Installs: 684
Dependents: 0
Suggesters: 0
Security: 0
Stars: 19
Watchers: 3
Forks: 2
Open Issues: 2
Language:JavaScript
Type:project
This package is auto-updated.
Last update: 2024-10-12 03:56:45 UTC
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 tofalse
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.