@frontkom/gutenberg-js

Table of contents

• Installation

• Development
• Global variables

* [Post Types](#post-types)
  * [Wp block](#wp-block)
* [Posts and Pages](#posts-and-pages)
* [Categories](#categories)
* [Media](#media)
* [Taxonomies](#taxonomies)
* [Blocks](#blocks)
* [Themes](#themes)

• Usage

• Customize your Gutenberg

• Rendering Dynamic Blocks
• Custom blocks

Installation

$ npm install @frontkom/gutenberg-js

Dependencies

// webpack.config.js
const CopyWebpackPlugin = require('copy-webpack-plugin');

module.exports = {
    ...
    plugins: [
        new CopyWebpackPlugin([
            { from: 'node_modules/tinymce/plugins', to: `${ your_root_path }/plugins` },
            { from: 'node_modules/tinymce/themes', to: `${ your_root_path }/themes` },
            { from: 'node_modules/tinymce/skins', to: `${ your_root_path }/skins` },
        ], {}),
    ],
    ...
}

<script src="https://unpkg.com/react@16.6.3/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@16.6.3/umd/react-dom.production.min.js"></script>
<script src="https://unpkg.com/moment@2.22.1/min/moment.min.js"></script>
<script src="https://code.jquery.com/jquery-1.12.4.min.js" integrity="sha256-ZosEbRLbNQzLpnKIkEdrPv7lOy9C27hHQ+Xp8a4MxAQ=" crossorigin="anonymous"></script>

Development

1. Check @wordpress packages versions from Gutenberg release we want to upgrade to and update package.json file (npm outdated could help).
2. Check if there are new @wordpress packages and import them in index.js file'.
3. Check if our overrides are updated and work well with new @wordpress packages versions.
4. Check if there are new blocks containing images and apply data attributes override.
5. Test, test and test. We can use g-editor to test the editor.
6. To do: unit tests could help

Global variables

// globals.js

window.wp = {
    apiFetch,
    url: { addQueryArgs },
    ...,
};

window.userSettings = {
    uid: 2, // Among other things, this uid is used to identify and store editor user preferences in localStorage
};

// set your root path
window.wpApiSettings = {
    root: 'YOUR_ROOT_PATH',
    ...,
};

apiFetch

function apiFetch(options) {
    // Do something with those options like calling an API
    // or actions from your store...
}

Post Types

Wp Block

{
    "capabilities": { ... }
    "description": "",
    "hierarchical": false,
    "labels": { ... }
    "name": "Blocks",
    "slug": "wp_block",
    "taxonomies": [],
    "rest_base": "blocks",
    "supports": { ... }
    "viewable": false,
    "_links": { ... }
}

Posts and Pages

Categories

Taxonomies

Media

{
    ...,
    id: 1527069591355,
    link: MEDIA_LINK_HERE,
    source_url: MEDIA_URL_HERE,
    // Additionaly, you can add some data attributes for images for example
    data: { entity_type: 'file', entity_uuid: 'e94e9d8d-4cf4-43c1-b95e-1527069591355' }
    ...,
}

{
    headers: {
        get: value => {
            if (value === 'allow') {
                return [ 'POST' ];
            }
        },
    },
}

Blocks

{
    content: "<!-- wp:paragraph -->↵    <p>3</p>↵    <!-- /wp:paragraph -->",
    id: 131,
    title: "my block",
}

Themes

{
    ...,
    theme_supports: {
        formats: [ 'standard', 'aside', 'image', 'video', 'quote', 'link', 'gallery', 'audio' ],
        'post-thumbnails': true,
    },
    ...,
}

url

/**
 * External dependencies
 */
import { parse, format } from 'url';
import { parse as parseQueryString, stringify } from 'querystring';

/**
 * Appends arguments to the query string of the url
 *
 * @param  {String} url   URL
 * @param  {Object} args  Query Args
 *
 * @return {String}       Updated URL
 */
export function addQueryArgs(url, args) {
    const queryStringIndex = url.indexOf('?');
    const query = queryStringIndex !== -1 ? parse(url.substr(queryStringIndex + 1)) : {};
    const baseUrl = queryStringIndex !== -1 ? url.substr(0, queryStringIndex) : url;

    return baseUrl + '?' + stringify({ ...query, ...args });
}

Usage

// Importing global variables that Gutenberg requires
import './globals';

// Importing domReady and editPost modules
import { domReady, editPost } from '@frontkom/gutenberg-js';

// Don't forget to import the style
import '@frontkom/gutenberg-js/build/css/block-library/style.css';
import '@frontkom/gutenberg-js/build/css/style.css';

// DOM element id where editor will be displayed
const target = 'editor';

// Post properties
const postType = 'post'; // or 'page'
const postId = 123;

// Some editor settings
const settings = {
    alignWide: true,
    availableTemplates: [],
    allowedBlockTypes: true,
    disableCustomColors: false,
    disableCustomFontSizes: false,
    disablePostFormats: false,
    titlePlaceholder: "Add title",
    bodyPlaceholder: "Write your story",
    isRTL: false,
    autosaveInterval: 10,
    styles: [],
    postLock: {
        isLocked: false,
    },
    ...
    // @frontkom/gutenberg-js settings
    canAutosave: false,  // to disable the Editor Autosave feature (default: true)
    canPublish: false,   // to disable the Editor Publish feature (default: true)
    canSave: false,      // to disable the Editor Save feature (default: true)
    mediaLibrary: false, // to disable the Media Library feature (default: true)
};

// Post properties to override
const overridePost = {};

// Et voilá... Initializing the editor!
window._wpLoadGutenbergEditor = new Promise(function (resolve) {
    domReady(function () {
        resolve(editPost.initializeEditor(target, postType, postId, settings, overridePost));
    });
});

Gutenberg Stores

// Importing select and dispatch methods from @frontkom/gutenberg-js package
import { data } from '@frontkom/gutenberg-js';

// Use dispatch to change the state of something
data.dispatch('core/edit-post').openGeneralSidebar('edit-post/block');
data.dispatch('core/edit-post').closeGeneralSidebar();

// Use select to get the state of something
data.select( 'core/editor' ).getEditedPostContent();
// <!-- wp:paragraph -->
// <p>Hello</p>
// <!-- /wp:paragraph -->

Registering Custom Blocks

import { blocks, editor } from '@frontkom/gutenberg-js';

const {
    AlignmentToolbar,
    BlockControls,
    RichText,
} = editor;

blocks.registerBlockType('custom/my-block', {
    title: 'My first block',
    icon: 'universal-access-alt',
    category: 'common',
    attributes: {
        content: {
            type: 'array',
            source: 'children',
            selector: 'p',
        },
        alignment: {
            type: 'string',
        },
    },
    edit({ attributes, className, setAttributes }) {
        const { content, alignment } = attributes;

        function onChangeContent( newContent ) {
            setAttributes( { content: newContent } );
        }

        function onChangeAlignment( newAlignment ) {
            setAttributes( { alignment: newAlignment } );
        }

        return [
            <BlockControls>
                <AlignmentToolbar
                    value={ alignment }
                    onChange={ onChangeAlignment }
                />
            </BlockControls>,
            <RichText
                tagName="p"
                className={ className }
                style={ { textAlign: alignment } }
                onChange={ onChangeContent }
                value={ content }
            />
        ];
    },
    save({ attributes, className }) {
        const { content, alignment } = attributes;

        return (
            <RichText.Content
                className={ className }
                style={ { textAlign: alignment } }
                value={ content }
            />
        );
    },
});

Customize your Gutenberg

window.customGutenberg = { ... };

Events

window.customGutenberg = {
    ...,
    events: {
        'OPEN_GENERAL_SIDEBAR': function(action, store) {
            console.log( 'OPEN_GENERAL_SIDEBAR', action, store );
        },
        'CLOSE_GENERAL_SIDEBAR': function(action, store) {
            console.log( 'CLOSE_GENERAL_SIDEBAR', action, store );
        },
    },
    ...,
};

Rendering Dynamic Blocks

<!-- wp:block {"ref":1537389905603} /-->

<!-- wp:core-embed/twitter {"url": "https://twitter.com/drupalgutenberg/status/1040203765452820480", "type": "rich", "providerNameSlug": "twitter"} -->
<figure class="wp-block-embed-twitter wp-block-embed is-type-rich is-provider-twitter">
    <div class="wp-block-embed__wrapper">
        https://twitter.com/drupalgutenberg/status/1040203765452820480
    </div>
</figure>
<!-- /wp:core-embed/twitter -->

<!-- wp:latest-posts /-->

Custom Blocks

Creating and Registering

const myFirstBlock = {
    title: 'My first block!',
    icon: 'universal-access-alt',
    category: 'cloudblocks',

    edit() {
        return <p>Hello editor.</p>;
    },

    save() {
        return <p>Hello saved content.</p>;
    },
};

const category = {
    slug: 'cloudblocks',
    title: 'Gutenberg-Cloud Blocks',
};

const { dispatch, select } = wp.data;

const currentCategories = select('core/blocks').getCategories().filter(item => item.slug !== category.slug);

dispatch('core/blocks').setCategories([ category, ...currentCategories ]);

const { registerBlockType } = wp.blocks;

registerBlockType(`${category.slug}/my-first-block`, { category: category.slug, ...hero.settings });

const { dispatch, select } = wp.data;
const { registerBlockType } = wp.blocks;

// Setting block's properties
const myFirstBlock = {
    title: 'My first block!',
    icon: 'universal-access-alt',
    category: 'cloudblocks',

    edit() {
        return <p>Hello editor.</p>;
    },

    save() {
        return <p>Hello saved content.</p>;
    },
};

// Setting category's properties
const category = {
    slug: 'cloudblocks',
    title: 'Gutenberg-Cloud Blocks',
};

// Checking the category
const currentCategories = select('core/blocks').getCategories().filter(item => item.slug !== category.slug);
dispatch('core/blocks').setCategories([ category, ...currentCategories ]);

// Registering the new block
registerBlockType(`${category.slug}/my-first-block`, myFirstBlock);

Sharing