Carbon.Eel Package for Neos CMS
Generates BEM classes. The modifiers property can be a string (for one modifier), an array (e.g. ['one', 'two']
), or an array with keys and values. If you have an array with keys and values (like a Fusion DataStructure) and a value is true
, the key's name gets used for the modifier.
block
(string, required) The name of the blockelement
(string) The name of the element, optionalmodifiers
(string|array) The name of the modifiers, optional
Shortcut to Carbon.Array.BEM(block, element, modifiers)
Shortcut to Carbon.String.BEM(block, element, modifiers)
Generates a string with BEM classes. The modifiers property can be a string (for one modifier), an array (e.g. ['one', 'two']
), or an array with keys and values. If you have an array with keys and values (like a Fusion DataStructure) and the value is true
, the key's name gets used for the modifier.
class
(string, required) The name of the classmodifiers
(string|array) The name of the modifiers, optional
Return The string
Generates an array with BEM classes. The modifiers property can be a string (for one modifier), an array (e.g. ['one', 'two']
), or an array with keys and values. If you have an array with keys and values (like a Fusion DataStructure) and the value is true
, the key's name gets used for the modifier.
block
(string, required) The name of the blockelement
(string) The name of the element, optionalmodifiers
(string|array) The name of the modifiers, optional
Return The array
Chunks an array into arrays with length
elements. The last chunk may contain less than length
elements.
array
(array, required) The array to work onlength
(integer, required) The size of each chunkpreserveKeys
(bool) When set totrue
, keys will be preserved. Default isfalse
, which will reindex the chunk numerically
Join the given array recursively using the given separator.
${Carbon.Array.join(array, ',')}
array
(array) The array that should be processedseparator
(string, optional) The separator between the values defaults to,
Return The converted array as a string
This method extracts sub-elements to the parent level.
An input array of type:
[
element1 => [
0 => 'value1'
],
element2 => [
0 => 'value2'
1 => 'value3'
],
will be converted to:
[
0 => 'value1'
1 => 'value2'
2 => 'value3'
]
array
(array) The array that should be processedpreserveKeys
(boolean, optional) Option if the key should be preserved, defaults tofalse
Return The converted array
array1
(iterable|mixed) First array or valuearray2
(iterable|mixed) Second array or valuearray_
(iterable|mixed, optional) Optional variable list of additional arrays / values
Returns an array containing all the values of array1
that are present in all the arguments.
The method counts elements of a given array or a countable object. Return 0
if it is not an countable object.
count = ${Carbon.Array.length(countable)}
Returns a boolean if the array has a specific key
bool = ${Carbon.Array.hasKey(array, key)}
Returns a boolean if the array has a specific value
bool = ${Carbon.Array.hasValue(array, value)}
Returns the value of a nested array by following the specified path.
value = ${Carbon.Array.getValueByPath(array, path)}
Sets the given value in a nested array or object by following the specified path.
array = ${Carbon.Array.setValueByPath(subject, path, value)}
Check if a variable is iterable and has items
Return The variable or null
if it is empty or not an iterable
Check if the given variable is countable
Return true
or false
array
(iterable|mixed) array with arrays to sortkey
(string) Key of array to sortdirection
(string, optional)ASC
orDESC
. Direction of sorting
Return The sorted array
Return seconds until the given offset. . Very useful for maximumLifetime
on the @cache
entry.
string
(string) The offset inDateInterval
format starting from midnightdateinerval
(boolean, optional) true if interval should be used or the $offset should be parsed, defaults totrue
In this example, we clear the cache at midnight by adding an offset of 0 hours.
@cache {
mode = 'cached'
maximumLifetime = ${Carbon.Date.secondsUntil('PT0H')}
...
}
To get the seconds until next year, you can do it like this:
secondUntilNextYear = ${Carbon.Date.secondsUntil('first day of January next year', false)}
Return The timespan in seconds (integer)
Convert time duration (1:00) into a DateInterval
Return The duration as DateInterval
Returns the file content of a path. Fails silently.
Examples:
Carbon.FileContent.path('resource://Foo.Bar/Private/Assets/Logo.svg')
Carbon.FileContent.path('Foo.Bar/Private/Assets/Logo.svg')
string
(string) The path to the file
Return The content of the file
Returns the hash value from the file content of a path. Fails silently.
Examples:
Carbon.FileContent.pathHash('resource://Foo.Bar/Private/Assets/Logo.svg') == 1d62f5a5
Carbon.FileContent.pathHash('Foo.Bar/Private/Assets/Logo.svg', 20) == 1d62f5a55ad5e304d60d
string
(string) The path to the filelength
(integer, optional) The length of the hash value defaults to8
. The maximal value is40
Return The hash value from the content of the file
Returns the file content of a persisted resource. Fails silently.
Example:
Carbon.FileContent.resource(q(node).property('file'))
resource
(resource) The persisted resource to read
Return The content of the file
Returns the hash value from the file content of a persisted resource. Fails silently.
Example:
Expression | Result |
---|---|
Carbon.FileContent.resourceHash(q(node).property('file')) |
'1d62f5a5' |
Carbon.FileContent.resourceHash(q(node).property('file'), 20) |
'1d62f5a55ad5e304d60d' |
resource
(resource) The persisted resource to readlength
(integer, optional) The length of the hash value defaults to8
. The maximal value is40
Return The hash value from the content of the file
This helper allows you to merge multiple Tailwind CSS classes and automatically resolves conflicts between them without headaches. Render all arguments as classNames and apply conditions if needed. Merge strings and arrays to a string with unique values, separated by an empty space.
All arguments of the eel helper are evaluated and the following rules are applied:
- falsy values: (
null
,''
,[]
,{}
) are not rendererd - array: all items that are scalar and truthy are rendered as classname
- object: keys that have a truthy values are rendered as classname
- scalar: is cast to string and rendered as class-name
It is based on tailwind-merge-php.
Examples:
Expression | Result |
---|---|
Tailwind.merge('w-8 h-8 rounded-full rounded-lg') |
'w-8 h-8 rounded-lg' |
Tailwind.merge(['w-8 rounded-full'], 'rounded-lg', 'h-8') |
'w-8 rounded-lg h-8' |
Tailwind.merge(null, null, {}, []) |
null |
Tailwind.merge('one', ['one', 'two'], {three: true, four: false} |
'one two three' |
Return The merged string
If you are using Tailwind CSS without any extra config, you can use the Eel helper right away. And stop reading here.
If you're using a custom Tailwind config, you may need to configure the Eel helper as well to merge classes properly.
By default it is configured in a way that you can still use it if all the following apply to your Tailwind config:
- Only using color names which don't clash with other Tailwind class names
- Only deviating by number values from number-based Tailwind classes
- Only using font-family classes which don't clash with default font-weight classes
- Sticking to default Tailwind config for everything else
If some of these points don't apply to you, you need to customize the configuration.
This is an example to add a custom font size of very-large
:
Carbon:
Eel:
tailwindMergeConfig:
classGroups:
'font-size':
- text: ['very-large']
You can also enable different validators, to make everything easier. For instance, if you use the Tailwind OKLCH Plugin, you can set it like that:
Carbon:
Eel:
tailwindMergeConfig:
classGroups:
'fill-lightness':
- 'fill-lightness-offset': ['INTEGER_VALIDATOR', 'ARBITRARY_NUMBER_VALIDATOR']
'border-lightness':
- 'border-lightness-offset': ['INTEGER_VALIDATOR', 'ARBITRARY_NUMBER_VALIDATOR']
'text-lightness':
- 'text-lightness-offset': ['INTEGER_VALIDATOR', 'ARBITRARY_NUMBER_VALIDATOR']
'bg-lightness':
- 'bg-lightness-offset': ['INTEGER_VALIDATOR', 'ARBITRARY_NUMBER_VALIDATOR']
If you want to use a certain validator, just change it to constant case and add it as a string.
So, for examle, if you want to use the TshirtSizeValidator
, just add TSHIRT_SIZE_VALIDATOR
to the list.
The merge service uses a its own cache
Carbon_Eel_Tailwind
. Make sure to clear the cache when you are making changes to the configuration.
Generate an object for AlpineJS directive x-data
.
Supports nested arrays. You could do the same with Json.stringify()
, but this function is shorter, as AlpineJS
accepts objects and easier to write and read. The default magics from Alpine.js will not be converted to string. The
same goes with methods (see example below).
Examples:
Expression | Result |
---|---|
AlpineJS.object({effect: 'slide', spaceBetween: 12, loop: true, navigation: null}) |
"{effect:'slide',spaceBetween:12,loop:true,navigation:null}" |
AlpineJS.object({nested: {value: true, nulled: null'}}) |
"{nested:{value:true,nulled:null}}" |
AlpineJS.object({persistedNumber: '$persist(5)'}) |
"{persistedNumber:$persist(5)}" |
AlpineJS.object({value: 'someValue', log(value): '{console.log(value)}'}) |
"{value:'someValue',log(value){console.log(value)}}" |
Of course you can also pass DataStructures
to the helper:
prototype(Foo.Bar:Example) < prototype(Neos.Fusion:Component) {
data = Neos.Fusion:DataStructure {
effect = 'slide'
spaceBetween = 12
persistedNumber = '$persist(5)'
'log(value)' = '{console.log(value)}'
}
renderer = ${AlpineJS.object(props.data)}
}
...arguments
The array
Return The JavaScript object as string
Generate a function call for AlpineJS. More info.
Supports nested arrays. In named arrays ({first:1,second:null}
) null
get filtered out, but in list
arrays ([1,null]
) and in plain values the will stay. Basically it is the same as AlpineJS.object
, just wrapped in a
function call.
Examples:
Expression | Result |
---|---|
AlpineJS.function('slider', {effect: 'slide', spaceBetween: 12, loop: true, navigation: null}) |
"slider({effect:'slide',spaceBetween:12,loop:true})" |
AlpineJS.function('slider', 'one', 1, false, null, ['string', 2, null]) |
"slider('one',1,false,null,['string',2,null])" |
AlpineJS.function("vote", 4) |
"vote(4)" |
name
(string) The name for the function (e.gx-data
,x-on:click
, etc.)...arguments
(mixed) The options for the function
Return The string for the x-data function call
Generate a call for a magic function for AlpineJS..
Supports nested arrays. In named arrays ({first:1,second:null}
) null
get filtered out, but in list
arrays ([1,null]
) and in plain values the will stay.
Examples:
Expression | Result |
---|---|
AlpineJS.magic('dispatch', 'notify') |
"$dispatch('notify')" |
AlpineJS.magic('$dispatch', 'notify', { message: 'Hello World!' }) |
"$dispatch('notify',{message:'Hello World!'})" |
AlpineJS.magic('dispatch', 'notify', { message: true, nested: {value: true} }) |
"$dispatch('notify',{message:true,nested:{value:true}})" |
name
(string) The name for the magic. If not prefixed with an$
, it will automatically prefixed....arguments
(mixed) The options for the function
Return The string for the magic function call
Use this to pass a javascript expression inside of the AlpineJS.object
, AlpineJS.function
or AlpineJS.magic
helper
Examples:
Expression | Result |
---|---|
AlpineJS.object({theme: AlpineJS.expression("localStorage.theme||'system'"), show: true}) |
"{theme:localStorage.theme||'system',show:true}" |
AlpineJS.function('themeSwitcher', {theme: AlpineJS.expression("localStorage.theme||'system'") |
"themeSwitcher({theme:localStorage.theme||'system',show:true})" |
Generates a string with BEM classes. The modifiers property can be a string (for one modifier), an array (e.g. ['one', 'two']
), or an array with keys and values. If you have an array with keys and values (like a Fusion DataStructure) and the value is true
, the key's name gets used for the modifier.
block
(string, required) The name of the blockelement
(string) The name of the element, optionalmodifiers
(string|array) The name of the modifiers, optional
Return The string
Get a property from a node link. Can be used to get the title from a page who is linked via the link editor.
Example:
Expression | Result |
---|---|
Carbon.String.getPropertyFromNodeLink(site, 'node://aaaa-bbbb-ccc') |
'Title from the linked page' |
Carbon.String.getPropertyFromNodeLink(site, 'node://aaaa-bbbb-ccc', null) |
null |
Carbon.String.getPropertyFromNodeLink(null, 'node://aaaa-bbbb-ccc') |
null |
Carbon.String.getPropertyFromNodeLink(site, 'some other value') |
null |
Carbon.String.getPropertyFromNodeLink(site, 'some other value', 'title', 'fallback value') |
'fallback value' |
node
(NodeInterface) The node, usallysite
value
(string) The value to processpropertyName
(string) The name of the property to getfallback
(mixed) The fallback value if nothing is found
Generates a slug of the given string
Examples:
Expression | Result |
---|---|
Carbon.String.urlize('Hello World') |
'hello-world' |
Carbon.String.urlize('Ä_ÖÜ äöü') |
'ae-oeue-aeoeue' |
string
(string) The string to convert
Return The converted string
Minifies JavaScript so that it can be delivered to the client quicker.
javascript
(string, required) The JavaScript to minify
Return The minified JavaScript
Minifies CSS so that it can be delivered to the client quicker.
css
(string, required) The CSS to minify
Return The minified CSS
Convert strings to PascalCase
.
Examples:
Expression | Result |
---|---|
Carbon.String.toPascalCase('hello-world') |
'HelloWorld' |
Carbon.String.toPascalCase('hello world') |
'HelloWorld' |
Carbon.String.toPascalCase('Hello World') |
'HelloWorld' |
string
(string) The string to convert
Return The converted string
Convert strings to camelCase
.
Examples:
Expression | Result |
---|---|
Carbon.String.toCamelCase('hello-world') |
'helloWorld' |
Carbon.String.toCamelCase('hello world') |
'helloWorld' |
Carbon.String.toCamelCase('Hello World') |
'helloWorld' |
string
(string) The string to convert
Return The converted string
Convert CamelCaseStrings
to hyphen-case-strings
Examples:
Expression | Result |
---|---|
Carbon.String.convertCamelCase('HelloWorld') |
'hello-world' |
Carbon.String.convertCamelCase('HelloWorld', '_') |
'hello_world' |
Carbon.String.convertCamelCase('HelloWorld', '') |
'helloworld' |
string
(string) The string to convertseparator
(string, optional) The separator between the words defaults to-
Return The converted string
Helper to make sure to get a string back.
Examples:
Expression | Result |
---|---|
Carbon.String.convertCamelCase(' helloworld ') |
'helloworld' |
Carbon.String.convertCamelCase([' hello', ' world']) |
'hello world' |
Carbon.String.convertCamelCase([' hello', ' world'], '-') |
'hello-world' |
input
(string, array) A string or an array to convertseparator
(string, optional) The separator between the words, defaults to whitespace
Return The converted string
Replace all newlines with an <br>
.
Examples:
Expression | Result |
---|---|
Carbon.String.nl2br('hello\nworld') |
'hello<br>world' |
Carbon.String.nl2br('hello\nworld', ' - ') |
'hello - world' |
string
(string) A string to convertseparator
(string, optional) The separator between the words, defaults to<br>
Return The converted string
Replace non-breaking spaces and double spaces with a normal space.
Examples:
Expression | Result |
---|---|
Carbon.String.removeNbsp(' hello world') |
'hello world' |
Carbon.String.removeNbsp('hello world') |
'hello world' |
string
(string) A string to convert
Return The converted string
Render all arguments as classNames and apply conditions if needed. Merge strings and arrays to a string with unique values, separated by an empty space.
All arguments of the eel helper are evaluated and the following rules are applied:
- falsy values: (
null
,''
,[]
,{}
) are not rendererd - array: all items that are scalar and truthy are rendered as classname
- object: keys that have a truthy values are rendered as classname
- scalar: is cast to string and rendered as class-name
Examples:
Expression | Result |
---|---|
Carbon.String.classNames('', 'one') |
'one' |
Carbon.String.classNames(['one two three'], ['one', 'four']) |
'one two three four' |
Carbon.String.classNames(null, false, [null], {one: false}) |
null |
Carbon.String.classNames('one two three', ['one', 'four']) |
'one two three four' |
Carbon.String.classNames('one', {two: true, three: false }) |
'one two' |
Return The merged string
Split a string into an array width integers and strings. Useful for animations.
Examples:
Expression | Result |
---|---|
Carbon.String.splitIntegerAndString('1000+ customers') |
[1000, '+ customers'] |
Carbon.String.splitIntegerAndString('24/7 reachability') |
[24, '/', 7, ' reachability'] |
Carbon.String.splitIntegerAndString('0 issues') |
[0, ' issues'] |
Carbon.String.splitIntegerAndString('') |
[] |
Carbon.String.splitIntegerAndString(null) |
[] |
Carbon.String.splitIntegerAndString(100) |
[100] |
string
(string) The string to split
Return The string, splitted into an array of integers and strings
Helper to convert phone numbers to a compatible format for links
Examples:
Expression | Result |
---|---|
Carbon.String.phone(' 079 123 45 67 ') |
'tel:0791234567' |
Carbon.String.phone('+41 (0) 79 123/45/67') |
'tel:0041791234567' |
Carbon.String.phone('079 123 45 67', '+41') |
'tel:0041791234567' |
Carbon.String.phone('079 123 45 67', null, null) |
'0791234567' |
Carbon.String.phone(' / (0) ') |
null |
phoneNumber
(string) The phone number to convertdefaultCountryCode
(string, optional) The default country code, for example'+41'
prefix
(string, optional) Prefix the phone number, defaults to'tel:'
Return The phone number, optimized for links
Checks if the string is a valid email address
Examples:
Expression | Result |
---|---|
Carbon.String.isValidEmail('') |
false |
Carbon.String.isValidEmail('Some text') |
false |
Carbon.String.isValidEmail('[email protected]') |
true |
emailAddress
(string) The string to check
Helper to replace the first occurrence of a string.
Examples:
Expression | Result |
---|---|
Carbon.String.replaceOnce('Foo Bar Foo', 'Foo', 'X') |
'X Bar Foo' |
Carbon.String.replaceOnce('Foo Bar Foo', 'Foo ') |
'Bar Foo' |
string
(string) The string being searched and replaced onsearch
(string) The value being searched forprefix
(string, optional) The replacement value that replaces found search value
Returns the string with one occurrence replaced
Format a number with grouped thousands. If decimals
is set to null
, it returns as many as needed decimals.
number
(float, required) The number being formatteddecimals
(integer, optional) Sets the number of decimal points, defaults tonull
dec_point
(string, optional) The name of the modifier defaults to.
thousands_sep
(string, optional) The name of the modifier defaults to,
Format a localized number with grouped thousands. If decimals
is set to null
, it returns as many as needed decimals.
number
(float, required) The number being formatteddecimals
(integer, optional) Sets the number of decimal points, defaults tonull
locale
(string, optional) String locale - example (de_DE|en|ru_RU)
Get number of decimal digits.
number
(float, required) The number being formatted
Convert a pixel value to rem
value
(numeric | string, required) The value to convertedfallback
(numeric | string, optional) Fallback value ifvalue
isfalse
ornull
Examples:
Expression | Result |
---|---|
Carbon.Number.pxToRem('') |
'0' |
Carbon.Number.pxToRem('8px') |
'0.5rem' |
Carbon.Number.pxToRem(16) |
'1rem' |
Carbon.Number.pxToRem(0) |
'0' |
Carbon.Number.pxToRem(false, 32) |
'2rem' |
Carbon.Number.pxToRem(null, '16px') |
'1rem' |
Returns a string with the converted value
Returns the language from the interface
Get the translated value (in the language of the interface) for an id or original label. If the only id is set and contains a translation shorthand string, translate according to that shorthand.
In all other cases: Replace all placeholders with corresponding values if they exist in the translated label.
id
(string) Id to use for finding translation (trans-unit id in XLIFF)originalLabel
(string, optional) The original translation value (the untranslated source string)arguments
(array, optional) Array of numerically indexed or named values to be inserted into placeholderssource
(string, optional) Name of file with translationspackage
(string, optional) Target package keyquantity
(mixed, optional) A number to find a plural form for (float or int),null
to not use plural formslocale
(string, optional) An identifier of the locale to use (NULL for use the interface language)
Returns the translated label or source label / ID key
Carbon.Eel is available via packagist. Just run
composer require carbon/eel
Some of the Eel helpers were inspired and or copied from punkt.de