automattic / picard

A prototype theme that uses React and WP-API

Picard

Picard is an experimental prototype WordPress theme that makes use of React and the new WP-API. It means, that instead of loading new page every time you click a link, it uses background AJAX requests to WP REST API to fetch data without reloading the page.

Please note, it is STRONGLY recommended that this theme is not used in any production environment. It is purely for educational and testing purposes. This theme is under development so it is not recommended that you rely on any aspect of it.

Installation

1. Working WordPress installation

First, prepare a proper WordPress environment:

• You will obviously need a working WordPress installation,
• You will also need WP REST API. It is a plugin (with plans to incorporate into the WordPress core) that creates REST API to be used by the theme. Plugin is currently NOT in plugins repository, you have to upload the files manually. Install and activate the WP REST API plugin (make sure that you are using the master branch – the default is currently develop),
• Set your permlink structure to /%year%/%monthnum%/%day%/%postname%/.

2. Theme building (for team building go to your local meetup)

Unlike other themes, this one uses a build process. JavaScript is an interpreted language, but we need to take certain steps (like transpiling React JSX syntax or SASS CSS syntax) to take the files from development phase to production. You will need the following tools:

• node.js and npm - node is an command line JavaScript interpreter that is used for build process. npm stands for node package manager. You can install both from nodejs.org,
• gulp is a build system running on node. Once you install node and npm, type npm install -g gulp to install gulp in your system (-g flag installs package globally so you will now have gulp command in your command line).

Next, you have to set up the theme:

1. Download the theme files to wp-content/themes directory of your WordPress installation. You can clone this repository (git clone [email protected]:Automattic/Picard.git) or just press download on the right side - also here (remember to unzip).
2. In Picard directory, run npm install to install the node dependencies. npm will take care of the rest (npm installs dependencies listed in the package.json file).
3. In Picard directory, run gulp build to compile the JavaScript and SASS. Gulp will know what to do, because proper actions are listed in the gulpfile.js,
4. In Picard directory, run gulp watch to actively develop the theme and have the styles and JS files automatically update. Watch command listens for file changes and starts build process every time you save a source file.

Contributing

Pull requests and issues are very much welcome!

Todos

A not exhaustive list of all things Picard still needs to do:

1. Work with different permalink structures.
2. Allow user to set a static front page.
3. Allow user to use sidebars and widgets.
4. Support all permalinks (archives, search etc)

picard's Issues

Fatal error: Class 'WP_JSON_Comments' not found...

Just followed all of the install instructions laid out in the readme file, however upon activating the theme this is what I see:

Fatal error: Class 'WP_JSON_Comments' not found in /srv/www/wordpress-trunk/wp-content/themes/Picard/functions.php on line 163

I do have the REST API plugin installed, so I don' t think that's the issue. . .

Here's the terminal record of the gulp build process:

› gulp build
[09:15:28] Warning: gulp version mismatch:
[09:15:28] Global gulp is 3.9.0
[09:15:28] Local gulp is 3.8.11
[09:15:29] Using gulpfile ~/vagrant-local/www/wordpress-trunk/wp-content/themes/Picard/gulpfile.js
[09:15:29] Starting 'styles'...
[09:15:29] Finished 'styles' after 271 ms
[09:15:29] Starting 'scripts'...
[09:15:31] Finished 'scripts' after 1.74 s
[09:15:31] Starting 'build'...
[09:15:31] Finished 'build' after 4.73 μs

Any ideas?

Uncaught TypeError: Cannot read property 'hasClass' of null

I'm getting this error on line 88 of picard.js

