zen 0.3 → 0.4

data/guide/javascript/zen_editor.md

@@ -0,0 +1,83 @@
+# Zen.Editor
+
+Zen.Editor is the main class used for the markup editor that can be used to more
+easily insert markup for all supported languages into a text area. By default
+Zen will automatically use the markup editor for all ``textarea`` elements with
+a class of ``visual_editor``. The format used for the markup is retrieved from
+the column ``data-format`` (this column is required). The attribute
+``data-format`` should contain the name of the markup engine to use as defined
+in ``Zen.Editor.drivers``. Currently the following are supported:
+
+* markdown
+* textile
+
+If an unknown driver is specified the default driver (HTML) will be used
+instead.
+
+The markup required for Zen to automatically use the markup editor looks like
+the example below.
+
+    <textarea class="visual_editor" data-format="markdown"></textarea>
+
+If you want to manually create an instance of ``Zen.Editor`` you can still do so
+but due to the way the system works you shouldn't directly create an instance of
+the class as this will prevent the editor from automatically using the correct
+driver class. You should use ``Zen.Editor.init`` instead. This method has the
+following syntax:
+
+    var editor = Zen.Editor.init(driver, element[, options, buttons]);
+
+The first parameter is a string containing the name of the driver to use. The
+second parameter can either be a CSS selector, a collection of elements or a
+single element. If the parameter is a CSS selector or a collection of elements
+the **first** element will be used, all others will be ignored. The last two
+parameters are used for customized options as well as adding custom buttons to
+the editor. Currently the editor only supports the following two options:
+
+* width: sets a minimum width on the textarea element.
+* height: sets a minimum hight on the textarea element.
+
+Buttons can be added by setting the last parameter to an array. Each button has
+the same format as the buttons used in Zen.Window:
+
+    {
+      name:   'foobar',
+      label:  'Foobar',
+      onClick: function() {}
+    }
+
+Note that unlike Zen.Window these buttons can't be set in the options object
+under the key "buttons". This is because the Options class of Mootools doesn't
+actually merge options but instead overwrites existing ones. This would mean
+that it would be more difficult to add a default set of buttons as well as
+custom ones. Most likely this will change in the future once I find out what the
+best way of doing this would be.
+
+Example:
+
+    var editor = Zen.Editor.init(
+        'markdown',
+        'div#text_editor',
+        {
+            width: 400
+        },
+        [
+            {
+                name:    'custom',
+                label:   'Custom',
+                onClick: function(editor)
+                {
+                    console.log("This is a custom button!");
+                }
+            }
+        ]
+    );
+
+Functions used for buttons take a single parameter which will contain an
+instance of the editor the button belongs to. This makes it easy to insert text
+into the textarea:
+
+    function(editor)
+    {
+        editor.insertAroundCursor({before: '<!--', after: '-->'});
+    }

data/guide/javascript/zen_hash.md

@@ -0,0 +1,34 @@
+# Zen.Hash
+
+Zen.Hash is a class that can be used to parse and generate shebang/hash bang
+URLs. Parsing is done using ``Zen.Hash#parse`` and generating URLs using
+``Zen.Hash#getHash``.
+
+Parsing a URL is relatively simple and the end output is similar to how you'd
+parse URLs with query string parameters. First create a new instance of this
+class:
+
+    var hash = new Zen.Hash('#!/users/active?limit=10');
+
+The supplied string will be parsed straight away and the result can be
+retrieved from two attributes:
+
+* segments
+* params
+
+The first attribute contains an array with all the URL segments, the second
+one is an object containing all the query string parameters. In case of the
+above example that would lead to the following data being stored in these
+attributes:
+
+    console.log(hash.segments); // => ["users", "active"]
+    console.log(hash.params);   // => {limit: '10'}
+
+Keep in mind that calling ``Zen.Hash#parse`` will overwrite existing segments
+and parameters.
+
+Generating a full shebang URL is pretty straight forward as well and can be done
+by calling ``getHash()``. This method returns a string containing the shebang
+URL including the prefix:
+
+    hash.getHash(); // => "#!/users/active?limit=10"

data/guide/javascript/zen_htmltable.md

