Gutenberg blocks met REACT/JSX/SASS

REACT: Het Framework waarop de Gutenberg Editor is gebaseerd

REACT is een javascript framework dat door Facebook ontwikkeld werd om hun producten, dus bijvoorbeeld Facebook en Instagram,  makkelijker en sneller te kunnen bouwen.  Met de komst van Gutenberg maakt REACT ook deel uit van de WordPress core. UI componenten zijn nu ontwikkeld met REACT.  Het is dus vereist om Gutenberg blocks met REACT te bouwen. Ook een groot aantal tutorials en voorbeelden, en dus ook de Gutenberg core blocks zijn hiermee ontwikkeld.

JSX als template engine:

JSX is een template engine zoals bijvoorbeeld Handelbars of Underscore.  In het kort: Je kunt HTML Code en Javascript code “Mixen” waarbij HTML, zoals gewoonlijk, de structuur bepaald en je kunt Javascript inzetten om variabelen binnen je HTML structuur te gebruiken. Uiteindelijk wordt de uitkomst als HTML gerendeerd voordat het aan de cliënt gepresenteerd wordt.
Een klein voorbeeld hiervan is:

const name = ‘Thomas Scheper’;
const element = <h1>Hallo, {name}</h1>;

De HTML gaat er uiteindelijk als volgt uitzien: 
<h1> Hallo, Thomas Scheper</h1>

REACT samen met JSX is een vaak gebruikte combinatie.  Ook hier zul je vele voorbeelden en tutorials over Gutenberg Blocks vinden. Als je meer over REACT en JSX wilt weten, kijk hier: https://reactjs.org/docs/getting-started.html

SASS om de style te defineren

SASS is een preproccessor die code naar CSS compileert. Met behulp van SASS kun je bijvoorbeeld variabelen definiëren en meerdere keren gebruiken of functies definiëren om css code te genereren.

Ook Gutenberg maakt gebruik van SASS. Daarom gaan ook wij SASS binnen deze opzet gebruiken. Het is echter niet noodzakelijk, je kunt net zo goed een andere CSS precompiler of een gewoon CSS bestand gebruiken. Wil je meer weten over SASS, lees dan hier verder: https://sass-lang.com/

NPM om alle benodigde onderdelen snel en makkelijk in je project te laden

in ons tutorial gebruiken wij NPM als bron voor code packages. Om REACT en JSX te kunnen gebruiken hebben we verschillende javascript functionaliteit en libraries nodig  die we met behulp van een package file vanuit NPM kunnen halen.  Als je NPM nog niet geïnstalleerd hebt, kijk hier voor meer informatie: https://docs.npmjs.com/getting-started/installing-node

Filestructuur:

Binnen de wp-content/plugins directory gaan we een nieuwe map “my-first-gutenberg-block” maken. De hierna volgende bestanden en bestandsmappen moeten aangemaakt worden. Waarvoor al deze bestanden nodig zijn gaan we verder onderaan nog uitleggen:

• my-first-gutenberg-block [map]
  • package.json [.json file]
  • .babelrc [init . file]
  • webpack.config.js [.js file]
  • my-first-gutenberg-block.php  [.php file]
  • src [map]
    • scss [map]
      • block.scss [.scss file]
    • js [map]
      • block.js [.js file]
    • index.js [.js file]

package.json: 

dit .json bestand  wordt door NPM gebruikt  om alle benodigdheden voor onze Gutenberg Block op te halen. Hierdoor hoef je deze packages niet zelf bij elkaar te zoeken en handmatig te downloaden. Alles wordt via NPM geregeld.; 

