wordless: A PHP repository from dbeard

Wordless is an opinionated WordPress plugin that dramatically speeds up and enhances your custom themes creation. Some of its features are:

A structured, organized and clean theme organization (taken directly from Rails);
The ability to create a new theme skeleton directly within the WordPress backend interface;
The ability to write PHP code using the beautiful Haml templating system;
The ability to write CSS stylesheets using the awesome Sass syntax and the Compass framework;
The ability to write Javascript logic in Coffeescript;
The ability to merge and compress Javascript assets using Yahoo YUI Compressor;
A growing set of handy and documented helper functions ready to be used within your views;

Requirements, installation and configuration

Wordless will make your web development easier, faster and fun again, you will write less and be more productive; you'll love it more than anything else you've ever loved before and there will be rainbows and ponies randomly popping up everywhere.

But what's the catch? It needs Ruby. No I mean it, it seriously needs Ruby.

If you are not familiar with Ruby you may follow the following tutorial for getting up a fully functional Ruby environment in less than 5 minutes. Otherwise, if you are already fluent in Ruby, Wordless depends on compass, sprockets and coffee-script. The coffee-script gem requires a valid javascript runtime available on your machine, see the ExecJS readme to learn about the supported ones.

The RVM Way

Our recommended way to get Ruby installed on your system is RVM, the Ruby Version Manager. This beautiful project creates a tight, clean and well organized Ruby platform in your system. Moreover it's deadly easy to setup (this requires git installed):

bash < <(curl -s https://raw.github.com/wayneeseguin/rvm/master/binscripts/rvm-installer )

Now reload your shell and install your preferred Ruby version by running (this will take some time, go have a coffee or something):

rvm install 1.8.7

Whew, now you have a fully functional Ruby environment! The following oneliner will create a new gemset called wordless, install the gems wordless needs and create some handy symbolic links:

rvm use 1.8.7@wordless --create --default && gem install therubyracer sprockets compass coffee-script thor yui-compressor && rvm wrapper 1.8.7@wordless wordless compass ruby

Now you should be able to know the location of your RVM-wrapped ruby executables typing which wordless_ruby and which wordless_compass on your terminal.

The Cool Stuff

Okay, now we can get everything up and running :)

The production server doesn't need any extra-dependencies, as all the assets get pre-compiled by Wordless on the development machine and then statically served;
Enable Apache mod_rewrite module (a2enmod rewrite) and make sure WordPress nice permalinks are enabled under the WP "Settings > Permalinks" section (for example, choose month and name);
Download the Wordless plugin, drop it in the wp-content/plugins directory and enable it from the WP "Plugins" section;
Create a brand new Wordless theme directly within the WP backend, from the WP "Appearance > New Wordless Theme" section;
Configure the path of your compass and ruby executables within the config/initializers/wordless_preferences.php config file.

Wordless Theme anatomy

That's a typical Wordless theme directory structure:

your_theme_dir
├── assets
│   ├── fonts
│   ├── images
│   ├── javascripts
│   └── stylesheets
├── config
│   ├── initializers
│   └── locales
├── theme
│   ├── assets
│   │   ├── javascripts
│   │   └── stylesheets
│   ├── helpers
│   └── views
│       └── layouts
└── index.php

Let's see in detail what is the purpose of all those directories:

Routing

The index.php serves as a router to all the theme views.

<?php

if (is_front_page()) {
  render_view("static/homepage)");
} else if (is_post_type_archive("portfolio_work")) {
  render_view("portfolio/index");
} else if (is_post_type("portfolio_work")) {
  render_view("portfolio/show");
}

As you can see, you first determine the type of the page using WordPress conditional tags, and then delegate the rendering to some particular view.

Theme Views (`theme/views/.haml` or `theme/views/.php`)

That's the directory where you'll find yourself coding for most of the time. Here you can create a view for each main page of your theme, using Haml syntax or plain PHP. Feel free to create subdirectories to group toghether the files. Here's what could be an example for the typical WordPress loop in an archive page:

/ theme/views/posts/archive.haml
%h2 Blog archive
%ul.blog_archive
  - while (have_posts())
    - the_post()
    %li.post= render_partial("posts/single")

/ theme/views/posts/_single.haml
%h3= link_to(get_the_title(), get_permalink())
.content= get_the_filtered_content()

Wordless uses Phamlp for your Haml views, a great PHP port of the Haml ruby gem. In this little snippet, please note the following:

The view is delegating some rendering work to a partial called _single.haml. Partial templates – usually just called “partials” – are another device for breaking the rendering process into more manageable chunks. Partials are named with a leading underscore to distinguish them from regular views, even though they are referred to without the underscore.
There's no layout here, just content: the layout of the page is stored in a secondary file, placed in the theme/views/layouts directory;
We're already using two of the 40+ Wordless helper functions, link_to() and get_the_filtered_content(), to DRY up this view.

