zen 0.2.8 → 0.3b

data/{CHANGELOG.md → guide/changelog.md}

@@ -1,3 +1,45 @@
+# Changelog
+
+## Git Head
+
+* Started using checkboxes in favor of select boxes as they're easier to use.
+* Fixed a small issue that would make it impossible to add/update categories of
+  a section entry.
+* Core packages no longer include certain modules just to so that they don't
+  have to specify the full namespace to a class.
+* Added an event system (Zen::Event) and a bucket load of events.
+* Merged Zen.init and Zen.post_init into Zen.start.
+* Fixed various YARD formatting issues.
+* Localized all of the Javascript.
+* All specs now pass on Ruby 1.9.3.
+* Made it easier to format dates and do other locale based actions using
+  Ramaze::Helper::Locale.
+* Dropped Zen::Asset in favor of Ramaze::Asset.
+* Updated Mootools Core and Mootools More to version 1.4.
+* Fixed an issue related to creating users without passwords.
+* New API for Zen::Package.
+* ACL system has been re-written from scratch.
+* Merged Zen::Theme::Base with Zen::Theme and Zen::Plugin::Base with
+  Zen::Plugin.
+* Sections are no longer directly related to template groups.
+* Added a package that displays the installed languages, packages and themes.
+* New API for Zen::Language.
+* Removed Zen::Plugin.
+* Improved settings API.
+* Visitors can now register an account (or not) based on a setting.
+* Vendorized Ramaze::Helper::StackedAspect from Ramaze Git.
+* Added a helper for allowing users to access admin URLs.
+* User statuses are now stored as IDs instead of plain text.
+* Full support for PostgreSQL.
+* Zen now requires Ramaze >= 2011.10.23.
+* Content in the admin panel can now be searched using regular expressions (not
+  supported in SQLite3) or LIKE statements (used in case of SQLite3).
+* New documentation based on YARD instead of Sphinx.
+* Vendorized the Sequel sluggable plugin.
+* Fixed an issue that would cause comments to be displayed regardless of their
+  status.
+* Lots of small fixes, improvements, etc.
+
 ## 0.2.8 - August 3, 2011
 
 * Replaced RSpec with Bacon.

data/guide/css/common.css

@@ -0,0 +1,20 @@
+body
+{
+    font-size:   14px;
+    line-height: 1.6;
+    margin:      0 auto;
+    max-width:   960px;
+}
+
+p code
+{
+    background:    #f2f2f2;
+    padding-left:  3px;
+    padding-right: 3px;
+}
+
+pre.code
+{
+    font-size:   13px;
+    line-height: 1.4;
+}

data/guide/getting_started.md

@@ -0,0 +1,61 @@
+# Getting Started
+
+Once installed (see {file:installation Installation}) you can use the ``zen``
+executable to create new applications. Keep in mind that this command is not a
+wrapper for the ``ramaze`` executable. This means that you still have to type
+``ramaze console`` or ``ramaze start`` if you want to open up a console or start
+your application.
+
+In order to create a new application based on Zen you'll need to execute the
+following command:
+
+    $ zen create
+
+This command will start an interactive installer that walks you through the
+process of creating a new project. Using this installer you can specify the
+project name, database settings and various other settings.
+
+The prototype applications generated by the zen command are pretty basic but
+should be enough for most users. If you want to change anything of it you're
+free to do so just make sure that all paths and such are updated correctly.
+
+Once an application has been created and is configured you'll need to create the
+database and insert the default user. This can be done by executing the
+following commands:
+
+    $ rake db:migrate
+    $ rake db:user
+
+This creates all the database tables and inserts a default user with a random
+password.
+
+When creating the database tables for the first time you'll see one or two
+yellow warnings telling you certain tables might be missing. These can be safely
+ignored.
+
+You can now start the application using your server of choice and start using
+it.
+
+## Updating Applications
+
+Updating Zen in general is quite easy and requires the following two commands::
+
+    $ gem update zen
+    $ rake db:migrate
+
+However, with some releases there may be some extra steps that are required in
+order to properly update your installation so it's always wise to check the
+release notes before updating an installation.
+
+When updating the database schema I always try to write my migrations in such a
+way that existing data is migrated as well. However, because there may be some
+cases where this isn't possible it's recommended that you **always** make a
+backup of your database before updating.
+
+## Logging In
+
+In order to log in you must navigate to ``/admin/users/login`` or ``/admin``
+(the latter will redirect you to the first URL and show a warning). If you don't
+have any user accounts set up yet you should run the rake command ``rake
+db:user`` as explained above. If you do have an available user account you can
+log in using the user's Email address and password.

