wordpressdev / wordless

Stop writing themes like it's 1998. All the power of Haml, Compass and Coffeescript, in your Wordpress theme.

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);
• Ability to create a new theme skeleton directly within the Wordpress backend interface;
• Ability to write PHP code using the beautiful Haml templating system;
• Ability to write CSS stylesheets using the awesome Sass syntax and the Compass framework;
• Ability to write Javascript logic in Coffeescript;
• A growing set of handy and documented helper functions ready to be used within your views;

Requirements, installation and configuration

1. Your development machine needs a ruby environment, and the compass, sprockets and coffee-script gem. The coffee-script gem requires a valid javascript runtime available on your machine, see the ExecJS readme to learn the supported ones;
2. The production server doesn't need any extra-dependencies, as all the assets get pre-compiled by Wordless on the development machine and statically served;
3. Enable Apache mod_rewrite module (a2enmod rewrite) and make sure Wordpress nice permalinks are enabled under the WP "Settings > Permalinks" section;
4. Download the Wordless plugin, drop it in the wp-content/plugins directory and enable it from the WP "Plugins" section;
5. Create a brand new Wordless theme directly within the WP backend, from the WP "Appearance > New Wordless Theme" section;
6. Specify the path of the compass and ruby executables within the config/initializers/wordless_preferences.php config file.

RVM (recommended setup)

It's recommended to use RVM to handle ruby gems. Type the following from your terminal:

rvm use 1.8.7
rvm gemset create wordless
rvm use 1.8.7@wordless
gem install sprockets compass coffee-script
rvm wrapper 1.8.7@wordless wordless compass ruby

Now you should be able to know the location of your RVM-wrapped ruby executables using which wordless_ruby and which wordless_compass. Write them down into the config/initializers/wordpress_preferences.php file.

Wordless Theme anatomy

That's a typical Wordless theme directory structure:

your_theme_dir
├── config
│   ├── initializers
│   └── locales
├── public
│   ├── assets
│   │   ├── javascripts
│   │   └── stylesheets
│   └── images
├── 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)

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. 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 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
    = include_stylesheet("application")
    / HTML5 Shiv
    /[if lt IE 9]
      = include_javascript("http://html5shiv.googlecode.com/svn/trunk/html5.js")

  %body.home-layout
    = render_partial("common/header")
    = yield()
    = render_partial("common/footer")
    = include_javascript("jquery")
	= include_javascript("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+ 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;
• get_the_time_ago() - 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 Haml views using include_stylesheet() helper.

= include_stylesheet("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 Haml views using include_javascript() helper.

= include_javascript("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 backing 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)

Copyright © 2011 weLaika

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.