Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/namelesscoder/patternlab-fluid-edition

Pattern Lab Fluid Edition
https://github.com/namelesscoder/patternlab-fluid-edition

atomic-design design fluid neos-cms pattern-lab patternlab typo3

Last synced: 5 days ago
JSON representation

Pattern Lab Fluid Edition

Awesome Lists containing this project

README 

        
Pattern Lab Fluid Edition

=========================



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



![license](https://img.shields.io/github/license/namelesscoder/patternlab-fluid-edition.svg)

![Packagist](https://img.shields.io/packagist/v/namelesscoder/patternlab-fluid-edition.svg)



# Pattern Lab Fluid Edition



This package is an edition of [Pattern Lab](http://patternlab.io) for the [TYPO3 Fluid template engine](https://github.com/TYPO3/Fluid). 



## Installing



**Please note:** The Pattern Lab Fluid edition exclusively uses [Composer](https://getcomposer.org/) 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](https://getcomposer.org/) to manage project dependencies.



#### 1. Install Composer



Please follow the directions for [installing Composer](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx) on the Composer website.



#### 2. Install the Pattern Lab Fluid Edition



Use Composer's [`create-project` command](https://getcomposer.org/doc/03-cli.md#create-project) 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



```yaml

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 `` this must be set

  to `false` to produce a `<script>` tag instead of ``).



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 `` 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:



1. Original class is completely missing, which fully emulates the ViewHelper

2. 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](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 



### Credits



This work was kindly sponsored by [Busy Noggin](http://busynoggin.com/).