Added support for Example

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)

docs/example.md

@@ -1,5 +1,4 @@
 # Example
-
 ```twig
 {#
   Title: Testimonial

docs/parameters.md

@@ -18,5 +18,6 @@
  SupportsMode: (true|false)
  SupportsMultiple: (true|false)
  SupportsReusable: (true|false)
+ Example: (JSON format)
 #}
 ```

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" }
+#}
+
+<blockquote>
+    <p>{{ fields.testimonial }}</p>
+    <cite>
+      <span>{{ fields.author }}</span>
+    </cite>
+</blockquote>
+
+```
+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
+<blockquote>
+    <p>Testimonial</p>
+    <cite>
+      <span>John Doe</span>
+    </cite>
+</blockquote>
+
+```
+
+You can also create an image preview and put it like this:
+```twig
+<img src="https://example.com/img/testominial-preview.jpg" alt="testimonial example">
+```

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
 #}
+
+<blockquote data-{{ block.id }}>
+    <p>{{ fields.testimonial }}</p>
+    <cite>
+      <span>{{ fields.author }}</span>
+    </cite>
+</blockquote>
+
+<style type="text/css">
+  [data-{{ block.id }}] {
+    background: {{ fields.background_color }};
+    color: {{ fields.text_color }};
+  }
+</style>
 ```

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";
 		}