Download the PHP package mvrk/icenberg without Composer

Icenberg

Icenberg is an opinionated abstraction library for writing websites with Advanced Custom 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) by handling the rendering of blocks and fields for you.

Using Icenberg's element methods you can render acf fields and blocks inside a block, or anywhere you choose, fully scaffolded with BEM classes and settings which makes writing structured and re-usable CSS much more manageable. Icenberg takes care of checking a fields existence and skips over non-rendering fields. It can even apply settings as modifier classes.

Using the CLI you can generate full-featured ACF Gutenberg blocks (or flexible content row templates) with all the necessary files and with the boilerplate abstracted and settings applied in one command.

Who is it for?

Icenberg is written by professional (human) web developers who use it every day. It is intended for use by other professional or hobbyist web developers who build WordPress themes, by choice or otherwise. If you don't understand the problem it solves, don't like writing (non boilerplate) code or prefer Tailwind to BEM then this probably isn't for you. This is not a WordPress plugin.

Requirements

• PHP 8+
• ACF Pro 6+
• WordPress 7+
• Composer
• WP CLI

Getting Started

Install via composer:

Make sure autoloading is set up in functions.php - something like:

Initialise in functions.php

Optionally add the CLI commands

Use in a template

Configuration

To configure for your own preferences and environment, place 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:

Basic Usage

Gutenberg Block

You can use Icenberg in an ACF Gutenberg block render template, whether generated using the CLI or hand made (you should try the CLI). 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.

Flexible Content

The following example takes place inside ACF's the_row() - ie:

Initialise with ACFs get_row_layout() in your block template:

API

Icenberg()

instantiate an Icenberg object at block or template level.

get_element()

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()

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. You can pass ANY field. If the field is supported, Icenberg will process the field and its sub-fields

To retrieve a global option simply pass a comma-delimited string to the_element() or get_element() - it must be all as one string as opposed to separate args, and it must be comma-delimited, where the first part is the field name and the second part is the options name.

enclose() / get_enclose()

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.

Value()

You can us the value() method to return the 'raw', value of a given field without checking for existence or specifying if it is a sub-field. As this just returns the value there are no special considerations for individual field types.

field()

you can use icenberg to evaluate fields and do some more complex field manipulation too, using the field() method in conjunction with the below methods. field() takes the field name as an argument and returns the icenberg instance for method chaining.

get()

Returns the icenbergified field HTML (in the same way as get_element). Optionally pass a tag for the wrapper.

prune()

Pass an array of field names to the prune method to remove them from a group or from a repeater row.

only()

Whitelist fields in a group

is()

returns true if the value of the field equals the argument passed to is(). You don't need to check for a fields existence before using these methods as they will do it for you and return false if they don't.

has()

Returns true if the field value (an array/iterable like a select multiple or checkbox field) contains the given value. Returns false if the field doesn't exist or isn't iterable.

lessThan() / greaterThan()

Self-explanatory, both take an integer as an argument. Warning: If you use it on a non-numeric field it will return false.

settings()

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 an ID too.

If using the wrap() method, you don't need to manually specify settings. wrap() looks for a field group called ' block_settings' and one called 'settings' on the block and uses this method to parse them into modifiers on the intermediate wrapper.

Example using settings in enclose():

or in regular php/html

which will print out something like

Depending on the settings in your group.

wrap()

Wraps an array of rendered elements in the standard Icenberg block wrapper, mirroring the wrapping that WordPress applies in the backend so the frontend matches. Optionally accepts a background element which can be rendered behind the wrapped content.

InnerBlocks

Helper for rendering Gutenberg's <InnerBlocks/> tag inside an ACF block render template, with the appropriate BEM class applied automatically so it slots in with the rest of your block markup. Pass an array of allowed block names and the current Icenberg instance.

member()

Pulls a single sub-field value directly out of a group field without having to render the whole group. Useful when you only need one value from a settings or config group.

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)

CLI

you can use the Icenberg CLI to rapidly bootstrap Icenberg blocks. This extends wp-cli so you need to have that installed and working first.

Available commands

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 and send a scss file to the sass directory. The block.json is opinionated so modify as required once its generated. Pay attention to the fact that the stylesheet is set to display in-editor only because we're assuming a workflow where you're compiling sass to the CSS file and enqueuing it globally on the frontend.

this is similar to the above but creates just the php and scss files for flexible content blocks.

Supported Add Ons

The library directly supports the following ACF plugins:

• ACF Gravity forms
• Table Field Add-on for ACF and SCF

Other plugins may be compatible if they use the built-in field names or aren't directly involved in the render.

Supported fields

Full Support

The following fields can be used with get_element() / the_element() and all other Icenberg methods:

• DatePicker
• DateTimePicker
• Gallery
• Google Maps
• Group
• IconPicker
• Image
• Link
• Number
• OEmbed
• Page Link
• Post Object
• Range
• Relationship
• Repeater
• Select
• Text
• Textarea
• TimePicker
• WYSIWYG

Element methods will quietly skip over any other default fields if they are included in a group or repeater.

Limited Support

The values of the following fields are available in the settings method or any of the field methods:

• ButtonGroup
• Checkbox
• Taxonomy
• User
• TrueFalse

Submit a GitHub issue if you have a use case for directly rendering any of these and we'll consider it.

Third party fields:

• Forms
• Table

VS Code Extension

An extension with useful snippets is available for Virtual Studio Code.

Icenberg Snippets