(if ( ( document.querySelector( 'body' ).hasClass( 'page' ) || document.querySelector( 'body' ).hasClass( 'single' ) ) && document.querySelector( '.hentry' ).hasClass( 'has-post-thumbnail' ) ) {)

Server-Side Rendering

In the initial page load, it would be great if React components be rendered to HTML server-side. Doing this would improve performance, compatibility, SEO, and reliability. We'd get these benefits without having to write our code once in PHP and then again in JavaScript.

I know this is a pretty major task, but there's some prior work that could serve as the foundation:

• The v8js extension for PHP
• ReactJS.net, which is React + ClearScript (the C# answer to v8js) + utility functions.
• This server-side React with PHP tutorial from Stoyan Stefanov.

README needs some improvement

We need more thorough explanations of setting up node, gulp etc.

Theme kills admin access if activated before WP REST API plugin

Should have noted this one earlier when it happened, but I just thought of it again - I failed to activate the WP REST API plugin before activating the theme and then couldn't access the admin to correct it without removing the theme folder to deactivate it. There was an error message but since I didn't record it at the time I can't grab it for you right now, although it should be pretty easy to recreate - it was about a missing function that the plugin provides, I believe.

Seems like a check to see if the plugin is active would be good.

(Sorry to drop issues that I can't immediately help with!)

Node-sass compile error on windows

Well, this is not necessarily Picard issue, but is there any downsides to use gulp-sass rather than node-sass?

Add customizer preview support

WordPress 4.7 has specific improvements to the customizer to make the preview compatible with JS-driven themes. I was originally thinking I would submit a PR to Picard to add support, but the theme fatal errored for me and so I found another theme to add support to. I did so for Anadama, see ryelle/Anadama-React#5

If Picard gets freshened up to be compatible with WordPress 4.7 and the REST API committed to core, I'd like to help work out integration with the customizer.

Project roadmap?

I really like this project, thank you.

The Readme states

"Please note, it is STRONGLY recommended that this theme is not used in any production environment. It is purely for educational and testing purposes."

and I was wondering if this changed since the beginning of this project.

Is anyone here using it in production?
I read that wordpress.com is moving towards WP-API and react and maybe something like this is happening in the wordpress theme community also.

Also, serverside rendering in picard, did anyone already manage to integrate it?

gulp build fails with AssertionError: missing path

[13:10:35] Using gulpfile C:\Ampps\www\wpdev\wp-content\themes\Picard\gulpfile.js
[13:10:35] Starting 'styles'...
[13:10:35] 'styles' errored after 32 ms
[13:10:35] AssertionError: missing path
at Module.require (module.js:352:3)
at require (internal/module.js:12:17)
at requireFn (C:\Ampps\www\wpdev\wp-content\themes\Picard\node_modules\gulp-load-plugins\index.js:37:14)
at Object.defineProperty.get (C:\Ampps\www\wpdev\wp-content\themes\Picard\node_modules\gulp-load-plugins\index.js:59:18)
at Gulp. (C:\Ampps\www\wpdev\wp-content\themes\Picard\gulp\styles.js:5:10)
at module.exports (C:\Ampps\www\wpdev\wp-content\themes\Picard\node_modules\orchestrator\lib\runTask.js:34:7)
at Gulp.Orchestrator._runTask (C:\Ampps\www\wpdev\wp-content\themes\Picard\node_modules\orchestrator\index.js:273:3)
at Gulp.Orchestrator._runStep (C:\Ampps\www\wpdev\wp-content\themes\Picard\node_modules\orchestrator\index.js:214:10)
at Gulp.Orchestrator.start (C:\Ampps\www\wpdev\wp-content\themes\Picard\node_modules\orchestrator\index.js:134:8)
at C:\Users\Muluneh\AppData\Roaming\npm\node_modules\gulp-cli\lib\versioned^3.7.0\index.js:46:20

Should the readme point to the repo plugin now?

https://wordpress.org/plugins/rest-api/ is now up. Should this be the place we point as opposed to master?

Warnings on npm install

I got the following:

npm WARN optional dep failed, continuing [email protected]
[email protected] install /Users/karmatosed/Vagrant-sites/vagrant-local/www/restplay/htdocs/wp-content/themes/Picard/node_modules/gulp-sass/node_modules/node-sass
node scripts/install.js

[email protected] postinstall /Users/karmatosed/Vagrant-sites/vagrant-local/www/restplay/htdocs/wp-content/themes/Picard/node_modules/gulp-sass/node_modules/node-sass
node scripts/build.js

Spawns infinite customizer menus

I experienced an infinite spawning (until Chrome crashed) of customizer menus when I tried to preview before activating the theme.

I'll try again with a fresh dev install.

Autoprefixing in Gulp causes errors that block style.css compile.

The following error shows upon running gulp styles:

        throw er; // Unhandled 'error' event
              ^
CssSyntaxError: /Users/kwight/Sites/trunk/src/wp-content/themes/picard/style.css.map:3:1: Unknown word

Commenting out autoprefixer from the equation allows the compile to complete.

gulp build error: Libsass bindings not found

After setup, running gulp build for the first time gave me this error.

 ❯ gulp build
[22:28:06] Warning: gulp version mismatch:
[22:28:06] Global gulp is 3.9.1
[22:28:06] Local gulp is 3.8.11
[22:28:07] Using gulpfile ~/Vagrant/www/dalbey/htdocs/wp-content/themes/picard/gulpfile.js
[22:28:07] Starting 'styles'...
[22:28:07] 'styles' errored after 43 ms
[22:28:07] Error: `libsass` bindings not found. Try reinstalling `node-sass`?

Node v6.9.4
Mac OS Sierra

react-tools has been deprecated

It looks like the gulp build command requires react-tools to process the scripts. I'm stuck, so I'll leave this here so someone smarter than me can update the gulpfile.js items.

npm WARN deprecated [email protected]: react-tools is deprecated. For more information, visit https://fb.me/react-tools-deprecated

server:Picard Jesse$ gulp build
[14:52:41] Using gulpfile ~/Documents/Websites/www.mysite.dev/wp-content/themes/Picard/gulpfile.js
[14:52:41] Starting 'styles'...
[14:52:42] Finished 'styles' after 596 ms
[14:52:42] Starting 'scripts'...

events.js:72
        throw er; // Unhandled 'error' event
              ^
Error: EMFILE, open '/Users/Jesse/Documents/Websites/www.mysite.dev/wp-content/themes/Picard/node_modules/react/package.json'

Work with subfolder installs

This ties into your item about working with different permalink structures (listed in the ReadMe) but currently no content displays if WordPress is installed in a subdirectory.

For example, on my local machine I have a bunch of WordPress installations all within a single parent directory accessed something like:

127.0.0.1/core/
127.0.0.1/dev/

Picard didn't work to display post/ page content when installed into one of those, but it does work when installed in the root install at

127.0.0.1

'WP_JSON_Comments' bug

Voila :
Fatal error: Class 'WP_JSON_Comments' not found in C:\EasyPHP\data\localweb\explora\wp-content\themes\picard\functions.php on line 164

Widgets, where art thou?

Leading on from #15 , displaying widgets in an API-based theme is currently problematic, as widgets are not available in either the wpcom nor WP-API APIs.

Since widgets are all very similar class extensions, one approach would be to take a simple widget, come up with a template, and then use that general template as a base for other widgets in a new endpoint.

Of course, the best first course of action would be finding out what previous work/discussion (if any) have happened at Automattic and in the WP-API project.

header.jsx / footer.jsx not rendered

Hey, I am pretty new to React and my question might be a little bit noobish:
There are JSX files for the header and footer but it seems that they are not rendered to an elementByID? Is there a reason for not doing so?

Page Loading UX

Can we implement something like http://chieffancypants.github.io/angular-loading-bar/ with Picard? I came from angular and quite new with react. I saw that there are no direct feedback whenever user click on links other than the url changing.

I think that it is important to give user something to see that we are actually loading something in the background, maybe something like http://cezary.github.io/react-loading/. But i'm still figuring out on how to implement it in Picard (or use that component in react).

Identify components to componentize

Let's figure out some components! CC @kwight

Initial ideas that come to mind that follow the standardish class structure pretty nicely:

|- masthead
|-- site-title

|- navigation

|- hentry // for post and pages?
|--- entry-title
|--- entry-meta // and maybe components for the stuff that lives here
|--- entry-content

|- comment-box
|--- comment-form
|--- comments
|----- comment
|------- author ingo/meta stuff?
|------- comment-content
|------- comment-actions // reply/favorite/etc

|- widget

Add minify/uglify options to Gulp config

The compiled picard.js file currently equates to about 691KB uncompressed. When compressed with something like uglify, it comes in at about 260KB.

Of course, in any production environment, we would want it compressed. It would be super to have some additional gulp commands that allow you to build for production.