https://github.com/maverick-international/icenberg
Abstracts away Advanced Custom Fields flexible content markup
https://github.com/maverick-international/icenberg
acf advanced-custom-fields bem
Last synced: 6 months ago
JSON representation
Abstracts away Advanced Custom Fields flexible content markup
- Host: GitHub
- URL: https://github.com/maverick-international/icenberg
- Owner: maverick-international
- Created: 2022-06-01T09:33:28.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2025-11-19T08:43:56.000Z (7 months ago)
- Last Synced: 2025-11-19T10:20:22.981Z (7 months ago)
- Topics: acf, advanced-custom-fields, bem
- Language: PHP
- Homepage:
- Size: 240 KB
- Stars: 7
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# Icenberg 🥶
- [Icenberg 🥶](#icenberg-)
- [What is it?](#what-is-it)
- [Getting Started](#getting-started)
- [Initialise](#initialise)
- [`Icenberg::__construct($layout, $prefix = 'block', $post_id = false)`](#icenberg__constructlayout-prefix--block-post_id--false)
- [Using with ACF Flexible Content blocks](#using-with-acf-flexible-content-blocks)
- [Using in an ACF Gutenberg Block](#using-in-an-acf-gutenberg-block)
- [Icenberg Methods](#icenberg-methods)
- [`get_element($field_name, $tag = 'div', $modifiers = [])`](#get_elementfield_name-tag--div-modifiers--)
- [`the_element($field_name, $tag = 'div', $modifiers = [])`](#the_elementfield_name-tag--div-modifiers--)
- [Global Options](#global-options)
- [`enclose($class, array $elements, $tag = 'div', $attrs = [], $modifiers = [])`](#encloseclass-array-elements-tag--div-attrs---modifiers--)
- [Values](#values)
- [Conditionals and manipulations](#conditionals-and-manipulations)
- [`field($field_name)`](#fieldfield_name)
- [`get($tag = 'div', $modifiers = [])`](#gettag--div-modifiers--)
- [`prune(array $exclusions)`](#prunearray-exclusions)
- [`only(array $inclusions)`](#onlyarray-inclusions)
- [`is($value)`](#isvalue)
- [`lessThan($value)` / `greaterThan($value)`](#lessthanvalue--greaterthanvalue)
- [Special Fields](#special-fields)
- [Google Maps Field](#google-maps-field)
- [`settings($field_name, $additional_classes = [])`](#settingsfield_name-additional_classes--)
- [`get_buttons($field_name, $modifiers = [])` / `the_buttons($field_name, $modifiers = [])`](#get_buttonsfield_name-modifiers----the_buttonsfield_name-modifiers--)
- [CLI](#cli)
- [Available commands](#available-commands)
- [Configuration](#configuration)
- [Supported fields](#supported-fields)
- [Full Support](#full-support)
- [Third party fields:](#third-party-fields)
- [Special Fields](#special-fields-1)
- [VS Code Extension](#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:
```bash
composer require mvrk/icenberg
```
make sure autoloading is set up in functions.php - something like:
```php
$composer_path = $_SERVER['DOCUMENT_ROOT'] . '/../vendor/';
if (file_exists($composer_path)) {
require_once $composer_path . 'autoload.php';
}
```
Make sure you have ACF Pro installed. The library also supports [ACF Gravity forms](https://wordpress.org/plugins/acf-gravityforms-add-on/) plugin.
#### Initialise
```php
use MVRK\Icenberg\Icenberg;
$ice = new Icenberg($layout = 'block_name', $prefix = 'block', $post_id = false);
```
#### `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:
```php
if (have_rows('content_blocks', $id)) :
while (have_rows('content_blocks', $id)) : the_row();
get_template_part('inc/blocks/block_template');
endwhile;
endif;
```
Initialise with ACFs `get_row_layout()` in your block template:
```php
use MVRK\Icenberg\Icenberg;
$ice = new Icenberg(get_row_layout());
$ice->the_element('quote');
$ice->the_element('attribution');
$ice->the_element('portrait');
```
## 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:
```php
use MVRK\Icenberg\Icenberg;
$icenberg = new Icenberg(strtolower($block['title']));
$icenberg::wrap(
[
$icenberg->get_element('quote'),
$icenberg->get_element('attribution'),
$icenberg->get_element('portrait'),
],
$block,
true
);
```
### 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'
```php
$field_name = $ice->get_element('field_name');
echo $field_name;
```
#### `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.
```php
$ice->the_element('field_name');
```
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
```php
$ice->the_element('field_name, options');
```
#### `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:
```php
$ice->enclose('text', [
$ice->get_element('cta_heading')
$ice->get_element('cta_content'),
]);
```
will generate:
```html
I'm a heading, look at me!
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
```
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).
```php
$random_text = "I am some random text, isn't it wonderful?";
$ice->enclose('text', [
$ice->get_element('cta_heading'),
$random_text
]);
```
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.
```html
the_element('motif_blurple');
endif; ?>
```
## 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.
```php
$lady_in_red = $ice->value('dancing_with_me');
```
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.
```php
$ice->field($field_name)
```
#### `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.
```php
$ice->field('saxaphone')->get()
```
#### `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.
```php
$group = $ice->field('bad_singers')->prune(['chris_de_burgh', 'cliff_richard'])->get();
```
#### `only(array $inclusions)`
| Argument | Type | Required | Description |
|--------------|--------|----------|-----------------------------------|
| `$inclusions`| array | Yes | Field names to include in the group/repeater output |
```php
$group = $ice->field('great_singers')->only(['chris_de_burgh'])->get('marquee');
```
#### `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.
```php
if ($ice->field('font_colour')->is('red')) :
$ice->the_element('font_colour');
else :
echo 'oh no';
endif;
```
#### `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.
```php
if ($ice->field('range_test')->lessThan(51)) :
$class = 'text_' . $ice->field('range_test')->field;
$ice->enclose($class, [
$ice->get_element('cta_content'),
$ice->get_element('cta_image'),
]);
endif;
```
## 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)
```php
function acf_google_map_field($api)
{
$api['key'] = GOOGLE_MAPS_API_KEY;
return $api;
}
add_filter('acf/fields/google_map/api', 'acf_google_map_field');
```
#### `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()`:
```php
$classes = ['banana', 'orange'];
$block_settings = get_sub_field($block_settings);
$settings = $ice->settings($block_settings, $classes);
$ice->enclose ($settings, [
$ice->get_element('cheese_board'),
$ice->get_element('flame_thrower')
])
```
or in regular php/html
```html
>
...whatever you want
```
which will print out something like
```html
"class='orange orange_padding_top_300 orange_skin_purple' id='cheese_board'"
```
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.
```php
$is_wp_cli = defined('WP_CLI') && WP_CLI;
if ($is_wp_cli) {
\MVRK\Icenberg\Commands\Bootstrap::setup();
}
```
### 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:
```yaml
block_directory_name: 'blocks' #change the default block directory name
sass_path: 'src/sass/blocks' #specify a location for sass partials
google_maps_api_key: ''
```
## 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.
[Icenberg Snippets](https://marketplace.visualstudio.com/items?itemName=coderjerk.icenberg-snippets&ssr=false#overview)