@@ -0,0 +1,78 @@
+# Zen.HtmlTable
+
+The class Zen.HtmlTable was introduced in Zen 0.2.8 and makes it possible to
+sort tables by their columns, check all checkboxes in the first column of a
+table and it highlights odd rows. Generally you don't need to use this class
+itself but instead you'll be using the markup it accepts in order to modify it's
+behavior.
+
+The basic markup for this class is very simple, in fact, it's nothing more than
+a regular table with a ``<thead>`` element:
+
+    <table>
+        <thead>
+            <tr>
+                <th>#</th>
+                <th>Name</th>
+            </tr>
+        </thead>
+        <tbody>
+            <tr>
+                <td>2</td>
+                <td>Ruby</td>
+            </tr>
+        </tbody>
+    </table>
+
+Zen will automatically detect and use the table and you're good to go. If you
+want to modify the behavior you can use a few attributes on certain elements of
+the table. The following attributes can be applied to the ``<table>`` element
+itself:
+
+* data-sort-index: the index of the ``<th>`` element to sort the table on by
+  default. By default this is set to 1 as all tables have a checkbox in the
+  first column of each row.
+
+The following attributes can be set on each ``<th>`` element:
+
+* data-sort-parser: the name of the parser to use for sorting the columns. This
+  option is directly passed to HtmlTable.Sort and can be any of the parsers
+  Mootools has to offer (or one you wrote yourself).
+
+Example:
+
+    <table data-sort-index="1">
+        <thead>
+            <tr>
+                <th>#</th>
+                <th data-sort-parser="usernames">Name</th>
+            </tr>
+        </thead>
+        <tbody>
+            <tr>
+                <td>2</td>
+                <td>Ruby</td>
+            </tr>
+        </tbody>
+    </table>
+
+If you want to create a table that should be ignored by Zen.HtmlTable simply
+give the ``<table>`` element a class of ``no_sort``:
+
+    <table class="no_sort">
+        <thead>
+            <tr>
+                <th>#</th>
+                <th>Name</th>
+            </tr>
+        </thead>
+        <tbody>
+            <tr>
+                <td>2</td>
+                <td>Ruby</td>
+            </tr>
+        </tbody>
+    </table>
+
+This class can also be applied to ``<th>`` elements to ignore just that column
+rather than the entire table.

data/guide/javascript/zen_tabs.md

@@ -0,0 +1,44 @@
+# Zen.Tabs
+
+Zen.Tabs can be used to create a tab based navigation menu. Because Zen already
+uses this class for all elements that match the selector ``div.tabs ul`` it's
+usually not required to manually create an instance of this class.
+
+The syntax of creating an instance of this class looks like the following:
+
+    var tabs = new Zen.Tabs(selector[, options]);
+
+The first parameter is a CSS selector, the second parameter is an object
+containing various options to customize the instance. Note that the selector
+used should result in a number of ``ul`` elements, not ``div`` elements (or any
+other elements).
+
+A short example looks like the following:
+
+    var tabs = new Zen.Tabs('div.my_tabs ul');
+
+The following options can be used to customize the tabs:
+
+* default: a selector used to indicate what tab element should be selected by
+  default. Set to ``li:first-child`` by default.
+
+For the tabs system to work properly you'll need to use the right markup for
+your fields. Luckily this is as simple as creating a ``<div>`` (or another type
+of element) and setting an ID for that element:
+
+    <!-- The markup for your tabs -->
+    <div class="tabs">
+        <ul>
+            <li>
+                <a href="#some_id">Some ID</a>
+            </li>
+        </ul>
+    </div>
+
+    <!-- The field to show/hide -->
+    <div id="some_id">
+
+    </div>
+
+Keep in mind that for the tab system to work properly the URLs for each tab
+should start with a hash sign.

data/guide/javascript/zen_window.md

@@ -0,0 +1,49 @@
+# Zen.Window
+
+The Window class can be used to display modal windows with (or without) a set of
+custom buttons. These windows can be used for displaying pictures, confirmation
+messages and so on. In order to display a window you'll need to create a new
+instance of the class. The syntax of this looks like the following:
+
+    var some_window = new Zen.Window(content[, options]);
+
+<div class="note deprecated">
+    <p>
+        <strong>Warning</strong>: When creating an instance of Zen.Window you
+        should never save it in a variable named "window" as this is a reserved
+        variable that refers to the browser window.
+    </p>
+</div>
+
+The first parameter is the content to display and can either be plain text or
+HTML. The second parameter is an object containing various options that can be
+used to customize the window. The following options can be set in this object:
+
+* height: a number indicating a fixed height to use for the window.
+* width: the same but for the width.
+* title: the title to display in the title bar containing the close button.
+* resize: boolean that when set to true allows the user to resize the window.
+* move: boolean that when set to true allows the user to move the window around.
+* buttons: an array of buttons to display at the bottom of the window.
+
+Creating a new window with some of these options would look something like the
+following:
+
+    var some_window = new Zen.Window('Hello, world!', {title: 'This is a window!'});
+
+Note that you're not required to call any extra methods, the window will be
+displayed whenever a new instance of the window is created.
+
+Buttons can be added by setting the "buttons" option to an array of objects of
+which each object has the following format:
+
+    {
+      name:   'foobar',
+      label:  'Foobar',
+      onClick: function() {}
+    }
+
+* name: the name of the button, should be unique as it's used for the class of
+  the ``li`` element of the button.
+* label: the text displayed in the button.
+* onClick: a function that will be called whenever the button is clicked.

