zen 0.3 → 0.4

data/.gems

@@ -1,12 +1,13 @@
-# Production dependencies.
+# Production.
 ramaze
 sequel
 bcrypt-ruby
 loofah
 shebang
 ramaze-asset
+rake
 
-# Development dependencies, no need for specific versions.
+# Development.
 rdiscount
 bacon
 yard

data/.rvmrc

@@ -1,2 +1,2 @@
 #!/usr/bin/env bash
-rvm use --create 1.9.3@zen
+rvm use --install --create 1.9.3@zen

data/.travis.yml

@@ -16,7 +16,12 @@ env:
   - 'ADAPTER=sqlite'
   - 'ADAPTER=mysql2 DATABASE=zen_dev'
   - 'ADAPTER=postgres DATABASE=zen_dev USERNAME=postgres'
+  - 'LRU=1 ADAPTER=sqlite'
+  - 'LRU=1 ADAPTER=mysql2 DATABASE=zen_dev'
+  - 'LRU=1 ADAPTER=postgres DATABASE=zen_dev USERNAME=postgres'
 
 before_script:
   - "mysql -e 'CREATE DATABASE zen_dev;'"
   - "psql -c  'CREATE DATABASE zen_dev;' -U postgres"
+  - "export DISPLAY=:99.0"
+  - "sh -e /etc/init.d/xvfb start"

data/.yardopts

@@ -6,8 +6,9 @@
 -e ./lib/yard/tags.rb
 --private
 --protected
