WordPress Express

This project is my attempt at using Node.js and Express to consume data from a WordPress database using GraphQL and Relay and React and...other stuff. This repo is the codebase for wordexpress.io, where I will write articles and documentation explaining how it works.

It's built using Webpack, and requires Node V 5.0.0. You might be able to get away with 4.0, but really just tighten up and use 5.0.

Docs on Medium

Part 1 - Introduction

Part 2 - The Setup

Part 3 - The Schema

Getting Started

Just run npm install and then npm run startdev To build for production, run npm run build, which creates a dist folder in the root directory which contains production-ready code. You can run npm start which will start the express server using code in the dist folder.

Defining Your Application Settings

You'll notice a settings folder, which contains JSON files for development. This is where you can define settings for uploads, WP database connection, and some other things. Change accordingly. For production, create a prod.json file in the same format as dev.json.

Upload Settings

This project uses Amazon AWS with an S3 bucket. If you are hosting your media files on the same server as your WP installation, set amazonS3 to false and set the uploads directory accordingly. If you are using S3, set don't include 'wp-content/uploads' to the end of the setting - it will be added for you.

Database Settings

This should be pretty self-explanatory: simply enter in the name of your database, username and password, and host. Make sure these are inside of "private", or else they'll be available on the client (WHICH IS BAD).

##Connecting Your WordPress Database This project uses WordExpress Schema, an NPM package I wrote specifically for this project. WordExpress schema allows you to quickly connect to a WordPress database using your database settings. It provides some out-of-the-box WordPress models (like Post, Postmeta, Terms, etc.) and some queries. For more details, read the documentation. Here is how it's being used in this project.

import { WordExpressDatabase } from 'wordexpress-schema';
import { publicSettings, privateSettings } from '../settings/settings';

/*
  Example settings object:
  publicSettings: {
    uploads: "http://wordexpress.s3.amazonaws.com/",
    amazonS3: true
  },
  privateSettings: {
    wp_prefix: "wp_",
    database: {
      name: "wpexpress_dev",
      username: "root",
      password: "",
      host: "127.0.0.1"
    }
  }
*/

const { name, username, password, host } = privateSettings.database;
const { amazonS3, uploads } = publicSettings;

const connectionDetails = {
  name: name,
  username: username,
  password: password,
  host: host,
  amazonS3: amazonS3,
  uploadDirectory: uploads
}

const Database = new WordExpressDatabase(connectionDetails);
const ConnQueries = Database.queries;

export default ConnQueries;

Setting the Landing Page

When you run npm startdev for the first time, you'll probably get an error saying "cannot find page-title of undefined." This is probably because you haven't set a landing page in WordPress. By default, the LandingPage component queries a post with the post-name (AKA slug) of "homepage". If you are using a fresh WordPress installation, simply create a page and give it a slug of "homepage." If you are working with an exsiting WordPress database, you can change which page that gets loaded by changing the page query in the LandingPage component. See below:

export default Relay.createContainer(LandingPage, {
  fragments: {
    viewer: () => Relay.QL`
      fragment on User {
        page(post_name:"homepage"){
					id,
					post_title
					post_content
				}
      }
    `,
  },
});

Simply change "homepage" to anything you want. Keep in mind that it queries the post-name (AKA slug), not the post-title.

Using React Components as Layouts

You can use any React component you'd like as a page layout by using a custom field in WordPress. First, in your application add the layout to the Layouts object in the layouts directory. The Layouts object stores some basic parameters that the WordpressPage component will read. It looks like this:

import PostList from '../posts/PostList.js';
import DefaultLayout from './DefaultLayout.js';

const Layouts = {
  'Default': {
    Component: DefaultLayout,
    showPosts: false
  },
  'PostList': {
    Component: PostList,
    showPosts: true,
    postType: 'post',
    limit: 10
  }
};


export default Layouts;

Then, simply add a react_layout custom field to your WordPress page. The value of the field must be the name of the layout in the Layouts object. Here's how you can add custom fields to a page.

##Playing With GraphQL For experimentation purposes, I've kept the GrapiQL IDE publically available so you can play aroud with querying the WordExpress database. Check it out here.

React by default

The project runs with React by default and hot replacement of changes to the modules.

React CSS Modules

SASS files loaded into components are locally scoped and you can point to class names with javascript. You can also compose classes together, also from other files. These are also hot loaded. Read more about them here.

Babel and Linting

Both Node server and frontend code runs with Babel. And all of it is linted. With atom you install the linter package, then linter-eslint and linter-jscs. You are covered. Also run npm run eslint or npm run jscs to verify all files. I would recommend installing language-babel package too for syntax highlighting

Beautify

With a beautify package installed in your editor it will also do that

NoellyB76 / WordPressExpress