Don't you already feel so much better?

Layouts (`theme/views/layouts` directory)

Just like Rails, when Wordless renders a view as a response, it does so by combining the view with a layout. Within a layout, you have access to the yield() helper to combine it with the main content:

!!! 5
%html(html_attrs())
  %head

    / Charset
    %meta(http-equiv="Content-type" content="text/html;charset=UTF-8")
    / Title
    %title= get_page_title(bloginfo('name'), " – ")
    / Stylesheets
    = stylesheet_link_tag("application")
    / HTML5 Shiv
    /[if lt IE 9]
      = javascript_include_tag("http://html5shiv.googlecode.com/svn/trunk/html5.js")

  %body.home-layout
    = render_partial("common/header")
    = yield()
    = render_partial("common/footer")
    = javascript_include_tag("jquery", "application")

Please note that for content that is shared among all pages in your application, you can use partials directly from layouts.

Helpers (`theme/helpers/*.php` files)

Helpers are basically small functions that can be called in your views to help keep your code stay DRY. Create as many helper files and functions as you want and put them in this directory, they will all be required within your views, together with the default Wordless helpers. These are just a small subset of all the 40+ tested and documented helpers Wordless gives you for free:

lorem() - A "lorem ipsum" text and HTML generator;
pluralize() - Attempts to pluralize words;
truncate()- Truncates a given text after a given length;
new_post_type() and new_taxonomy() - Help you create custom posts and taxonomy;
distance_of_time_in_words() - Reports the approximate distance in time between two dates;

Initializers (`config/initializers/*.php` files)

Remember the freaky functions.php file, the one where you would drop every bit of code external to the theme views (custom post types, taxonomies, wordpress filters, hooks, you name it). That was just terrible, isn't it? Well, forget it. Wordless let you split you code into many modular initializer files, each one with a specific target:

config/initializers
├── custom_post_types.php
├── hooks.php
├── menus.php
├── wordless_preferences.php
└── thumbnail_sizes.php

These are just some file name examples: you can organize them the way you prefer. Each file in this directory will be automatically required by Wordless.

Locale files (`config/locales` directory)

Just drop all your theme locale files in this directory. Wordless will take care of calling load_theme_textdomain() for you.

Assets

WordPress has to different places where you want to put your assets:

Place all the static images and vendor assets (i.e. jQuery and vendor JS plugins) into the assets/* directory;
Place all your custom, project related assets into the theme/assets/*.

Stylesheets

Include the assets in your views using stylesheet_link_tag() helper.

= stylesheet_link_tag("screen")

This will produce the following HTML, pointing to the assets/stylesheets directory:

<link href="/wp-content/themes/YOUR_THEME/assets/stylesheets/screen.css" media="all" rel="stylesheet" type="text/css" />

If Wordless can't find this static file, it will search for a file named screen.sass or screen.scss inside the theme/assets/stylesheets directory, and will automatically compile and serve it on the fly using Compass under the cover.

To make things faster, Wordless handles nicely precompilation caching, so a new compile will happen only if the file itself really changed since the last recompilation.

Javacripts

Include the assets in your views using javascript_include_tag() helper.

= javascript_include_tag("application")

This will produce the following HTML, pointing to the assets/javascripts directory:

<script src="/wp-content/themes/YOUR_THEME/assets/javascripts/application.js" type="text/javascript"></script>

If Wordless can't find this static file, it will search for a file named application.js.coffee or application.js inside the theme/assets/javascripts directory, and will automatically compile (if needed) and serve it on the fly using the Sprockets preprocessor under the cover. Coffescript is optional, you can just write normal javascript as well.

To make things faster, Wordless handles nicely precompilation caching, so a new compile will happen only if the file itself really changed since the last recompilation.

Additional recommended plugins

Wordless is not meant to be a bloated, all-included tool. This is why we recommend adding some other plugins to get the most out of your beautiful WP developer life:

Simple Fields: a complete solution to add different types of custom fields to your custom posts. We love Simple fields so much that Wordless embeds a dedicated helper file just for it;
Options Framework: makes it easy to include an options panel in any WordPress theme;
Wordmove: a great gem (from yours truly) to automatically mirror local WordPress installations and DB data back and forth from your local development machine to the remote staging server;

Known problems and limitations

Wordless has not been tested on Windows machines;
From WP 3.2 WordPress has ceased to support PHP4, and so does Wordless;
Documentation still to be written;
The assets static baking for production is still pre-alpha and needs some rewrite (it's rough, but it works);
The routing part can be drammaticaly improved to make it more readable and DRY;
This is alpha software, everything is still subject to change :)

License

(The MIT License)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

dbeard/wordless