data/guide/hacking.md

@@ -0,0 +1,52 @@
+# Hacking & Contributing
+
+Everybody is free to contribute to Zen. However, to ensure that the quality of
+Zen doesn't degrade developers should stick with the guidelines described in
+this document. Zen also follows the [Ramaze guidelines][ramaze guidelines] as
+much as possible.
+
+## General Standards
+
+* 2 spaces per indentation level for Ruby code.
+* 4 spaces per indentation level for Javascript, CSS and HTML.
+* Document your code, that includes CSS (when dealing with complex selectors)
+  and Javascript files.
+* No tabs at all times.
+* Markdown is used for all markup.
+* The maximum width of each line should be no more than 80 characters, this
+  makes it easier to read code in terminals or when using split view modes.
+
+## Comitting
+
+Besides the guidelines set in [Ramaze's comit messages][commit guidelines]
+section Zen comes with the requirement that all commits are signed off using
+``git commit --sign``. For more information about signing commits (and why
+it is a good idea) see the following pages:
+
+* <http://kerneltrap.org/files/Jeremy/DCO.txt>
+* <http://stackoverflow.com/questions/1962094/what-is-the-sign-off-feature-in-git-for>
+
+## Branching
+
+Zen has two main branches, "master" and "develop". The master branch is directly
+tied to releases, this means that it should **always** contain stable and fully
+tested code. In almost all cases I (Yorick) will be the only one merging
+changes into this branch. The develop branch is used as a place to merge other
+branches into as well as for comitting small changes such as typos, small bug
+fixes and so on.
+
+Big features such as a new backend design should go in a separate branch with an
+easy to remember and meaningful name. In this example the branch name could be
+"new\_design" or simply "design".
+
+## Tests
+
+Tests for Zen are written using [Bacon][bacon]. New features, modified ones, it
+doesn't matter, they should all be tested. Currently Zen's code coverage
+(measured using SimpleCov) sits around 96% and I intent to keep it above 95%.
+The test ouput is displayed using [TAP][tap protocol].
+
+[ramaze guidelines]: http://ramaze.net/documentation/file.contributing.html
+[commit guidelines]: http://ramaze.net/documentation/file.contributing.html#Commit_Messages
+[bacon]: https://github.com/chneukirchen/bacon
+[tap protocol]: https://en.wikipedia.org/wiki/Test_Anything_Protocol

data/guide/installation.md

@@ -0,0 +1,44 @@
+# Installation
+
+Zen can be installed in two different ways, either by using Rubygems or Git. The
+former is the easiest of the two as it only requires a single command. The
+latter is more useful if you want to hack on Zen while using it.
+
+## Rubygems Installation
+
+Installing Zen using Rubygems can be done by running the following command in
+your terminal:
+
+    $ gem install zen
+
+If you want to install a specific version of Zen you can provide the ``-v``
+option:
+
+    $ gem install zen -v [VERSION]
+
+For example, if you want to install 0.2.8 you'd run the following command:
+
+    $ gem install zen -v 0.2.8
+
+## Git Installation
+
+When you want to submit a patch, hack the core or are just interested in
+browsing the code you'll want to install a copy of the Git repository. This can
+be done by a simply cloning the repository:
+
+    $ git clone git://github.com/zen-cms/Zen-Core.git zen_core
+
+This command saves a local copy of Zen in the directory ./zen_core. Now that you
+have a local copy there are two ways of using it:
+
+1. Manually build the Gem each time you've made a change.
+2. Directly load the Zen installation from your application.
+
+The latter is recommended as you don't have to build the Gem each time. In order
+to do this you simply need to replace all calls to require() that load data from
+the gem with a path to the local copy of Zen.
+
+For an overview of all available tasks that can be executed in your local copy
+of Zen execute the following command:
+
+    $ rake -T

data/guide/javascript.md

@@ -0,0 +1,352 @@
+# Javascript API
+
+Zen comes with a pretty good Javascript API that's based on the
+[Mootools][mootools]. This API allows you to display modal windows, markup
+editors and so on. On top of that you're free to use everything Mootools and
+it's community has to offer.
+
+<div class="note todo">
+    <p>
+        <strong>Note</strong>: Whenever you're creating Javascript files you
+        should use 4 spaces per indentation and refrain from using tabs. 4
+        spaces are used as 2 spaces are generally harder to read due to
+        Javascript using curly brackets.
+    </p>
+</div>
+
+## Creating Classes
+
+Mootools has a wonderful system that allows you to easily create classes. The
+one thing to remember when creating classes is that you should *always* declare
+them under a certain namespace. Not doing so might lead to collisions with
+classes created by other developers.
+
+Creating a class (including a namespace) works like the following:
+
+    // This would be your namespace
+    var Foobar = {};
+
+    Foobar.ClassName = new Class(
+    {
+        initialize: function()
+        {
+
+        }
+    });
+
+This allows you to access your class as following:
+
+    var instance = new Foobar.ClassName();
+
+The namespace you're using doesn't really matter as long as you **do not** use
+the "Zen" namespace, it's reserved for all the official classes that are
+included in Zen.
+
+It's also important to remember that there's no guarantee Javascript (and CSS)
+files are loaded in a particular order. Because of that you should always wrap
+your code (except for class declarations and such) in the following code:
+
+    window.addEvent('domready', function()
+    {
+        // Do something funky!
+    });
+
+This function will be executed once the DOM (and thus all the resources) are
+fully loaded.
+
+<div class="note deprecated">
+    <p>
+        <strong>Warning</strong>: Do not put class declarations inside this
+        block as it may lead to unexpected behavior.
+    </p>
+</div>
+
+## Available Classes
+
+Out of the box the following classes are available:
+
+* Zen.Window
+* Zen.Tabs
+* Zen.Editor
+* Zen.Editor.Markdown
+* Zen.Editor.Textile
+* Zen.HtmlTable
+
+The following third-party classes are also provided:
+
+* Picker
+* Picker.Date
+* Picker.Attach
+
+### 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.
+
+<div class="note todo">
+    <p>
+        <strong>Note</strong>: Currently the resize and move features are a bit
+        buggy, especially when they're both used. This will be fixed in one of
+        the next releases.
+    </p>
+</div>
+
+### 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.
+* ajax: when set to true the content to display for each tab will be retrieved
+  using an Ajax call rather than retrieving it from the current page.
+
+When you're *not* using an Ajax based tab system you'll have to make sure your
+markup is correct. The links of the tabs should point to an ID of an element
+with a class of "tab_content":
+
+    <div id="some_id" class="tab_content">
+
+    </div>
+
+In order to display this field the corresponding tab URL should be ``#some_id``.
+A full example of the required markup, including the markup for the tab menu,
+looks like the following:
+
+    <div class="tabs">
+        <ul>
+            <li>
+                <a href="#my_tab">This is my tab</a>
+            </li>
+        </ul>
+    </div>
+
+    <div id="my_tab" class="tab_content">
+
+    </div>
+
+### 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: '-->'});
+    }
+
+### 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.Html table 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.
+
+[mootools]: http://mootools.net/