Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs and API: clarify naming around block registration #842

Merged
merged 12 commits into from
Jun 1, 2017
Prev Previous commit
Next Next commit
Update inline documentation in blocks/api.
  • Loading branch information
mtias authored and youknowriad committed Jun 1, 2017
commit c86eebccd7d4f9b6b88d5ec8bb969bf4730657f4
10 changes: 7 additions & 3 deletions blocks/api/factory.js
Original file line number Diff line number Diff line change
Expand Up @@ -10,20 +10,24 @@ import { get, castArray, findIndex, isObjectLike, find } from 'lodash';
import { getBlockSettings } from './registration';

/**
* Returns a block object given its type and attributes
* Returns a block object given its type and attributes.
*
* @param {String} blockType BlockType
* @param {Object} attributes Block attributes
* @return {Object} Block object
*/
export function createBlock( blockType, attributes = {} ) {
// Get the type definition associated with a registered block.
const blockSettings = getBlockSettings( blockType );

// Do we need this? What purpose does it have?
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's create a separate issue for this. I think our current use-cases don't really need it as much as it seems they would.

let defaultAttributes;
if ( blockSettings ) {
defaultAttributes = blockSettings.defaultAttributes;
}

// Blocks are stored with a unique ID, the assigned type name,
// and the block attributes.
return {
uid: uuid(),
blockType,
Expand All @@ -35,7 +39,7 @@ export function createBlock( blockType, attributes = {} ) {
}

/**
* Switch a block into one or more blocks of the new block type
* Switch a block into one or more blocks of the new block type.
*
* @param {Object} block Block object
* @param {string} blockType BlockType
Expand All @@ -52,7 +56,7 @@ export function switchToBlockType( block, blockType ) {
find( transformationsTo, t => t.blocks.indexOf( blockType ) !== -1 ) ||
find( transformationsFrom, t => t.blocks.indexOf( block.blockType ) !== -1 );

// If no valid transformation, stop. (How did we get here?)
// Stop if there is no valid transformation. (How did we get here?)
if ( ! transformation ) {
return null;
}
Expand Down
34 changes: 19 additions & 15 deletions blocks/api/parser.js
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,8 @@ export function parseBlockAttributes( rawContent, blockSettings ) {
* @return {Object} All block attributes
*/
export function getBlockAttributes( blockSettings, rawContent, attributes ) {
// Merge any attributes from comment delimiters with block implementation
// Merge any attributes present in comment delimiters with those
// that are specified in the block implementation.
attributes = attributes || {};
if ( blockSettings ) {
attributes = {
Expand All @@ -69,18 +70,18 @@ export function getBlockAttributes( blockSettings, rawContent, attributes ) {
* @return {?Object} An initialized block object (if possible)
*/
export function createBlockWithFallback( blockType, rawContent, attributes ) {
// Use type from block content, otherwise find unknown handler
// Use type from block content, otherwise find unknown handler.
blockType = blockType || getUnknownTypeHandler();

// Try finding settings for known block type, else again fall back
// Try finding settings for known block type, else fall back again.
let blockSettings = getBlockSettings( blockType );
const fallbackBlockType = getUnknownTypeHandler();
if ( ! blockSettings ) {
blockType = fallbackBlockType;
blockSettings = getBlockSettings( blockType );
}

// Include in set only if settings were determined
// Include in set only if settings were determined.
// TODO do we ever expect there to not be an unknown type handler?
if ( blockSettings && ( rawContent.trim() || blockType !== fallbackBlockType ) ) {
// TODO allow blocks to opt-in to receiving a tree instead of a string.
Expand Down Expand Up @@ -123,27 +124,30 @@ export function parseWithTinyMCE( content ) {
}
);

// Create a custom HTML schema
// Create a custom HTML schema.
const schema = new tinymce.html.Schema();
// Add <wp-block> "tags" to our schema

// Add <wp-block> "tags" to our schema.
schema.addCustomElements( 'wp-block' );
// Add valid <wp-block> "attributes" also

// Add valid <wp-block> "attributes" also.
schema.addValidElements( 'wp-block[slug|attributes]' );
// Initialize the parser with our custom schema

// Initialize the parser with our custom schema.
const parser = new tinymce.html.DomParser( { validate: true }, schema );

// Parse the content into an object tree
// Parse the content into an object tree.
const tree = parser.parse( content );

// Create a serializer that we will use to pass strings to blocks.
// TODO: pass parse trees instead, and verify them against the markup
// shapes that each block can accept.
const serializer = new tinymce.html.Serializer( { validate: true }, schema );

// Walk the tree and initialize blocks
// Walk the tree and initialize blocks.
const blocks = [];

// Store markup we found in between blocks
// Store markup we found in between blocks.
let contentBetweenBlocks = null;
function flushContentBetweenBlocks() {
if ( contentBetweenBlocks && contentBetweenBlocks.firstChild ) {
Expand All @@ -164,19 +168,19 @@ export function parseWithTinyMCE( content ) {
while ( currentNode ) {
if ( currentNode.name === 'wp-block' ) {
// Set node type to document fragment so that the TinyMCE
// serializer doesn't output its markup
// serializer doesn't output its markup.
currentNode.type = 11;

// Serialize the content
const rawContent = serializer.serialize( currentNode );

// Retrieve the attributes from the <wp-block> tag
// Retrieve the attributes from the <wp-block> tag.
const nodeAttributes = currentNode.attributes.reduce( ( memo, attr ) => {
memo[ attr.name ] = attr.value;
return memo;
}, {} );

// Retrieve the block attributes from the original delimiters
// Retrieve the block attributes from the original delimiters.
const attributesMatcher = /([a-z0-9_-]+)(="([^"]*)")?/g;
const blockAttributes = {};
let match;
Expand All @@ -187,7 +191,7 @@ export function parseWithTinyMCE( content ) {
}
} while ( !! match );

// Try to create the block
// Try to create the block.
const block = createBlockWithFallback(
nodeAttributes.slug,
rawContent,
Expand Down
4 changes: 2 additions & 2 deletions blocks/api/serializer.js
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ export function getCommentAttributes( realAttributes, expectedAttributes ) {
Object.keys( expectedAttributes )
);

// Serialize the comment attributes
// Serialize the comment attributes as `key="value"`.
return keys.reduce( ( memo, key ) => {
const value = realAttributes[ key ];
if ( undefined === value ) {
Expand All @@ -64,7 +64,7 @@ export function getCommentAttributes( realAttributes, expectedAttributes ) {
}

/**
* Takes a block list and returns the serialized post content
* Takes a block list and returns the serialized post content.
*
* @param {Array} blocks Block list
* @return {String} The post content
Expand Down