data/guide/zen_compared.md

@@ -0,0 +1,201 @@
+# Comparing Zen With Others
+
+A common question people ask when looking into specific software is "How is this
+different/better compared to X?". One might wonder what the differences are
+between Zen and Wordpress or Zen and Radiant. This guide is meant to clear
+things up a bit.
+
+Do note that since I wrote Zen my opinion is more than likely biased.
+
+## Zen vs Wordpress
+
+There are quite a few differences between Zen and Wordpress besides the language
+that's being used for the two (PHP for Wordpress, Ruby for Zen). Wordpress at
+its core is a blogging engine that was meant to handle blog articles and simple
+static pages. Over the years people started writing plugins and it expanded from
+a blogging engine into a more general purpose content management system.
+However, at its core it still remains a blogging engine and this is something
+you'll quickly notice when trying to use it for something other than a blog or a
+very basic website.
+
+Another issue with Wordpress is that it has a (in my opinion) horrible code base
+as well as a badly designed plugin system that promote bad coding standards and
+the mixing of logic and presentation. Wordpress doesn't take full advantage of
+the good parts of PHP such as classes and namespaces and instead mostly relies
+on the use of global functions.
+
+A good example of this is the file ``wp-admin/media.php``. This file contains a
+mixture of HTML for the presentation as well as plain PHP for the logic. There's
+logic for enqueing certain actions, displaying error messages as well as
+presentation code for various media files. Instead of separating this into
+controllers, models and views the developers decided to just chuck it all in a
+single file.
+
+Sure, Wordpress is pretty easy to use and has a decent looking interface but
+once you have to dive into the code base you'll most likely wish you never
+touched it alltogether.
+
+Zen doesn't aim to be a blogging engine or another specific type of content
+management application, not does it aim to be N times faster (I've simply never
+compared it with Wordpress in terms of performance). Instead Zen tries to be
+more right by giving you greater flexibility (without the need for installing
+third party plugins/hacks) as well as a solid code base that is far more
+pleasant to work with.
+
+### Installation
+
+Unlike Zen Wordpress isn't distributed using a package manager, instead you have
+to manually download, extract and install a compressed archive. In its most
+basic form you'd have to run the following commands to get a copy of Wordpress:
+
+    $ wget http://wordpress.org/latest.tar.gz
+    $ tar -xvf latest.tar.gz
+    $ cd wordpress/
+
+This process is not only tiring but also makes it harder to upgrade existing
+installations.
+
+Zen is distributed using Rubygems and thus all you need to run in order to
+install it is the following command:
+
+    $ gem install zen
+
+If you want to update Zen you simply run ``gem update zen`` instead.
+
+## Zen vs Expression Engine
+
+Zen was heavily inspired by Expression Engine and was initially written to be
+"Expression Engine done right". The two have a lot of things in common such as
+the ability to create custom fields and sections (called "channels" in EE). Zen
+however takes it a step further and allows you to create custom field methods
+and types (on top of just fields) as well as having a simpler database design
+and a code base that's far more pleasant to work with.
+
+Another big difference between the two is that Expression Engine costs money and
+is not open source, Zen on the other hand is completely free and licensed under
+the MIT license. This license gives you the freedom to use Zen for any project
+(both open source and proprietary) without the drawbacks of licenses such as the
+GPL.
+
+### Installation
+
+Similar to Wordpress you'll have to download a copy of Expression Engine
+yourself. However, EE comes with the requirement of having a user account as
+well as a credit card since Expression Engine is not free nor open source.
+Installing EE comes down to the following:
+
+1. Register for an account
+2. Buy a license using a credit card
+3. Download a .zip archive (I'm not sure if they offer Tarballs)
+3. Extract the archive
+
+Again just like Wordpress this has to be done for every installation (except for
+the registration part) though this depends on the license you've chosen.
+
+## Zen vs Radiant
+
+While I have to admit that I'm not very familiar with Radiant it appears that
+Radiant comes with a rather limited set of features out of the box and tries to
+label everything as a page giving you some extra flexibility using so called
+"snippets" and "layouts". I can imagine this being easier to use for some but it
+also greatly limits the flexibility meaning that developers will often have to
+resort to installing or developing (third party) extensions.
+
+Another difference between the two is that Zen uses "Etanni" as a template
+engine whereas Radiant uses "Radius". Radius is a template engine that uses HTML
+like tags for its logic whereas Etanni uses plain Ruby. Both have their
+advantages as well as their drawbacks.
+
+Plain Ruby code is more flexible but it isn't something you want your users to
+be able to execute (don't worry, Zen escapes the template tags for you).
+
+Radius on the other hand is something you can use in your content as it can
+only execute what you've explicitly defined. The downside of this is that
+you'll often end up re-inventing things that can be easily done in plain Ruby.
+
+One thing to keep in mind is that Zen doesn't limit you in terms of what engines
+you can use, you can easily use other engines such as Radius or Liquid in
+combination with Etanni.
+
+### Installation
+
+Just like Zen Radiant can be installed using Rubygems by running the following
+comamnd:
+
+    $ gem install radiant
+
+Other than using a different gem name there are no differences between Zen and
+Radiant when it comes down to installing the two.
+
+## Zen vs Refinery CMS
+
+I have to admit that I have very little experience with Refinery CMS. What I
+noticed from using the demo was that the interface it uses looks rather boring
+and doesn't feel very pleasant to use. The settings overview is rather confusing
+and managing settings happens in modal windows while managing other rows, such
+as users, happens on an entirely new page.
+
+Another thing I noticed is that Refinery CMS, just like Wordpress and Expression
+Engine, assumes you'll only use two markup formats: plain text and HTML. A big
+problem with common WYSIWYG editors such as CKEditor and TinyMCE is that the
+markup they generate is either plain incorrect or otherwise disgusting. CKEditor
+for example has a tendency to insert empty ``<p>`` or ``<div>`` elements in
+your content for no apparent reason.
+
+Out of the box Zen offers support for plain text, HTML, Markdown and Textile
+with the ability to easily add your own markup formats. The text editor was
+written with this in mind and produces very clean markup, the drawback being
+that it does not (and most likely never will) support WYSIWYG features. The
+closest thing to this feature is the "Preview" button which opens a modal window
+with the HTML that was generated based on the used markup.
+
+Probably the biggest difference of all is that Refinery CMS does not appear to
+have a very flexible content model (out of the box at least). There are a few
+content types such as "Pages", "Images" and "Inquiries" but it's not very clear
+how flexible (or not) these content types are.
+
+### Installation
+
+Similar to Zen and Radiant Refinery CMS is also installed using Rubygems, this
+can be done by running the following command:
+
+    $ gem install refinerycms
+
+Besides the Gem name there are no other differences in the installation process
+that I know of.
+
+## Zen vs Locomotive CMS
+
+Locomotive CMS is a rather new application that was released somewhere in the
+end of 2011. It has a similar system like Zen allowing you to create custom
+fields however based on the little experience that I have with Locomotive I'd
+say it's far more limited. I couldn't figure out if there was the ability to add
+your own field types or group them together. Locomotive also doesn't offer a
+flexible way of defining rules for custom fields other than allowing users to
+specify that a certain field is required.
+
+The interface used by Locomotive was rather annoying to use and doesn't appear
+to be very useful when presenting large amounts of content due to the fixed
+width of the design. To be honest I'm quite amazed by this since the designer,
+Sacha Grief, seems to be more than capable of designing good looking and useful
+interfaces.
+
+Unlike Zen Locomotive doesn't use a relational database but instead uses
+MongoDB. Some might argue that this is better (or worse) but I'm personally not
+too sure about it. I've heard great things about MongoDB but I've also heard and
+read very bad things about it. When I tried it myself I wasn't too impressed
+with it, it gives me the idea somebody wanted to write a relational database
+engine that wasn't a relational database engine.
+
+### Installation
+
+The installation process of Locomotive looks rather, well, stupid. Instead of
+allowing you to install it using Rubygems and be done with it you have to go
+through multiple steps, starting with setting up a bare Rails installation,
+adding Locomotive to your Gemfile and so on. In total there's about 6 steps
+needed to install it. See
+<http://www.locomotivecms.com/support/installation/engine> for more information.
+
+Compared with Zen, which only requires you to run ``gem install zen``, I wonder
+why they ever thought it was a good idea to require so many steps when it can be
+done so much easier.