{
    "name": "my-first-gutenberg-block",
    "version": "1.0.0",
    "license": "GPL-2.0-or-later",
    "main": "src/js/block.js",
    "devDependencies": {
        "babel-core": "^6.25.0",
        "babel-loader": "^7.1.1",
        "babel-plugin-transform-react-jsx": "^6.24.1",
        "babel-preset-env": "^1.6.0",
        "classnames": "^2.2.6",
        "cross-env": "^5.0.1",
        "css-loader": "^1.0.0",
        "extract-text-webpack-plugin": "^4.0.0-beta.0",
        "style-loader": "^0.23.1",
        "webpack": "^4.21.0",
        "webpack-cli": "^3.1.2",
        "node-sass": "^4.9.4",
        "sass-loader": "^7.1.0”,
        "react": "^16.5.2",
        "react-dom": "^16.5.2"
    },
    "scripts": {
        "dev": "webpack --mode development ./src/index.js --output ./dist/main.js --watch",
        "build": "webpack --mode production ./src/index.js --output ./dist/main.js --watch"
    }
}

Nadat je dit bestand klaar hebt, ga naar je commando line tool en cd naar de plugin map (in dit voorbeeld dus wp-content/plugins/my-first-gutenberg-block) Hier kun je nu met de command “ npm install ” het installeren van alle relevante bestanden doorvoeren. In feite installeert NPM alle packages en dependencies, die deze package eventueel nog nodig hebben. 

Na de installatie zul je enkele nieuwe bestanden en de map “node_modules” in je plugin locatie tegenkomen. 

.babelrc:

Dit is het config bestand van Babel. Babel compileert alle JSX code naar javascript code. Meer hoef je over babel op dit moment eigenlijk ook niet te weten. Het bestand moet er als volgt uit komen te zien:

