PHPackages namelesscoder/fluid-parameters - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Templating & Views](/categories/templating) 4. / 5. namelesscoder/fluid-parameters ActiveTypo3-cms-extension[Templating & Views](/categories/templating) namelesscoder/fluid-parameters ============================== API to declare parameters for any Fluid template/section 1.4.0(3y ago)11.4k↓100%PHP Since Feb 13Pushed 3y ago1 watchersCompare [ Source](https://github.com/NamelessCoder/fluid-parameters)[ Packagist](https://packagist.org/packages/namelesscoder/fluid-parameters)[ RSS](/packages/namelesscoder-fluid-parameters/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependencies (5)Versions (8)Used By (0) [![Latest Stable Version](https://camo.githubusercontent.com/38e52c842790a4788edb5aa3d9a0a6a4cb4bc285e9861c2390851d2bbe8dd538/68747470733a2f2f706f7365722e707567782e6f72672f6e616d656c657373636f6465722f666c7569642d706172616d65746572732f762f737461626c652e7376673f7374796c653d666c61742d737175617265)](https://github.com/NamelessCoder/fluid-parameters)[![Total Downloads](https://camo.githubusercontent.com/0be4a0d5356d1ee91b5fc56c38ff902dfb5341d0168efc8c4dfcf0aa770ce337/68747470733a2f2f706f7365722e707567782e6f72672f6e616d656c657373636f6465722f666c7569642d706172616d65746572732f642f746f74616c3f7374796c653d666c61742d737175617265)](https://packagist.org/packages/namelesscoder/fluid-parameters)[![Monthly Downloads](https://camo.githubusercontent.com/ae7ee3f89324f8c1f3a575f97b6c9513719d02c3bff10e208ee3350808e7a571/68747470733a2f2f706f7365722e707567782e6f72672f6e616d656c657373636f6465722f666c7569642d706172616d65746572732f642f6d6f6e74686c793f7374796c653d666c61742d737175617265)](https://packagist.org/packages/namelesscoder/fluid-parameters)[![Coverage Status](https://camo.githubusercontent.com/62b45750cd465e4f24d9faca0f0790b7876a189af8f3e318cee722dfe7db6cbb/68747470733a2f2f696d672e736869656c64732e696f2f636f766572616c6c732f4e616d656c657373436f6465722f666c7569642d706172616d65746572732f6d61737465722e7376673f7374796c653d666c61742d737175617265)](https://coveralls.io/r/NamelessCoder/fluid-parameters) TYPO3 Fluid extension `fluid_parameters` ======================================== [](#typo3-fluid-extension-fluid_parameters) API to enable declaring parameters for a Fluid template, partial, layout or section within any of those types of files. What does it do? ---------------- [](#what-does-it-do) In short: *allows you to declare required and optional parameters for a Fluid asset*. It does this by emulating a subset of the features that would have been part of Fluid 3.0, namely `f:parameter`. On top of this it adds a couple of tricks for convenience. Installation ------------ [](#installation) To install, simply do `composer req namelesscoder/fluid-parameters`. That's it - no configuration is necessary. If you use the package in a TYPO3 CMS installation this automatically adds `f:parameter`, `f:description` and `f:parameter.mode`as ViewHelpers. If you are not within a TYPO3 CMS installation you nave to manually add the namespace `{namespace f=\NamelessCoder\FluidParameters\ViewHelpers}` in templates where you want to use the feature. Feature set: ------------ [](#feature-set) - Parameters can be declared for any Fluid asset; Templates, Layouts, Partials or Sections (within any of those three types of Fluid assets). - Parameters can be required, in which case an error is thrown if the required variable is not assigned as template variable or passed to the section/partial with `arguments` on `f:render`. - Parameters can be optional, in which case if they are not passed, they can be given a default value (precisely like a ViewHelper argument) and become assigned when rendering the asset. - Parameters can be cast to the appropriate type like `string` or `integer`. - Parameters can be given a list of allowed values. If you declare a parameter which allows for example values "foo" or "bar" but the variable value is "baz" when you render the asset, an error can be thrown. - Specifying a parameter with type `array` allows you to pass a CSV value as variable, to make it easier to pass array values as part of `arguments` on `f:render` without complex Fluid syntax - or directly consume values from records without exploding CSV values stored in the record's columns. - References can be rendered, describing parameters for a given Fluid asset or section. - Templates or sections can be provided with a description that can be rendered as part of the parameter reference. Together, these features allow a developer who writes Fluid template files to ensure that necessary variables are present when the template file is rendered and that optional variables can have a default value. And they allow an integrator who renders the templates to be informed if a necessary variable is not present or does not have a compatible data type - without having detailed knowledge of every template file's content. How to use: ----------- [](#how-to-use) **No configuration is required** - simply use the `f:parameter` ViewHelper in your Fluid template and the rest happens automatically. The `f:parameter` ViewHelper can be used in any Layout, Template or Partial, and within sections defined in any of those types of files. Declared parameters are **specific to the file or section** - as soon as you render another file or section, only the parameters of that other file or section will be considered. #### Adding a required parameter [](#adding-a-required-parameter) ``` {title} ``` This throws an error if `{title}` is not assigned as template variable when rendering the template. #### Optional parameter [](#optional-parameter) ``` {title} ``` This does not throw an error if `{title}` is not assigned. Instead, it automatically assigns the variable with a value of `Default title`. #### Supported parameter types [](#supported-parameter-types) - `int`, `integer` - `string` - `float`, `double`, `decimal` - `bool`, `boolean` - `array` - `DateTime` (natively converts UNIXTIME timestamps and date strings to `DateTime`) - `object` (generic object, cast to `stdClass` from `array`) Furthermore, custom class names are supported and can be specified by FQN or short name. If specified by short name, any object instance of a class with that short name will be allowed - *and no type casting will be done*. If specified by FQN, only instances of the class or subclasses thereof will be allowed - *and type casting will be possible by taking non-object values and passing them as single constructor argument for the class using `new $className($value)`*. Every type, including custom objects, also supports an "array-of-types" by adding `[]` to the type, e.g. `string[]`. This can even be done to multiple levels, e.g. `string[][]` to require "an array of arrays of strings". #### Specific required value [](#specific-required-value) ``` Some text that's either red, green or blue ``` This causes an error to be thrown if assigning variable `{color}` is not one of the exact values `red`, `green` or `blue` - and selects `red` as the default value. #### Undeclared variables [](#undeclared-variables) ``` strict ``` Sets the parameter handling mode to `strict` which means that if this template is rendered with an undeclared variable, an error is thrown: ``` ``` Results in an error: ``` Unxpected (undefined) template variable(s) encountered: unknownvariable ``` By default, **undeclared variables are allowed**. By setting the mode to `strict` this behavior is changed. **Note that `f:parameter.mode` must be used BEFORE any occurrences of `f:parameter` to have an effect.** #### Usage within sections [](#usage-within-sections) ``` strict {title} {text} ``` Has the exact same effect as declaring the parameter on a template, partial or layout - but only applies when rendering the section. If the section is rendered with an undeclared variable assigned, an error is thrown (due to mode=`strict`). If `{text}` is not assigned when rendering the section, it is automatically assigned with a value of `Default text`. #### Describing a template [](#describing-a-template) ``` This is a description of the template file. You must always assign the "title" variable when rendering this template. {title} ``` Output: ``` Value of title variable ``` Essentially, any content you use within `f:description` is not rendered as output when the template/section is rendered. **Note: do not use any Fluid code within the description block!** If you do, the description text will be truncated and only includes any text leading up to the first Fluid code. Invalid Fluid code within this block will still cause a template parsing error! Extracting "Reflections" of parameters/descriptions --------------------------------------------------- [](#extracting-reflections-of-parametersdescriptions) The package contains an API to extract information about which parameters apply to a given template, along with the contents of the `f:description` block within the template. This can be used to build your own style guide or reference. Consider the following example template file located at `/path/to/my/template.html`: ``` Text from the description block in my template strict {title} {text} Text from the description block in section "MySection" in my template Additional content: {content} ``` Using the extraction API is fairly straight-forward: ``` $templateFile = '/path/to/my/template.html'; $renderingContext = new \TYPO3Fluid\Fluid\Core\Rendering\RenderingContext(); $extractor = new \NamelessCoder\FluidParameters\Reflection\ParameterExtractor($renderingContext); $reflection = $extractor->parseTemplate($templateFile); ``` The `$reflection` variable now contains an instance of [TemplateReflection](https://github.com/NamelessCoder/fluid-parameters/blob/master/Classes/Reflection/TemplateReflection.php)which holds properties describing the template. You can use this reflection instance to extract all metadata: ```