Gilded WordPress

Easily synchronize content between the file system and WordPress.

Support this project by donating on Gratipay.

TOC

• Getting Started
• Installation
• Usage
• Node.js API
  • Exports
  • Client Methods - Validation
  • Client Methods - Synchronization
  • Client Methods - Logging
  • Client Methods - Utilities
  • Directory Structure
  • taxonomies.json
  • Post Files
• PHP API
• Permissive Uploads
• License

Getting Started

Resources are uploaded to /gw-resources/{HOME_URL}/. If you'd like a friendlier name, you can set up a redirect in your web server.

If you have problems uploading resources, check the Permissive Uploads section.

Installation

npm install gilded-wordpress

Usage

var wordpress = require( "gilded-wordpress" );
var client = wordpress.createClient({
	url: "wordpress.dev",
	username: "admin",
	password: "admin",
	dir: "my-content"
});

client.sync(function( error ) {
	if ( error ) {
		console.error( error );
		return;
	}

	console.log( "Successfully synchronized WordPress." );
});

Node.js API

Exports

wordpress.createClient( options )

Creates a new client instance.

• options: A hash of options that apply to all requests for the new client.
  • username: The username for the WordPress account.
  • password: The password for the WordPress account.
  • url: The URL for the WordPress install.
  • dir: The path to the directory containing all taxonomies, posts, and resources (see Directory Struture).
  • host (optional): The actual host to connect to if different from the URL, e.g., when deploying to a local server behind a firewall.
  • blogId (optional; default: 0): The blog ID for the WordPress install.
  • verbose (optional; default: false): Whether logging should be verbose.

wordpress.Client

The constructor used for client connections. Useful for creating extensions.

Client Methods - Validation

client.validate( callback )

Validates all data.

• callback (function( error )): A callback to invoke when the validation is complete.

client.validateXmlrpcVersion( callback )

Verifies whether the WordPress plugin is installed and has the same version as the Node.js module.

• callback (function( error )): A callback to invoke when the validation is complete.

client.validateTerms( callback )

Validates all terms.

• callback (function( error )): A callback to invoke when the taxonomies have been validated.

client.validatePosts( callback )

Validates all posts.

• callback (function( error )): A callback to invoke when the posts have been validated.

Client Methods - Synchronization

client.sync( callback )

Synchonizes all data.

• callback (function( error )): A callback to invoke when the synchronization is complete.

client.syncTerms( callback )

Synchronizes all terms.

• callback (function( error )): A callback to invoke when the taxonomies have been synchronized.

client.syncPosts( callback )

Synchronizes all posts.

• callback (function( error )): A callback to invoke when the posts have been synchronized.

client.syncResources( callback )

Synchronizes all resources.

• callback (function( error )): A callback to invoke when the resources have been synchronized.

Client Methods - Logging

The client methods log various information as they perform their tasks. These methods are designed to be overridden for custom logging or to hook into an existing logging system.

client.log( message )

Logs a message. Defaults to console.log().

• message: A message to log.

client.logError( message )

Logs an error message. Defaults to console.error().

• message: An error message to log.

Client Methods - Utilities

The utility methods exist to help build custom extensions to the client. All callbacks from the utility methods are invoked within the context of the client instance.

client.waterfall( steps, callback )

Asynchronously executes a set of functions.

Equivalent to async.waterfall(), but with context preserved.

• steps: An array of functions to perform. Each function is passed a callback (function( error, result1, result2, ... )) which must be called when the function is complete. The first argument is an error and any further arguments will be passed as arguments in order to the next step.
• callback (function( error )): A callback to invoke when all steps have been completed or a step has resulted in an error.

client.forEach( items, iterator, complete )

Asynchronous version of Array#forEach().

Equivalent to async.forEachSeries(), but with context preserved.

• items: An array to iterate over.
• iterator (function( item, callback )): A callback to invoke for each item of the array.
  • item: The current item of the array.
  • callback (function( error )): A callback to invoke after processing the item.
• complete (function( error )): A callback to invoke when all items have been iterated over or an item resulted in an error.

client.recurse( dir, iterator, complete )

Asyncrhonously walk all files in a directory, recursively. All files within a directory are walked before recursing.

• dir: The path to a directory to walk.
• iterator (function( path, callback )): A callback to invoke for each file within the directory.
  • path: The path to the current file.
  • callback (function( error )): A callback to invoke after processing the file.
• complete (function( error )): A callback to invoke when all files have been iterated over or a file resulted in an error.

Directory Structure

The directory passed to the client instance has the following structure:

dir
├── posts
│   └── <post_type>
│       └── <post_name>.html
├── resources
│   └── <file>.<ext>
└── taxonomies.json

The posts directory must only contain <post_type> directories. The <post_type> directories must be named to exactly match a post type, e.g., post or page. All custom post types are supported.

The resources directory is completely freeform. Resources of any type will be uploaded based on the current directory structure.

taxonomies.json

The taxonomies.json file defines all used taxonomy terms. You can only manage terms, all taxonomies must already exist in WordPress.

{
	"<taxonomy_name>": [
		{
			"name": "My Term",
			"description": "My term is awesome",
			"slug": "my-term"
		},
		{
			"name": "My Other Term",
			"slug": "my-other-term",
			"children": [
				{
					"name": "I'm a child term!",
					"slug": "hooray-for-children"
				}
			]
		}
	]
}

Slugs and names are required.

Post Files

Post files must be HTML, containing the content of the post. Post data can be specified as JSON in a <script> element at the top of the file.

<script>{
	"title": "My Post",
	"termSlugs": {
		"<taxonomy_name>": [
			"<hierarchical_slug>"
		]
	}
}</script>
<p>I'm a post!</p>

The post type and parent are determined based on the directory structure. termSlugs must match a hierarchical slug defined in taxonomies.json.

PHP API

Constants

GW_VERSION

The installed version of Gilded WordPress.

GW_RESOURCE_DIR

The path to the resources directory for the current site.

Methods

gw_resources_dir( url )

Gets the resources directory for a specific site.

• url: The URL for the site.

Permissive Uploads

Depending on what resources you're uploading, you may need to change some WordPress settings. Here are a few settings that might help:

// Disable more restrictive multisite upload settings.
remove_filter( 'upload_mimes', 'check_upload_mimes' );

// Give unfiltered upload ability to super admins.
define( 'ALLOW_UNFILTERED_UPLOADS', true );

// Allow additional file types.
add_filter( 'upload_mimes', function( $mimes ) {
	$mimes[ 'eot' ] = 'application/vnd.ms-fontobject';
	$mimes[ 'svg' ] = 'image/svg+xml';
	$mimes[ 'ttf' ] = 'application/x-font-ttf';
	$mimes[ 'woff' ] = 'application/font-woff';
	$mimes[ 'xml' ] = 'text/xml';
	$mimes[ 'php' ] = 'application/x-php';
	$mimes[ 'json' ] = 'application/json';
	return $mimes;
});

// Increase file size limit to 1GB.
add_filter( 'pre_site_option_fileupload_maxk', function() {
	return 1024 * 1024;
});

License

Copyright Scott González. Released under the terms of the MIT license.

Support this project by donating on Gratipay.