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;
- Your development machine needs a ruby environment, and the compass, sprockets and coffee-script gem. The
coffee-scriptgem requires a valid javascript runtime available on your machine, see the ExecJS readme to learn the supported ones; - 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;
- Enable Apache
mod_rewritemodule (a2enmod rewrite) and make sure WordPress nice permalinks are enabled under the WP "Settings > Permalinks" section; - Download the Wordless plugin, drop it in the
wp-content/pluginsdirectory 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;
- Specify the path of the
compassandrubyexecutables within theconfig/initializers/wordless_preferences.phpconfig file.
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.
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:
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.
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/layoutsdirectory; - We're already using two of the 40+ Wordless helper functions,
link_to()andget_the_filtered_content(), to DRY up this view.
Don't you already feel so much better?
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 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()andnew_taxonomy()- Help you create custom posts and taxonomy;get_the_time_ago()- Reports the approximate distance in time between two dates;
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.
Just drop all your theme locale files in this directory. Wordless will take care of calling load_theme_textdomain() for you.
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/*.
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.
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.
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;
- 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 :)
(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.