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;
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.
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):
\curl -L https://get.rvm.io | bash -s stable
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 2.0
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 2.0@wordless --create --default && gem install therubyracer sprockets compass coffee-script thor yui-compressor && rvm wrapper 2.0@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.
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, choosemonth and name
); - Download the Wordless plugin, drop it in the
wp-content/plugins
directory (be sure its directory is named 'wordless') 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
andruby
executables within the WP "Appearance > Wordless preferences".
That's a typical Wordless theme directory structure:
your_theme_dir
├── index.php
├── assets
│ ├── fonts
│ ├── images
│ ├── javascripts
│ └── stylesheets
├── config
│ ├── initializers
│ └── locales
├── theme
│ ├── assets
│ │ ├── javascripts
│ │ └── stylesheets
│ ├── helpers
│ │ └── README.mdown
│ └── views
│ ├── layouts
│ └── posts
└── tmp
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 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()
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
= stylesheet_link_tag("application")
/ HTML5 Shiv
/[if lt IE 9]
= javascript_include_tag("https://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 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()
andnew_taxonomy()
- Help you create custom posts and taxonomy;distance_of_time_in_words()
- 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 your code into many modular initializer files, each one with a specific target:
config/initializers
├── backend.php
├── custom_post_types.php
├── default_hooks.php
├── hooks.php
├── login_template.php
├── menus.php
├── shortcodes.php
├── thumbnail_sizes.php
└── wordless_preferences.php
- backend: remove backend componentes such as widgets, update messages, ecc
- custom_post_types: well...if you need to manage taxonomies, this is the place to be
- default_hooks: this are used by default wordless' behaviours; tweak them only if you know what are you doing
- hooks: this is intended to be your custom hooks collector
- menus: register new WP nav_menus from here
- shotcodes: as it says
- thumbnail_sizes: if you need custom thumbnailing sizes
- wordless_preferences: no more to be edited. Go to the Wordless menu in the WP backend
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. Note that due to WordPress localization framework, you need to append our domain when using internationalization. For example, using __()
without the domain specified will not work:
__("News")
But using the domain we will make it work:
__("News", "we")
Wordlress has to different places where you want to put your assets:
- Place all your custom, project related assets into the
theme/assets/*
. - Place all the static images and vendor assets (i.e. vendor JS plugins) into the
assets/*
directory;
The fast way:
- jquery is included by default for you
- write your style in sass inside
theme/assets/stylesheets/screen.sass
- write your js in
theme/assets/javascripts/application.js.coffee
and all will automagically works! :) The long way follows
The Wordless approach is to use screen.sass, present by default, as the aggregator of smaller sass partials. By default you have:
theme/assets/stylesheets/
├── screen.sass
├── _post.sass
├── _site_header.sass
└── _tinymce.sass
where screen contains:
.page-wrapper
[...]
@import "site_header"
section.site-content
[...]
@import "tinymce"
@import "post"
Every @import
will insert in that exact line the content of the called partial, where partials are named _post.sass
and just called as post
.
This will result in a single compiled screen.css
. This file, starting from tag 0.3, will be served using WordPress internal enqueueing function wp_enqueue_style
.
At your will, you can add e.g. mobile.css
or print.css
support, going in config/initializers/default_hooks.php
and extending the default function such as
function enqueue_stylesheets() {
wp_register_style("screen", stylesheet_url("screen"), false, false);
wp_enqueue_style("screen");
wp_register_style("print", stylesheet_url("print"), false, false);
wp_enqueue_style("print");
}
then write your code into theme/assets/stylesheets/print.sass
Say that you have a jQuery plugin shipped with custom css, ok? Take the vendorcss.css and drop it inside assets/stylesheets
folder; then include the assets in your views using stylesheet_link_tag()
helper.
= stylesheet_link_tag("vendorcss")
Usually you want css to load in the _head.html.haml
partial, but you can get it inside any view or partial. This will produce the following HTML, pointing to the assets/stylesheets
directory:
<link href="/wp-content/themes/YOUR_THEME/assets/stylesheets/vendorcss.css" media="all" rel="stylesheet" type="text/css" />
If Wordless can't find the static files in assets/stylesheets/*.css
, it will search for *.sass or *.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.
Before going production (or staging), you have to compile your assets in order to statically serving them. You will be definitely intrested in wordless-gem and simplify the task (and probably deploy commands too?! ;) ) to a one-shot command!
The Wordless approach is to use `theme/assets/javascripts/application.js.coffee, present by default.
This file, starting from tag 0.3, will be served using WordPress internal enqueueing function wp_enqueue_style
.
At your will, you can add support to other files, going in config/initializers/default_hooks.php
and extending the default function such as
function enqueue_javascripts() {
wp_register_script("jquery", 'https://ajax.googleapis.com/ajax/libs/jquery/1.7.0/jquery.min.js', '', false, true);
wp_enqueue_script("jquery");
wp_register_script("application", javascript_url("application"), '', false, true);
wp_enqueue_script("application");
wp_register_script("myjs", javascript_url("myjs"), '', false, true);
wp_enqueue_script("myjs");
}
then write you code into theme/assets/javascripts/myjs.coffee
Say that you have a jQuery plugin to load, ok? Take the vendorjs.js and drop it inside assets/javascripts
folder; then include the assets in your views using javascript_include_tag()
helper.
= javascript_include_tag("vendorjs")
You can get it inside any view or partial. This will produce the following HTML, pointing to the assets/javascripts
directory:
<script src="/wp-content/themes/YOUR_THEME/assets/javascripts/vendorjs.js" type="text/javascript"></script>
If Wordless can't find the static files in assets/javascripts/*.js
, it will search for *.coffee inside the theme/assets/javascripts
directory, and will automatically compile and serve it on the fly using Sprockets preprocessor 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.
Before going production (or staging), you have to compile your assets in order to statically serving them. You will be definitely intrested in wordless-gem and simplify the task (and probably deploy commands too?! ;) ) to a one-shot command!
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.
- We are developing Wordless-extender. A little plugin, that brings our collection of favorite plugins and let you set up some constants in wp-config.php useful in hardening the WP installation. At the moment is not yet well documented and absent from wordpress.org repository, but we are moving fast, so keep follow!
- 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-gem: the CLI sheriff for your Wordless theme! Compile and clean assets, create new WP installation, a new wordless theme and let you set up a deploy command in order to easily deploy your site, collaborating with Wordmove, with a
wordless deploy -r
- 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 routing part can be drammaticaly improved to make it more readable and DRY;
- This is go-ahead software, everything is subject to change :) but you can pull code from tagged commits (stable)
You can find it here. If you are intrested in contribuing to the documentation:
- we are documenting the following at the moment (path recursive)
wordless/helpers/*
wordless/helpers/placeholder_images/*
wordless/helpers/templates/*
vendor/mobile_detect.php
- here is a list of documentation holes :9
- go and add doc following the doxygen guides
- pull-request your commits
- we'll recompile the doxygen doc
- the community will be grateful!
(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.