{
  "presets": [
    [ "env", {
      "modules": false,
      "targets": {
        "browsers": [
          "last 2 Chrome versions",
          "last 2 Firefox versions",
          "last 2 Safari versions",
          "last 2 iOS versions",
          "last 1 Android version",
          "last 1 ChromeAndroid version",
          "ie 11"
        ]
      }
    }]
  ],
  "plugins": [
     [ "transform-react-jsx", {
       "presets": [       "pragma": "wp.element.createElement"
     }]
  ]
}

webpack.config.js:

Webpack luistert als het ware naar een bestand, en is er in ons geval verantwoordelijk voor, om zowel JSX code naar  Javascript, als ook SASS code naar CSS te compileren.  Zodra dit bestand veranderd wordt, compileert het automatisch naar het gewenste formaat. Als compiler wordt babel met de boven genoemde config gebruikt. Hiervoor is ook nog het plugin “extract-text-webpack-plugin” nodig omdat webpack zelf geen .css bestanden kan genereren. Om op dezelfde manier als Gutenberg blocks gebruik te kunnen maken van WordPress objecten (zoals wp.editor, wp.blocks, …),  gaan wij  ook deze hier definiëren. Op deze manier worden ook deze bestanden binnen ons gecompileerde .js bestand ter beschikking gesteld. 

const path = require('path');
const ExtractTextPlugin = require('extract-text-webpack-plugin');
const wplib = [
    'blocks',
    'components',
    'date',
    'editor',
    'element',
    'i18n',
    'utils',
    'data',
    'compose'
];

module.exports = {
    entry: {main: './src/index.js'},
    output: {
        path: path.resolve(__dirname, 'dist'),
        filename: 'main.js',
        library: ['wp', '[name]'],
        libraryTarget: 'window'
    },
    externals: wplib.reduce((externals, lib) => {
        externals[`@wordpress/${lib}`] = {
            window: ['wp', lib]
        };

        return externals;
    }, {
        'react': 'React',
        'react-dom': 'ReactDOM',
    }),    plugins: [
        new ExtractTextPlugin('style.css')
    ],
    module: {
        rules: [
            {
                test: /\.js$/,
                exclude: /node_modules/,
                use: {
                    loader: "babel-loader"
                }
            },
            {
                test: /\.scss$/,
                use: ExtractTextPlugin.extract(
                        {
                            fallback: 'style-loader',
                            use: ['css-loader', 'sass-loader']
                        })
            }
        ]
    }
};

my-first-gutenberg-block.php:

Dit is het gewone plugin bestand. Nadat een plugin geïnstalleerd is, wordt dit bestand als ingang gebruikt. In ons geval gaan we alleen maar het benodigde javascript bestand laden (let op: het is niet block.js, maar block.build.js. dit is het gecompileerde .js bestand.

<?php
/**
 * Plugin Name: Gutenberg Block: My first Gutenberg block	
 * Description: Gutenberg block build with REACT/JSX to learn how it works
 * Author: Thomas Scheper
 * Author URI:.nl
 * Version: 1.0.http://awwwesome0
 * License: GPL2+
 * License URI: http://www.gnu.org/licenses/gpl-2.0.txt
 */

defined('ABSPATH') || exit;

function my_first_gutenberg_block() {
    wp_enqueue_style('my-first-gutenberg-block-css', plugins_url('dist/style.css', __FILE__));

    wp_register_script(
            'my-first-gutenberg-block-js', 
            plugins_url('dist/main.js', __FILE__), array('wp-blocks', 'wp-element', 'wp-i18n', 'wp-data')
    );
    
    register_block_type('awww/my-first-gutenberg-block', array(
        'editor_script' => 'my-first-gutenberg-block-js',
        'editor_style' => 'my-first-gutenberg-block-css'
    ));
}

add_action('init', 'my_first_gutenberg_block');

Zoals je kunt zien gebruiken wij niet direct het src/block.scss en het src/block.js  bestand als plugin style respectievelijk plugin js source. Deze bestanden worden later gecompileerd naar de dist map. Hoe dit gebeurt ga je verder hieronder leren. 

src/index.js:

Dit bestand wordt in ons webpack configuratiebestand gebruikt om als het ware alle bestanden, waarop webpack moet reageren, te “verzamelen”. Nu staan hier alleen twee bestanden in: block.scss en block.js.  Als je deze tutorial uit wilt breiden of later uitgebreidere Gutenberg Blocks gaat ontwikkelen, is dit de perfecte plaats om alle componenten bij elkaar te brengen. 

import "./scss/block.scss";
import "./js/block.js”;

src/scss//block.scss:

In dit bestand kunnen styles voor de Gutenberg Block toegevoegd worden. Deze worden binnen de Gutenberg Editor gebruikt en zijn niet voor het frontend bedoeld. Voor nu laten we deze gewoon leeg. 

src/js/block.js:

Hier beginnen we met het programmeren van onze REACT/JSX code. Omdat het alleen maar om de opzet van de werkomgeving voor Gutenberg Blocks gaat, houden we dit voorbeeld simpel.

const { __ } = wp.i18n;
const { registerBlockType } = wp.blocks;

registerBlockType( 'awww/my-first-gutenberg-block', {
	title: __( 'Static Block Example with JSX' ),
	icon: 'format-quote',
	category: 'common',
	edit() {
	    return (
	        <p>Yeah my first block!</p>
	    );
	},
	save() {
	    return (
	        <p>Yeah my first block!</p>
	    );
	},
} );

Run npm:

Wij hebben nu de config bestanden aangemaakt,  alle benodigdheden vanuit NPM in onze plugin geladen en alle basisbestanden toegevoegd. 

Dit is alles wat je nodig hebt om met een zelf gebouwde plugin in REACT en JSX te starten. Het enige wat nog mist is het compileren van het block.js bestand naar block.build.js.  Hiervoor starten wij in onze plugin de commandline code “npm run dev”.

Vanaf nu wordt er continue gekeken of er veranderingen zijn binnen onze plugin bestanden. Zo ja, worden deze direct gecompileerd naar dist/main.js en dist/style.css  De map “dist” + die bestanden worden automatisch aangemaakt en ook veranderd. Dit zijn je gecompileerde bestanden die wij ook binnen het php bestand van onze plugin gebruiken.