Merge pull request #75 from jverneaut/50-allow-creating-server-side-rendered-blocks

50 Allow creating server side rendered blocks

Author: jverneaut

__tests__/fixtures/processable/server-block/expected.index.js

@@ -0,0 +1,9 @@
+import { registerBlockType } from "@wordpress/blocks";
+
+import Edit from "./edit.js";
+import metadata from "./block.json";
+
+registerBlockType(metadata.name, {
+  edit: Edit,
+  save: () => null,
+});

__tests__/fixtures/processable/server-block/expected.js

@@ -0,0 +1,13 @@
+import { useBlockProps } from "@wordpress/block-editor";
+import ServerSideRender from "@wordpress/server-side-render";
+
+export default ({ attributes, setAttributes }) => {
+  return (
+    <section {...useBlockProps()}>
+      <ServerSideRender
+        block="custom/server-side-rendered"
+        attributes={{ title: attributes.title }}
+      ></ServerSideRender>
+    </section>
+  );
+};

__tests__/fixtures/processable/server-block/expected.json

@@ -0,0 +1,14 @@
+{
+  "name": "custom/input",
+  "title": "Input",
+  "textdomain": "input",
+  "$schema": "https://schemas.wp.org/trunk/block.json",
+  "apiVersion": 3,
+  "version": "0.1.0",
+  "category": "theme",
+  "example": {},
+  "attributes": { "align": { "type": "string", "default": "full" } },
+  "supports": { "html": false, "align": ["full"] },
+  "editorScript": "file:./index.js",
+  "render": "file:./render.php"
+}

__tests__/fixtures/processable/server-block/expected.php

@@ -0,0 +1,3 @@
+<section <?php echo get_block_wrapper_attributes(); ?>>
+  
+</section>

__tests__/fixtures/processable/server-block/input.html

@@ -0,0 +1,7 @@
+<section>
+  <!-- $$attributes$$ is subject to change and undocumented at the moment -->
+  <server-block
+    name="custom/server-side-rendered"
+    title="$$attributes.title$$"
+  ></server-block>
+</section>

docs/docs/common/_experimental.md

@@ -0,0 +1,3 @@
+:::danger
+Experimental features are subject to change, or their may be dropped entirely, depending on feedback and stability. Use with caution.
+:::

docs/docs/experimental/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Experimental",
+  "position": 5
+}

docs/docs/experimental/raw-javascript-expressions.mdx

@@ -0,0 +1,37 @@
+import Experimental from "@site/docs/common/_experimental.md";
+import CodeExample from "@site/src/components/CodeExample";
+
+# Raw javascript expressions
+
+<Experimental />
+
+Using the special `$$...$$` escape sequence, it is possible to use raw javascript expressions inside the editor.
+
+<CodeExample>
+  ```
+  <section>
+    <!-- This is yet another experimental API not yet implemented, stay tuned... -->
+    <block-attribute name="title" type="string"></block-attribute>
+    <block-attribute name="postType" default="pages"></block-attribute>
+
+    <div data-display="editor">
+      <!-- This will update the title attribute -->
+      <input
+        type="text"
+        value="$${attributes.title}$$"
+        onChange="$${(e) => setAttributes({ title: e.target.value })}$$"
+      />
+
+      <!-- This will update the postType attribute -->
+      <select
+        value="$${attributes.postType}$$"
+        onChange="$${(e) => setAttributes({ postType: e.target.value })}$$"
+      >
+        <option value="posts">Posts</option>
+        <option value="pages">Pages</option>
+      </select>
+    </div>
+
+  </section>
+  ```
+</CodeExample>

docs/docs/experimental/server-side-blocks.mdx

@@ -0,0 +1,62 @@
+import Experimental from "@site/docs/common/_experimental.md";
+import CodeExample from "@site/src/components/CodeExample";
+
+# Server side blocks
+
+<Experimental />
+
+The `<server-side>` element can be used to render a block server side using the `<ServerSideRender />` component from `@wordpress/server-side-render` package.
+
+To use it, first install the package with:
+
+```
+npm install @wordpress/server-side-render --save
+```
+
+## Rendering blocks on the server
+
+To render a block on the server, use the `<server-block>` element with the `name` attribute telling it which block to render.
+It uses the same API as the `<block>` element to define attributes.
+
+<CodeExample>
+  ```
+  <section>
+    <server-block name="custom/latest-posts-slider" postType="pages">
+      <attribute name="numberOfPosts">5</attribute>
+    </server-block>
+  </section>
+  ```
+</CodeExample>
+
+## When to use server side blocks
+
+Server side blocks are particularly useful when having to query posts, build listing pages, more generaly whenever you need to build a data-rich block.
+
+To build a block that display the latest posts from our site, we could first define a block in HTML that will be used in the editor and that will render itself on the server:
+
+```html title="custom/latest-posts.html"
+<section>
+  <server-block name="custom/latest-posts"></server-block>
+</section>
+```
+
+Then, we can define a `render.php` override by creating a `latest-posts.render.php` file alongside our `latest-posts.html` file that will get the latest posts and render them:
+
+```php title="custom/latest-posts.render.php"
+<?php
+
+// You custom query here
+$latest_posts = get_posts();
+
+?>
+
+<section <?= get_block_wrapper_attributes(); ?>>
+<?php foreach ($posts as $post) : ?>
+  <article>
+    <h3><?= $post->post_title; ?></h3>
+    <a href="<?= get_permalink($post); ?>">Read more</a>
+  </article>
+<?php endforeach; ?>
+</section>
+
+```

docs/docs/extra/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Extra",
-  "position": 5
+  "position": 6
 }