pono ono

This is a WordPress theme built using Timber and bigwheel a minimalist frontend framework for managing application state created by Jam3

Introduction

The project setup and gulp configuration is based on wordpress-gulp-starter-kit which is awesome and has solid docs. Definitely worth checking out before getting started working on this theme. Below is a list of customiztions I've made to the boilerplate.

Set up Timber
Add Browserify and Babelify to bundle scripts written in ES2015
Get rid of jshint and set up linter with standard js style
Get rid of unused boilerplate (livereload, rubySass, composer, bower)
Add some steps to the gulp dist task to replace script tag in base.twig to load minified javascript and delete the unminified version

Getting Started

1) Install WordPress & MAMP

Download and install MAMP
Open MAMP and click Preferences
Go to the Ports tab and make sure Apache is set to 8888. Go to the Web Server tab and make sure Apache is selected.
Also on the Web Server tab, set the 'Document Root' to the directory where you want to install WordPress.
Now click OK on the preferences dialogue and click Start Servers.
If your browser doesn't open automatically, click Open WebStart Page.
Click the link to phpMyAdmin (under the MySQL heading).
Now we can create a database for WordPress to use
On the left sidebar, click New.
The title of the database should be pono_ono.
Now that the database is created, you can go download the latest version of WordPress and copy the contents of the wordpress folder into the MAMP Document Root you defined earlier.
Now navigate your browser to localhost:8888 and you should see the WordPress installer.
Follow the wizard. Enter the site title as 'Pono Ono'. Then, when it asks for the name of your database, enter what you named it in step 10. Then it will ask for a username and password which should both just be root.
Voila! Your local installation of WordPress should be all set. You can login at localhost:8888/wp-admin.

2) Install Project Dependencies

3) Project Setup

Open the command line and navigate to the directory where you'd like to store the theme.

# Clone the repo
$ git clone https://github.com/mikehwagz/pono-ono.git

# Move into the directory
$ cd pono-ono

# Install depencencies listed in package.json using yarn
$ yarn

# Build the theme for the first time
$ gulp build

Migrate the Production Site to Local

In order to work on the site locally, you will need to get the database and content from the production site. To do so, use your administrative login credentials provided by me to login to the production site. Go to Tools > Migrate DB and export the database, being sure to "Find and Replace" according to the location of your local environment. Now, you can import this database locally via the phpMyAdmin page accessible via the MAMP WebStart page. Now, you need to go to the file manager of the production site which you can access via http://ponoonopoke.com/cpanel and login with credentials provided by Jack. Click File Manager and navigate to public_html/wp-content. Now ZIP up and download both the plugins and uploads directories. Upload these directories to your local installation of WordPress in the wp-content directory.

Symlinking the theme build directory into your local WordPress Install

Assuming that you are already running a local installation of WordPress and have taken the steps above to migrate all production data, we can create a symlink to the build directory generated by gulp in the theme directory. For example, my local installation of WordPress is located in ~/Documents/Sites/wordpress, and I have the theme directory on my Desktop. Assuming these file locations, you can create a symlink by running the following command:

$ ln -s ~/Desktop/pono-ono/build ~/Documents/Sites/wordpress/wp-content/themes/pono-ono

Now if you navigate to the destination you defined for the symlink, you should see an alias into the built theme directory. If you mess up and want to start over, you can always just delete the alias as you would any directory.

4) Development

With our dependencies installed and our theme directory linked to our WordPress installation, we are ready to start development.

First, we need to add an environment variable for the BASE directory of our site. It will usually just be / but in my case, I had to create this for my staging server which is /pono-ono/.

# create a new file in src/js called env.js
cat > src/js/env.js
# and whatever you type on the next line
# is inserted into the file.
# Hit ctrl+D to save those changes and then ctrl+C to exit the file.
export default 'YOUR_SERVER_BASE'
# in my case
export default '/'
# and for staging
export default 'pono-ono'

I've explained the available gulp commands in more detail below:

###gulp

Does everything that gulp build does but also opens up a browser window at localhost:3000. Now changes to any files in src will be live-reloaded on save using BrowserSync.

###gulp build

Transpiles and bundles together js using Browserify and Babelify to support ES2015 JavaScript syntax. Sticks both a minified and unminified bundle in build/js.
Compiles all scss files imported to src/scss/main.scss, autoprefixes, minifies, renames to style.css, and sticks it in build.
Copies all images, php files, and twig templates over to build as well.

###gulp dist

This command is used to generate a distribution of the theme.
Runs gulp build and then takes everything from the build directory and puts it in a dist/pono-ono directory.
Next, all images are optimized automatically.
Finally, the script tag in base.twig is updated to load the minified javascript file and then the unminified version is deleted.
Now the pono-ono directory inside dist should be all set for deployment.

❗ Remember: All development will take place in the src directory. The build and dist folders can be regenerated using gulp at anytime.

paperrobots / pono-ono