updated readme

README.md

@@ -11,7 +11,7 @@ nodejs
 phantomjs
 ```
 
-- Clone the repo in wp-content/plugins.
+- Clone the repo in `wp-content/plugins`.
 
 - Install composer.
 ```sh
@@ -69,6 +69,14 @@ Kickstart file.
 
 # Tests.
 
+- Before running tests, make sure you specify the following values in the .env file:
+```sh
+WP_TEST_URL="http://wordpress.dev"
+WP_TEST_USER="admin"
+WP_TEST_PASSWORD="password"
+WP_TEST_PATH="/absolute/path/to/wordpress"
+```
+
 - Unit tests (using [verify](https://github.com/Codeception/Verify)):
 ```sh
 $ ./do test:unit
@@ -76,7 +84,6 @@ $ ./do test:unit
 
 - Acceptance tests:
 ```sh
-# Setup .env
 $ ./do test:acceptance
 ```
 
@@ -85,12 +92,37 @@ $ ./do test:acceptance
 $ ./do test:all
 ```
 
-# Watch assets.
+# Assets.
+## CSS
+We are using [Stylus](https://learnboost.github.io/stylus/) (with the [Nib extension](http://tj.github.io/nib/)) as our CSS preprocessor.
+### Structure
+```sh
+assets/css/lib -> link your dependencies here
+assets/css/src -> place your *.styl files here
+```
+
+### Watch for changes and recompile
+The following command will compile all specified *.styl files (in `Robofile.php`->`watch()`) into `assets/css`
 ```sh
 $ ./do watch
 ```
 
-# JS Dependencies.
+### Add files to the watch command
+```php
+# Robofile.php
+<?php
+  function watch() {
+    $files = array(
+      # global admin styles
+      'assets/css/src/admin.styl',
+      # rtl specific styles
+      'assets/css/src/rtl.styl',
+      # <-- add custom file (*.styl)
+    );
+    ...
+?>
+```
+## JS
 In order to use a JS library (let's take Handlebars as an example), you need to follow these steps:
 
 * add "handlebars" as a dependency in the `package.json` file
@@ -111,19 +143,130 @@ $ ln -nsf ../../../node_modules/handlebars/dist/handlebars.min.js handlebars.min
 ```
 * make sure to push the symlink onto the repository
 
-# Translations.
+# Views
-When editing a Twig template (`views/*.html`), you have to the following WordPress functions:
+## Twig (`views/*.html`)
+### Layout
+```html
+<!-- system notices -->
+<!-- main container -->
+<div class="wrap">
+  <!-- notices -->
+  <!-- title block -->
+  <% block title %><% endblock %>
+  <!-- content block -->
+  <% block content %><% endblock %>
+</div>
 
-* `__`: returns a string
+<!-- stylesheets -->
-* `_n`: returns a pluralized string
+<%= stylesheet(
+  'admin.css'
+)%>
+
+<!-- rtl specific stylesheet -->
+<% if is_rtl %>
+  <%= stylesheet('rtl.css') %>
+<% endif %>
+
+<!-- javascripts -->
+<%= javascript(
+  'ajax.js',
+  'notice.js',
+  'modal.js',
+  'lib/handlebars.min.js',
+  'handlebars_helpers.js'
+)%>
+
+<!-- handlebars templates -->
+<% block templates %><% endblock %>
+```
+### Page
+```html
+<% extends 'layout.html' %>
+
+<% block title %>
+  <h2 class="title"><%= form.form_name %></h2>
+<% endblock %>
+
+<% block content %>
+  <p><%= __('Hello World!') %></p>
+<% endblock %>
+```
+
+## Handlebars (`views/*.hbs`)
+
+In order to include Handlebars templates (`views/*.hbs`) in your view (`views/*.html`).
+
+You can either use the `partial(id, file, alias = null)` function or create your own custom template.
+
+Templates included using `partial(id,...)` can be accessed via `jQuery('#'+id).html()`.
+
+If you specify an `alias`, you will be able to reference it using `{{> alias }}` in any Handlebars template.
 
 ```html
-<p>{{ __('Click %shere%s!') | format('<a href="#">', '</a>') | raw }}</p>
+<!-- use the `templates` block -->
+<% block templates %>
+  <!-- include a .hbs template -->
+  <%= partial('my_template_1', 'form/templates/toolbar/fields.hbs') %>
+  
+  <!-- include a .hbs template and register it as a partial -->
+  <%= partial('my_template_2', 'form/templates/blocks.hbs', '_my_partial') %>
+  
+  <!-- custom partial using partial defined above -->
+  <script id="my_template_3" type="text/x-handlebars-template">
+    {{> _my_partial }}
+  </script>
+<% endblock %>
 ```
-This will print: "Click [here](#)"
+
+# Internationalization (i18n)
+## i18n in PHP
+* use the regular WordPress functions (`__()`, `_e()`, `_n()`,...).
+```php
+<?php
+  echo __('my translatable string');
+  // or
+  _e('my translatable string');
+  
+  // pluralize
+  printf(
+    _n('We deleted %d spam message.',
+       'We deleted %d spam messages.',
+       $count,
+       'my-text-domain'
+    ),
+    $count
+  );
+?>
+```
+Reference: [i18n for WordPress Developers](https://codex.wordpress.org/I18n_for_WordPress_Developers)
+
+## i18n in Twig
+* `__(string)`: returns a string
 
 ```html
-<p>{{ _n('deleted one message', 'deleted %d messages', count, 'wysija-newsletters') | format(count) }}</p>
+<p>
+  <%= __('Click %shere%s!') | format('<a href="#">', '</a>') | raw %>
+</p>
 ```
-This will print "deleted one message" (if count === 1)
+**/!\\** Notice that we use the `raw` filter so that the HTML remains unfiltered.
-This will print "deleted X message" (if count !== 1)
+
+Here's the output:
+```html
+<p>
+  Click <a href="#">here</a>
+</p>
+```
+
+* `_n('singular', 'plural', value)`: returns a pluralized string
+```html
+<p>
+  <%= _n('deleted %d message', 'deleted %d messages', count) | format(count) %>
+  <!-- count === 1 -> "deleted 1 message" -->
+  <!-- count > 1 -> "deleted $count messages" -->
+</p>
+```
+
+## i18n in Handlebars
+In order to use i18n functions, your Handlebars template needs to be loaded from Twig (`views/*.html`).
+
+Then you can use the Twig functions in your template.

RoboFile.php

@@ -14,14 +14,18 @@ class RoboFile extends \Robo\Tasks {
   }
 
   function watch() {
+    $files = array(
+      // global admin styles
+      'assets/css/src/admin.styl',
+      // rtl specific styles
+      'assets/css/src/rtl.styl'
+    );
+
     $command = array(
       './node_modules/stylus/bin/stylus -u',
       ' nib -w'.
-      // global admin styles
+      join(' ', $files).
-      ' assets/css/src/admin.styl'.
+      ' -o assets/css/'
-      // rtl specific styles
-      ' assets/css/src/rtl.styl',
-      '-o assets/css/'
     );
     $this->_exec(join(' ', $command));
   }

views/form/editor.html

@@ -588,7 +588,6 @@
   <script id="form_template_field_input" type="text/x-handlebars-template">
     {{> _settings_required }}
     {{> _settings_validate }}
-    heyh
   </script>
 
   <script id="form_template_field_textarea" type="text/x-handlebars-template">