---asset ./guide/_static:_static
+--asset ./guide/images:images
 --asset ./guide/css/common.css:css/common.css
 -
 ./guide/*.md
+./guide/javascript/*.md
 LICENSE

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010 - 2011, Yorick Peterse
+Copyright (c) 2010 - 2012, Yorick Peterse
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -38,12 +38,25 @@ small portion of what it can do.
 * A well documented, tested and easy to understand API.
 * A database structure that doesn't make you cry.
 
-## Chapters
+## Requirements
+
+* Ruby (YARV) 1.9.2 or newer (Rubinius, jruby and others are not supported).
+* Ramaze 2011.10.23 or newer.
+* A SQL database supported by Sequel. Zen has been tested and confirmed to
+  work on MySQL, SQLite3 and PostgreSQL. You'll also need the required gems for
+  these DBMS' such as "mysql2" for MySQL and "pg" for PostgreSQL.
+* A Rack compatible server such as Thin or Unicorn.
+* A library to convert your markup of choice to HTML. Zen by default has support
+  for Textile using Redcloth and Markdown using RDiscount. RDiscount and
+  RedCloth are installed automatically when needed.
+
+## User Guide
 
 * {file:installation Installation}
 * {file:getting_started Getting Started}
-* {file:hacking Hacking/Contributing}
-* {file:changelog Changelog}
+* {file:zen_compared Comparing Zen with Others}
+* {file:faq Frequently Asked Questions}
+* {Dashboard::Controller::Dashboard Dashboard}
 * {Categories Categories}
   * {Categories::Controller::CategoryGroups Managing Category Groups}
   * {Categories::Controller::Categories Managing Categories}
@@ -72,47 +85,38 @@ small portion of what it can do.
 * {Users Users, User Groups and Permissions}
   * {Users::Controller::Users Managing Users}
   * {Users::Controller::UserGroups Managing User Groups}
+
+## Developers Guide
+
+* {file:hacking Hacking/Contributing}
+* {file:changelog Changelog}
 * {Zen::Package Packages}
 * {Zen::Theme Themes}
 * {Zen::Language Localization}
 * {Zen::Event Events}
 * {Zen::Validation Validating Objects}
+* {Zen::Security.sanitize Sanitizing User Input}
+* {file:autosaving_forms Automatically Saving Form Data}
+* {Ramaze::Helper::Locale Working With Dates}
 * {file:asset_management Asset Management}
+* {Zen::Markup Converting Markup}
 * {file:javascript Javascript API}
 
-## Requirements
-
-* Ruby >= 1.9.2 (Rubinius, jruby and others are not supported).
-* Ramaze 2011.10.23 or newer.
-* A SQL database supported by Sequel. Zen has been tested and confirmed to
-  work on MySQL, SQLite3 and PostgreSQL. You'll also need the required gems for
-  these DBMS' such as "mysql2" for MySQL and "pg" for PostgreSQL.
-* A Rack compatible server such as Thin or Unicorn.
-* A library to convert your markup of choice to HTML. Zen by default has support
-  for Textile using Redcloth and Markdown using RDiscount. RDiscount and
-  RedCloth are installed automatically when needed.
-
 ## Community
 
 * [Website][zen website]
 * [Mailing list][mailing list]
-
-Zen does not have it's own IRC channel at this time but you can usually find me
-in any of the following channels on Freenode:
-
-* \#forrst-chat
-* \#ramaze
-* \#ruby-lang
+* IRC channel: \#zen-cms on Freenode
 
 ## Websites Using Zen
 
 * http://yorickpeterse.com/
 * http://ramaze.net/
 * http://zen-cms.com/
+* http://aplusm.me/
 
 If you've built a website using Zen and you'd like to have it listed here sent
-an Email to me (yorickpeterse [at] gmail [dot] com) or send an Email to the
-mailing list.
+an Email to me (yorickpeterse@gmail.com) or send an Email to the mailing list.
 
 ## Special Thanks
 

data/Rakefile

@@ -4,6 +4,9 @@ Zen::Gemspec = Gem::Specification::load(
   File.expand_path('../zen.gemspec', __FILE__)
 )
 
-Dir.glob(File.expand_path('../lib/zen/task/*.rake', __FILE__)).each do |task|
-  import(task)
+task_path = File.expand_path('../lib/zen/task', __FILE__)
+tasks     = ['build', 'clean', 'proto', 'setup', 'test']
+
+tasks.each do |task|
+  import File.join(task_path, "#{task}.rake")
 end

data/guide/asset_management.md

@@ -17,7 +17,7 @@ The asset helper is loaded in the admin controller and therefor available to all
 controllers that extend it. Loading assets using the first method works as
 following:
 
-    Zen.asset.serve(:javascript, ['admin/js/vendor/mootools/core'])
+    Zen.asset.serve(:javascript, ['admin/mootools/js/core'])
 
 The first parameter is the type of files to load. Out of the box you can use
 ``:javascript`` and ``:css``. The second parameter is an array of paths relative
@@ -34,7 +34,7 @@ following:
     class Posts < Zen::Controller::AdminController
       map '/admin/posts'
 
-      serve(:javascript, ['admin/js/vendor/mootools/core'])
+      serve(:javascript, ['admin/mootools/js/core'])
     end
 
 The ``serve()`` method has the same syntax as ``Zen.asset.serve()``, it just
@@ -45,7 +45,7 @@ package):
 
     serve(
       :javascript,
-      ['admin/js/users/lib/access_rules', 'admin/js/users/access_rules'],
+      ['admin/users/js/lib/access_rules', 'admin/users/js/access_rules'],
       :methods => [:edit, :new],
       :name    => 'users'
     )
@@ -73,7 +73,7 @@ asset groups to know for what controller they should be loaded:
     Zen.asset.register_asset_group(:my_asset_group) do |asset, controller|
       asset.serve(
         :javascript,
-        ['admin/js/vendor/mootools/core'],
+        ['admin/mootools/js/core'],
         :controller => controller
       )
     end
@@ -110,8 +110,8 @@ entire layout. These files are called "global.css" and "global.js" and (in order
 to use them) should be placed in the following directories (where ROOT is the
 root directory of the application):
 
-* ROOT/admin/css/global.css
-* ROOT/admin/js/global.js
+* ROOT/admin/zen/css/global.css
+* ROOT/admin/zen/js/global.js
 
 [ramaze-asset]: https://github.com/yorickpeterse/ramaze-asset
 [ramaze-env]: https://github.com/YorickPeterse/ramaze-asset/blob/master/lib/ramaze/asset/environment.rb

data/guide/autosaving_forms.md

@@ -0,0 +1,42 @@
+# Automatically Saving Form Data
+
+To make it easier for users to work with their data Zen allows developers to
+easily implement a system that makes it possible for form data to be saved
+automatically. It is recommended that all forms that create or update data
+automatically save their data.
+
+For this to work you must first make it possible for your controllers to respond
+to these auto saving actions. This can be done by calling
+{Ramaze::Helper::Controller::ClassMethods#autosave} in your controller
+declaration. The first parameter is the model to save the data with, the second
+an array of columns to save and the third a permission required to perform the
+action. For example, the controller {Categories::Controller::CategoryGroups}
+calls this method as following:
+
+    autosave Model::CategoryGroup,
+      Model::CategoryGroup::COLUMNS,
+      :edit_category_group
+
+The array {Categories::Model::CategoryGroup::COLUMNS} contains a list of column
+names that can be set by the user.
+
+Once the controller has been prepared you must update your forms so that they
+include a ``data-autosave-url`` attribute. This attribute should contain a
+string that points to the URL that will receive the form data. If you're using
+the autosave method discussed above you should call ``.r(:autosave)`` on your
+controller. For category groups this is done as following:
+
+    :'data-autosave-url' => Categories::Controller::CategoryGroups.r(:autosave)
+
+The last step is to make sure that your form has a hidden field with the name
+"id", usually this field contains the primary value of an object (the ID). If
+this field is empty Zen will **not** save the form automatically, this is to
+prevent it from trying to save forms related to non existing objects. Adding
+this field is as simple as the following (assuming you're using the BlueForm
+helper, which you should):
+
+    f.input_hidden(:id)
+
+And that's it, Zen will take care of the rest for you from this point on. Every
+10 minutes Zen will automatically save the form for you and take care of the
+logic related to retrieving error messages, updating CSRF tokens and so on.

data/guide/changelog.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.4 - March 7th, 2012
+
+* Packages can contain multiple menus.
+* New UI for the backend.
+* All Javascript code is executed in strict mode.
+* Added a new Javascript class for parsing hash fragments: Zen.Hash.
+* Active tabs "persist" by changing URL hash fragments.
+* Slugs are generated less aggressively, allowing the use of characters such as
+  hyphens.
+* Various documentation improvements and numerous bug fixes.
+* Datepickers can be customized using HTML attributes.
+* Etanni template tags are escaped when dealing with user input.
+* Added a new package: "Dashboard". This package shows various widgets and
+  replaces the "Sections" package as the landing page after logging in.
+* Performance improvements for ``Ramaze::Helper::MenuFrontend#render_menu()``.
+  These improvements mean that only two queries are needed to retrieve a menu
+  and build the hierarchy of menu items (regardless of the amount).
+* Fixed an issue that would incorrectly generate application names when creating
+  a new application using ``zen create``.
+* Full stack traces are logged in case of errors rather than just the message.
+* Model related events (e.g. before_new_section_entry) have been moved into
+  their corresponding models.
+* Menu item manager has been re-written so that menu items can be organized
+  using a drop and drag interface.
+* The various assets used by Zen have been re-organized.
+* Custom data can be stored in themes and packages in the ``env`` attribute.
+* Forms are automatically saved every 10 minutes. This only happens for forms
+  that contain data of existing objects.
+* The controller Zen::Controller::Translations has been removed. Instead of
+  using a controller translations are simply dumped as a JSON string in a view.
+* Fixed an issue that would cause Zen to crash when trying to store certain data
+  using Ramaze::Cache::LRU.
+* Custom fields are re-filled with their values whenever a user tries to
+  save/create a section entry with invalid/missing data.
+* CSRF errors no longer show a plain text message but instead redirect users
+  back to the previous page. In case of such an error forms will be re-filled to
+  prevent data loss.
+* The sort order of menu items increments automatically unless a custom order
+  has been specified.
+* Various dependencies have been updated.
+
 ## 0.3 - November 27th, 2011
 
 * Fixed slug generation.

data/guide/faq.md

@@ -0,0 +1,49 @@
+# Frequently Asked Questions
+
+## When starting I get the warning "Failed to migrate the settings..."
+
+This warning appears when Zen failed to insert/update the various settings
+stored in the database. In almost all cases this warning is caused because the
+settings table doesn't exist. This issue can be solved by simply running the
+following command:
+
+    $ rake db:migrate
+
+## I get errors such as "no such table: X"
+
+Similar to the issue above this error is caused by missing database tables and
+again this can be fixed by simply migrating the database:
+
+    $ rake db:migrate
+
+## Users are randomly logged out and settings are lost
+
+This happens when you're running your Zen application using a Rack server that
+uses multiple processes (e.g. Unicorn) in combination with memory based caches
+for the session and settings data. The easiest fix for this problem is to simply
+use an external cache for the settings and session data.
+
+It's recommended to either use Memcached using ``Ramaze::Cache::MemCache`` or
+Redis using ``Ramaze::Cache::Redis``. These caches can be set as following in
+``config/config.rb``:
+
+    Ramaze::Cache.options.session  = Ramaze::Cache::MemCache
+    Ramaze::Cache.options.settings = Ramaze::Cache::MemCache
+
+For Redis you'd do the following:
+
+    Ramaze::Cache.options.session  = Ramaze::Cache::Redis
+    Ramaze::Cache.options.settings = Ramaze::Cache::Redis
+
+## Can I use Zen for non open source projects?
+
+Yes. Zen is licensed under the MIT license which is a very flexible license. As
+long as you keep the license intact and include it in your projects that use Zen
+you're free to do whatever you like. For more information see the "LICENSE"
+file, you can find this file in the Git repository as well as in the "File list"
+dropdown at the top right of this page.
+
+## Can I contact you personally via Email or IRC?
+
+Yes, as long as any messages are written in decent English so that I can
+understand them you're more than welcome to contact me directly.

data/guide/getting_started.md

@@ -2,9 +2,8 @@
 
 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.
+wrapper for the ``ramaze`` executable, 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:
@@ -15,7 +14,7 @@ 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
+The prototype applications generated by the Zen executable 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.
 
@@ -30,15 +29,28 @@ 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.
+yellow warnings telling you certain tables might be missing. These warnings are
+triggered whenever Zen fails to automatically insert/update the settings table.
+These warnings can be safely ignored the first time you create a new
+application.
 
-You can now start the application using your server of choice and start using
-it.
+Once an application has been created and the database tables have been put in
+place you can start using it. Starting a Zen application (during development)
+can be done using the following command:
+
+    $ ramaze start
+
+This will start the application using WEBRick, if you want to use an alternative
+server instead (such as Thin) you can do this by setting the ``-s`` option:
+
+    $ ramaze start -s thin
+
+For more information on the available commands and options execute ``zen
+--help`` or ``ramaze --help``.
 
 ## Updating Applications
 
-Updating Zen in general is quite easy and requires the following two commands::
+Updating Zen in general is quite easy and requires the following two commands:
 
     $ gem update zen
     $ rake db:migrate
@@ -47,10 +59,9 @@ 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.
+While the database migrations written for Zen will always try to migrate your
+existing content (unless this simply isn't possible) I **highly** recommend you
+to make database backups before migrating the database.
 
 ## Logging In
 

data/guide/hacking.md

@@ -5,16 +5,46 @@ 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
+## Coding 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.
+Zen follows a rather strict set of coding guidelines that developers should
+follow if they wish to contribute to Zen. Write your code like the next
+developer looking at it is a psychopath with an axe and knows where you live.
+
+### Indentation
+
+For Ruby 2 spaces per indentation level is used. The use of tabs is not
+allowed at all times and pull requests containing incorrectly indented code will
+not be accepted until the indentation has been fixed.
+
+For Javascript, CSS and HTML 4 spaces per indentation level is used instead of
+2 spaces. This is because I personally find 4 spaces to be far easier to read in
+these languages. Again no tabs are allowed.
+
+### Documentation
+
+The same rule about the psychopath with the axe applies to documentation. Proper
+documentation is very, *very* important. Documentation should be written
+following the YARD syntax and by using Markdown where needed. If you need any
+examples just look at the source code of {Zen::Package} or {Zen::Theme}.
+
+### Line Width
+
+The maximum amount of characters per line should be no greater than 80
+characters whenever possible. Sometimes it's simply not possible (e.g. when
+adding a URL) but try to stick to this as much as possible.
+
+Limiting the amount of characters per line to 80 ensures that everybody will be
+able to read it, whether they're using Vim with multiple split windows or
+reading a file in their terminal.
+
+### CSS
+
+When writing CSS the properties of a selector (background-image, color, etc)
+should be sorted alphabetically. There are a few exceptions to this. For
+example, the CSS file buttons.css contains a set of background-image properties
+that are grouped together for better readability. As long as it's readable I'm
+ok with it.
 
 ## Comitting
 
@@ -50,3 +80,4 @@ The test ouput is displayed using [TAP][tap protocol].
 [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
+[allman style]: https://en.wikipedia.org/wiki/Indent_style#Allman_style