hananils / kirby-attrs-helper
Setting attributes on elements in snippets and templates quickly becomes convoluted. This gets worse if attributes require additional logic, like conditionally adding segmented values like classnames or datasets. Attributes helper mitigates this issue by offering a simple interface to set attributes
Installs: 1
Dependents: 0
Suggesters: 0
Security: 0
Stars: 4
Watchers: 4
Forks: 0
Open Issues: 0
Type:kirby-plugin
Requires
- php: ^8.2
Requires (Dev)
- ergebnis/composer-normalize: ^2.47
- rector/rector: ^2.0
README
Setting attributes on elements in snippets and templates quickly becomes convoluted. This gets worse if attributes require additional logic, like conditionally adding segmented values like classnames or datasets. Attributes helper mitigates this issue by offering a simple interface to set attributes.
Note
Please check out the online documentation at kirby.hananils.de/plugins/attrs-helper for further information.
Usage
Attributes helper takes an associative array with the keys specifying the attribute names and the values specifying the corresponding attribute values. Values can either be static if passed as string or conditional if passed as array.
Static values
If values are passed as string, the plugin will create an attribute for each key using the given value.
<p <?= attrs([ 'id' => 'introduction', 'class' => 'highlighted' ])?> > An introductory paragraph. </p>
This will create the following markup:
<p id="introduction" class="highlighted">An introductory paragraph.</p>
Conditional values
The attribute values can also be constructed conditionally:
<p <?=attrs([ 'id' => $page->isHomePage() ? 'home' : false ])?> > A paragraph. </p>
This will only add the id
attribute if the current page is the homepage. Otherwise, the attribute will be omitted.
Boolean values
If values evaluate to a boolean value, an attribute is only rendered if its value is true
. In the following case, the checked
attribute will only be added if the page is listed.
<input <?=attrs([ 'type' => 'checkbox', 'checked' => $page->isListed() ])?> >
The result will either be a checked or unchecked checkbox:
<!-- listed --> <input type="checkbox" checked /> <!-- unlisted, draft --> <input type="checkbox" />
Segmented values
If the value itself is an array, all keys will be considered value segments that will be joined by as separator (a space by default). The associated array value is used as the condition to determine whether a segment should be added to the attribute or skipped.
This is useful if you'd like to set classnames or datasets dynamically.
The following example will either create a class attribute with the value published has-image
, published
, has-image
or none at all depending on the page settings:
<article <?=attrs([ 'class' => [ 'published' => $page->published()->isTrue(), 'has-image' => $page->images()->isNotEmpty() ] ])?> > An example article. </article>
The helper also allows you to combine static and dynamic segments:
<article <?=attrs([ 'class' => [ 'some', 'static', 'classnames', 'published' => $page->published()->isTrue(), 'has-image' => $page->images()->isNotEmpty() ] ])?> > An example article. </article>
In this case, some static classnames
will always be added to the class
attribute.
Custom delimiter
If you'd like to join segmented values with a custom delimiter, you can pass it as second argument to the attrs
function:
<article <?=attrs([ 'data-list' => [ 'some', 'static', 'values' ] ], '|')?> > An example article. </article>
This example will return some|static|values
as value for the data-list
attribute.
Installation
Download
Download and copy this repository to /site/plugins/attrs-helper
.
Git submodule
git submodule add https://github.com/hananils/kirby-attrs-helper.git site/plugins/attrs-helper
Composer
composer require hananils/kirby-attrs-helper
License
This plugin is provided freely under the MIT license by hana+nils · Büro für Gestaltung.
We create visual designs for digital and analog media.