diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 807fd7e..8566c11 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -4,5 +4,6 @@ * [Example](example.md) * [Filters](filters.md) * [Previews](previews.md) +* [Using Example](using-example.md) * [Read More](read-more.md) * [Contributors](contributors.md) diff --git a/docs/example.md b/docs/example.md index 1312817..d7c760e 100644 --- a/docs/example.md +++ b/docs/example.md @@ -1,5 +1,4 @@ # Example - ```twig {# Title: Testimonial diff --git a/docs/parameters.md b/docs/parameters.md index c29c8b3..14b922c 100644 --- a/docs/parameters.md +++ b/docs/parameters.md @@ -18,5 +18,6 @@ SupportsMode: (true|false) SupportsMultiple: (true|false) SupportsReusable: (true|false) + Example: (JSON format) #} ``` diff --git a/docs/using-example.md b/docs/using-example.md new file mode 100644 index 0000000..f437de0 --- /dev/null +++ b/docs/using-example.md @@ -0,0 +1,44 @@ +# Using examples +From ACF 5.8.11 you can use **Example** to set example data for block previews. You can read more about this: +- [https://developer.wordpress.org/block-editor/developers/block-api/block-registration/](https://developer.wordpress.org/block-editor/developers/block-api/block-registration/) + +To do this in **Timber ACF Blocks** you need to create your block like this: +```twig +{# + Title: Testimonial + Description: Customer testimonial + Category: formatting + Icon: admin-comments + Keywords: testimonial quote "customer testimonial" + Mode: edit + Example: { "testimonial": "Testimonials", "author": "John Doe" } +#} + +
+

{{ fields.testimonial }}

+ + {{ fields.author }} + +
+ +``` +In **Example** we only pass the fields and their values as a valid JSON. + +## Using static HTML as preview +There are cases when we would like to use a static HTML as example. To do this create a file called `your-block-name-example.twig`. So if your block is called `testimonial.twig` than the example would be called `testimonial-example.twig`. + +This file would like this: +```twig +
+

Testimonial

+ + John Doe + +
+ +``` + +You can also create an image preview and put it like this: +```twig +testimonial example +``` diff --git a/readme.md b/readme.md index b59c225..2e31dc2 100644 --- a/readme.md +++ b/readme.md @@ -18,22 +18,30 @@ This plugin is build with help of contributors: Add twig templates to `views/blocks` which get and use ACF data. Each template requires a comment block with some data in it: ```twig {# - Block Name: (required) - Description: - Category: - Icon: - Keywords: (comma-separated) - Post Types: (comma-separated) - Mode: - Align: - Enqueue Style: - Enqueue Script: - Enqueue Assets: - Supports Align: (comma-separated) - Supports Anchor: (true|false) - Supports Custom Class Name: (true|false) - Supports Mode: (true|false) - Supports Multiple: (true|false) - Supports Reusable: (true|false) + Title: Testimonial + Description: Customer testimonial + Category: formatting + Icon: admin-comments + Keywords: testimonial quote "customer testimonial" + Mode: edit + Align: left + PostTypes: page post + SupportsAlign: left right + SupportsMode: false + SupportsMultiple: false #} + +
+

{{ fields.testimonial }}

+ + {{ fields.author }} + +
+ + ``` diff --git a/timber-acf-wp-blocks.php b/timber-acf-wp-blocks.php index 9338c48..01241af 100644 --- a/timber-acf-wp-blocks.php +++ b/timber-acf-wp-blocks.php @@ -66,6 +66,7 @@ function () { 'enqueue_assets' => 'EnqueueAssets', 'supports_custom_class_name' => 'SupportsCustomClassName', 'supports_reusable' => 'SupportsReusable', + 'example' => 'Example', ) ); @@ -154,6 +155,19 @@ function () { } } + // Suuport for "example". + if ( ! empty( $file_headers['example'] ) ) { + $json = json_decode( $file_headers['example'], true ); + $example_data = ( null !== $json ) ? $json : array(); + $example_data['is_example'] = true; + $data['example'] = array( + 'attributes' => array( + 'mode' => 'preview', + 'data' => $example_data, + ), + ); + } + // Register the block with ACF. acf_register_block_type( $data ); } @@ -189,11 +203,18 @@ function timber_blocks_callback( $block, $content = '', $is_preview = false, $po $context['classes'] = implode( ' ', $classes ); + $is_example = false; + + if ( ! empty( $block['data']['is_example'] ) ) { + $is_example = true; + $context['fields'] = $block['data']; + } + $context = apply_filters( 'timber/acf-gutenberg-blocks-data', $context ); $context = apply_filters( 'timber/acf-gutenberg-blocks-data/' . $slug, $context ); $context = apply_filters( 'timber/acf-gutenberg-blocks-data/' . $block['id'], $context ); - $paths = timber_acf_path_render( $slug, $is_preview ); + $paths = timber_acf_path_render( $slug, $is_preview, $is_example ); Timber::render( $paths, $context ); } @@ -203,13 +224,17 @@ function timber_blocks_callback( $block, $content = '', $is_preview = false, $po * * @param string $slug File slug. * @param bool $is_preview Checks if preview. + * @param bool $is_example Checks if example. */ -function timber_acf_path_render( $slug, $is_preview ) { +function timber_acf_path_render( $slug, $is_preview, $is_example ) { $directories = timber_block_directory_getter(); $ret = array(); foreach ( $directories as $directory ) { + if ( $is_example ) { + $ret[] = $directory . "/{$slug}-example.twig"; + } if ( $is_preview ) { $ret[] = $directory . "/{$slug}-preview.twig"; }