Download the PHP package mvrk/icenberg without Composer
On this page you can find all versions of the php package mvrk/icenberg. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download mvrk/icenberg
More information about mvrk/icenberg
Files in mvrk/icenberg
Package icenberg
Short Description Library to abstract away Advanced Custom Fields flexible content markup
License MIT
Informations about the package icenberg
Icenberg 🥶
- Icenberg 🥶
- What is it?
- Getting Started
- Initialise
- Using with ACF Flexible Content blocks
- Using in an ACF Gutenberg Block
- Icenberg Methods
- Global Options
- Values
- Conditionals and manipulations
field($field_name)
prune(array $exclusions)
only(array $inclusions)
is($value)
lessThan($value)
/greaterThan($value)
- Special Fields
- Google Maps Field
settings($field_name, $additional_classes = [])
get_buttons($field_name, $modifiers = [])
/the_buttons($field_name, $modifiers = [])
- CLI
- Available commands
- Configuration
- Supported fields
- Full Support
- Third party fields:
- Special Fields
- VS Code Extension
What is it?
Icenberg is an opinionated abstraction for ACF Fields in WordPress. It cleans up and simplifies ACF Flexible content and ACF Gutenberg block templates which often involve a lot of repetition and logic tangled up in presentation (in true WordPress style).
Using Icenberg's methods we can render acf fields complete with BEM classes and settings in a clean(er) object oriented fashion, while still allowing us to do things the old fashioned way if necessary.
Icenberg requires ACF Pro and is primarily for internal use at Maverick, although it is easy to implement on any WordPress template using ACF fields. It also includes a convenient CLI for generating ACF Gutenberg blocks.
It is designed to be used primarily with flexible content fields and ACF Gutenberg blocks but works with any field including option fields. It could also work within other scenarios, in theory.
Getting Started
Install via composer:
make sure autoloading is set up in functions.php - something like:
Make sure you have ACF Pro installed. The library also supports ACF Gravity forms plugin.
Initialise
Icenberg::__construct($layout, $prefix = 'block', $post_id = false)
Argument | Type | Required | Description |
---|---|---|---|
$layout |
string | Yes | ACF layout or block name |
$prefix |
string | No | Prefix used for classnames etc. Defaults to 'block' |
$post_id |
mixed | No | Override the default post ID. Defaults to false |
Using with ACF Flexible Content blocks
The following example takes place inside ACF's the_row() - ie:
Initialise with ACFs get_row_layout()
in your block template:
Using in an ACF Gutenberg Block
Since v0.5.0 you can use Icenberg in an ACF gutenberg block, just pass the block title instead of the row layout. You can use the wrap method in a gutenberg block to wrap the block frontend in a similar way to how it is wrapped automatically by wp in the backend:
Icenberg Methods
get_element($field_name, $tag = 'div', $modifiers = [])
Argument | Type | Required | Description |
---|---|---|---|
$field_name |
string | Yes | The ACF field name to render |
$tag |
string | No | The HTML tag to wrap the element in. Defaults to 'div' |
$modifiers |
array | No | An array of modifiers to use as BEM classes |
Returns an ACF field as a formatted string, wrapped up in all the divs you need and with any special considerations applied. Takes the field name as an argument and optionally a tag for the uppermost element. If no tag is set it will use 'div'
the_element($field_name, $tag = 'div', $modifiers = [])
Argument | Type | Required | Description |
---|---|---|---|
$field_name |
string | Yes | The ACF field name to echo |
$tag |
string | No | The HTML tag to wrap the element in. Defaults to 'div' |
$modifiers |
array | No | An array of modifiers to use as BEM classes |
As above, but echoes it out immediately.
Icenberg is smart enough to know what a field's type is, so you don't need to differentiate, you just pass the field name in.
Global Options
To retrieve a global option simply pass a comma delimeted string to the_element()
or get_element()
- it must be all as one string as opposed to seperate args and it must be comma delimited, where the first part is the field name and the second part is the options name, eg
enclose($class, array $elements, $tag = 'div', $attrs = [], $modifiers = [])
Argument | Type | Required | Description |
---|---|---|---|
$class |
string | Yes | Classname to apply to wrapper div (BEM modifiers will be appended automatically) |
$elements |
array | Yes | Array of rendered HTML elements (e.g. get_element() results or strings) |
$tag |
string | No | The HTML tag to wrap the element in. Defaults to 'div' |
$attrs |
array | No | An array of additional attributes to apply to the wrapper element |
$modifiers |
array | No | An array of modifiers to use as BEM classes |
Enclose is a utility for wrapping multiple icenberg fields in a container div without having to use a ?> anywhere. You just need to pass it a classname (without prefixes as these will be applied by icenberg). So clean!
So for example, in a 'Cta' block, where cta_heading is a text field and cta_content is a wysiwyg field:
will generate:
You could also pass any thing else you like to enclose as part of the array, as long as its storable as a variable (for example inserting a get_template_part()
won't work here because it effectively prints the content).
Of course life is never simple, so you will most likely need more complex layouts, but icenberg doesn't mind. You can insert it in html if you want to.
Values
You can us the value()
method to return the 'raw', value of a given field without checking for existence or specifiying if it is a sub field.
as this just returns the value there are no special considerations for individual field types.
Conditionals and manipulations
field($field_name)
Argument | Type | Required | Description |
---|---|---|---|
$field_name |
string | Yes | Name of the field to work with |
you can use icenberg to evaluate fields and do some more comlplex field manipualtion too, using the field()
method in conjucntion with the below methods. field()
takes the field name as an argument and returns the icenberg instance for method chaining.
get($tag = 'div', $modifiers = [])
Argument | Type | Required | Description |
---|---|---|---|
$tag |
string | No | Tag to use for the wrapper. Defaults to 'div' |
$modifiers |
array | No | An array of modifiers to use as BEM classes |
Returns the icenbergified field html (in the same way as get_element). Optionally pass a tag for the wrapper.
prune(array $exclusions)
Argument | Type | Required | Description |
---|---|---|---|
$exclusions |
array | Yes | Field names to exclude from the group/repeater output |
pass an array of field names to the prune method to remove them from a group or from a repeater row.
only(array $inclusions)
Argument | Type | Required | Description |
---|---|---|---|
$inclusions |
array | Yes | Field names to include in the group/repeater output |
is($value)
Argument | Type | Required | Description |
---|---|---|---|
$value |
mixed | Yes | Value to compare against the field value |
returns true if the value of the field equals the argument passed to is()
. You don't need to check for a fields existance before using these methods as they will do it for you and return false
if they don't.
lessThan($value)
/ greaterThan($value)
Argument | Type | Required | Description |
---|---|---|---|
$value |
int | Yes | Integer to compare field value against |
Self explanatory, both take an integer as an argument. Warning: If you use it on a non numeric field it will return false.
Special Fields
Google Maps Field
For the Google Maps field to work properly on front and backends you will need an API key. Once you have the key, add it to icenberg.yml in your project and the frontend will work. To make it work in the backend, add the following to your functions.php (in this example the key is defined in wp-config.php)
settings($field_name, $additional_classes = [])
Argument | Type | Required | Description | |
---|---|---|---|---|
$field_name |
string | array | Yes | Field group name or settings array |
$additional_classes |
array | No | Additional classnames to append as modifiers |
Pass in a field group of settings and optionally an array of manually set classes and it will attach them as CSS modifier classes. if you include a text field called 'unique_id' in your group icenberg will attach it as a id too.
Example using settings in enclose()
:
or in regular php/html
which will print out something like
Depending on the settings in your group.
get_buttons($field_name, $modifiers = [])
/ the_buttons($field_name, $modifiers = [])
Argument | Type | Required | Description |
---|---|---|---|
$field_name |
string | Yes | Field group name for buttons |
$modifiers |
array | No | An array of modifiers to use as BEM classes |
Return a formatted group of buttons with a huge range of styles catered for - very Maverick specific.Expects our usual group of buttons format.
CLI
you can now use the Icenberg CLI to rapidly bootstrap Icenberg blocks (since v0.5.0). This extends wp-cli so you need to have that installed and working first.
Add the below to your functions.php, after the autoload.
Available commands
wp icenberg block --block_name
this bootstraps an ACF gutenberg block with all relevant files ready to go.
This assumes that your blocks are in a folder called 'blocks' in your template root directory but this is configurable via icenberg.yaml
Icenberg generates a folder per block within the blocks folder. This folder contains
- block.json
-
.php -
.css
It will also register an empty field group ready for access via the ACF GUI.
wp icenberg block --block_name --flexible
this is similar to the above but creates just the php and scss files for flexible content blocks.
Configuration
Config options are now available by placing an 'icenberg.yaml' file in your project's root directory. If this file doesn't exist or can't be parsed, icenberg will just go ahead and use its defaults.
Supported config options below with their default values:
Supported fields
Full Support
- Gallery
- Group
- Image
- Link
- Number
- OEmbed
- Range
- Repeater
- Select
- Text
- Textarea
- Wysiwyg
- Relationship
- Post Object
- Page Link
- Google Maps
Third party fields:
- Forms
- Swatch
Special Fields
- Buttons
- Settings
VS Code Extension
An extension with useful snippets is available for Virtual Studio Code.