ramaze 2011.07.25 → 2011.10.23

data/{doc/COPYING → guide/RUBY_LICENSE}

@@ -38,15 +38,12 @@ version 2 (see the file GPL), or the conditions below:
        d) make other distribution arrangements with the author.
 
   4. You may modify and include the part of the software into any other
-     software (possibly commercial).  But some files in the distribution
+     software (possibly commercial). But some files in the distribution
      are not written by the author, so that they are not under these terms.
 
-     For the list of those files and their copying conditions, see the
-     file LEGAL.
-
-  5. The scripts and library files supplied as input to or produced as 
+  5. The scripts and library files supplied as input to or produced as
      output from the software do not automatically fall under the
-     copyright of the software, but belong to whomever generated them, 
+     copyright of the software, but belong to whomever generated them,
      and may be sold commercially, and may be aggregated with this
      software.
 

data/guide/_static/logo.svg

@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 14.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 43363)  -->
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg version="1.1"
+	 id="svg2" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" sodipodi:docname="ramaze_circle_logo.svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:svg="http://www.w3.org/2000/svg" xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" inkscape:version="0.48.1 r9760"
+	 xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" width="300px" height="300px"
+	 viewBox="-64.75 -65.013 300 300" enable-background="new -64.75 -65.013 300 300" xml:space="preserve">
+<sodipodi:namedview  id="base" fit-margin-bottom="0" fit-margin-right="0" fit-margin-left="0" fit-margin-top="0" inkscape:window-y="19" inkscape:window-x="0" showgrid="false" inkscape:current-layer="layer1" inkscape:document-units="px" inkscape:cy="304.76131" inkscape:pageopacity="0.0" borderopacity="1.0" bordercolor="#666666" pagecolor="#ffffff" inkscape:cx="174.2785" inkscape:zoom="0.35355339" inkscape:window-height="747" inkscape:pageshadow="2" inkscape:window-width="1364" inkscape:window-maximized="0">
+	</sodipodi:namedview>
+<g id="layer1" transform="translate(-48.0832, -566.213)" inkscape:groupmode="layer" inkscape:label="Layer 1">
+	<g id="g3090" transform="matrix(0.382148, 0, 0, 0.382148, 29.7083, 471.954)">
+		<path id="path2985-0-2-9" inkscape:connector-curvature="0" fill="#4D4D4D" d="M478.606,340.975L377.809,399.19
+			c9.905,17.125,15.573,37.008,15.573,58.215c0,32.151-13.043,61.245-34.115,82.315l82.347,82.344
+			C516.135,547.542,531.305,432.248,478.606,340.975z"/>
+		
+			<radialGradient id="path4022_1_" cx="1471.6052" cy="-11840.3555" r="258.7954" gradientTransform="matrix(0.3821 0 0 -0.0439 -299.9709 175.6774)" gradientUnits="userSpaceOnUse">
+			<stop  offset="0" style="stop-color:#000000"/>
+			<stop  offset="1" style="stop-color:#000000;stop-opacity:0"/>
+		</radialGradient>
+		
+			<path id="path4022" sodipodi:type="arc" sodipodi:cx="148.49242" sodipodi:cy="779.41895" sodipodi:rx="258.80109" sodipodi:ry="29.698484" fill="url(#path4022_1_)" d="
+			M521.2,694.912c0,16.404-115.87,29.697-258.801,29.697S3.598,711.316,3.598,694.912c0-16.403,115.87-29.697,258.801-29.697
+			S521.2,678.509,521.2,694.912z"/>
+		<path id="path2985-0-1" inkscape:connector-curvature="0" fill="#B3B3B3" d="M359.266,539.719
+			c-21.067,21.07-50.164,34.113-82.314,34.113v116.429c61.758,0,120.988-24.53,164.661-68.197L359.266,539.719z"/>
+		<path id="path2985-3" inkscape:connector-curvature="0" fill="#FF0000" d="M276.952,224.547
+			c-128.603,0-232.857,104.254-232.857,232.857c0,128.602,104.254,232.857,232.857,232.857V573.832
+			c-64.302,0-116.429-52.126-116.429-116.428s52.128-116.429,116.429-116.429c43.095,0,80.724,23.413,100.856,58.215l100.797-58.215
+			C437.011,268.929,360.145,224.547,276.952,224.547z"/>
+		
+			<linearGradient id="path2985-2-4_1_" gradientUnits="userSpaceOnUse" x1="1924.123" y1="-878.1219" x2="1924.123" y2="-1276.0308" gradientTransform="matrix(0.3821 0 0 -0.3821 -458.3633 -76.8066)">
+			<stop  offset="0" style="stop-color:#000000;stop-opacity:0.4902"/>
+			<stop  offset="1" style="stop-color:#FFFFFF;stop-opacity:0.4902"/>
+		</linearGradient>
+		<path id="path2985-2-4" inkscape:connector-curvature="0" fill="url(#path2985-2-4_1_)" d="M276.95,258.097
+			c-110.061,0-199.305,89.244-199.305,199.306c0,110.064,89.244,199.277,199.305,199.277c110.063,0,199.28-89.214,199.28-199.277
+			C476.229,347.341,387.013,258.097,276.95,258.097z M276.95,340.764c64.418,0,116.641,52.221,116.641,116.639
+			S341.368,574.042,276.95,574.042c-64.417,0-116.637-52.221-116.637-116.639S212.533,340.764,276.95,340.764z"/>
+		<path id="path2985-0-2" inkscape:connector-curvature="0" fill="#4D4D4D" d="M493.453,332.404l-108.219,62.5
+			c10.633,18.385,16.718,39.732,16.718,62.5c0,34.518-14.004,65.753-36.625,88.374l88.406,88.409
+			C533.743,554.176,550.029,430.397,493.453,332.404z"/>
+		<path id="path2985" inkscape:connector-curvature="0" fill="#FF0000" d="M276.952,207.404c-138.071,0-250,111.929-250,250
+			c0,138.073,111.929,250.002,250,250.002V582.403c-69.036,0-125-55.964-125-124.999c0-69.036,55.964-125,125-125
+			c46.266,0,86.668,25.137,108.282,62.5l108.219-62.5C448.794,255.054,366.268,207.404,276.952,207.404z"/>
+		<path id="path2985-0" inkscape:connector-curvature="0" fill="#B3B3B3" d="M365.328,545.778
+			c-22.621,22.621-53.859,36.625-88.375,36.625v125.003c66.304,0,129.896-26.337,176.781-73.219L365.328,545.778z"/>
+	</g>
+</g>
+</svg>

data/guide/css/common.css

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

data/guide/general/cache.md

@@ -0,0 +1,167 @@
+# Caching Data
+
+Caching data such as API responses, compiled templates or database results can
+give your application a big performance boost. Ramaze tries to make this as easy
+as possible by providing an API that allows you to use different cache
+mechanisms such as Memcache or Sequel using the same syntax.
+
+## Available Drivers
+
+* {Ramaze::Cache::Sequel}
+* {Ramaze::Cache::LRU}
+* {Ramaze::Cache::MemCache}
+* {Ramaze::Cache::Redis}
+* {Ramaze::Cache::LocalMemCache}
+* {Innate::Cache::FileBased}
+* {Innate::Cache::DRb}
+* {Innate::Cache::Marshal}
+* {Innate::Cache::Memory}
+* {Innate::Cache::YAML}
+
+## Manually Caching Data
+
+Besides making it easy to automatically cache various forms of data Ramaze also
+allows you to manually cache something using your favorite storage engine. In
+order to do this you'll first have to configure Ramaze so that it knows that you
+want to cache something, this can be done as following:
+
+    Ramaze::Cache.options.names.push(:custom)
+    Ramaze::Cache.options.custom = Ramaze::Cache::MemCache
+
+    # Now we can cache the data
+    Ramaze::Cache.custom.store('usernames', ['Pistos', 'Michael Fellinger'])
+
+From this point on you can cache your data by calling methods on
+``Ramaze::Cache.custom``.
+
+## Creating Drivers
+
+Odds are there's a cache driver out there that's not supported out of the box.
+Don't worry, adding your own cache driver is pretty easy and I'll try to explain
+it as best as I can.
+
+The first step is creating a basic skeleton for our cache class. In it's most
+basic form it looks like the following:
+
+    # It's not required to declare the cache under the Ramaze namespace, feel free
+    # to use a different name.
+    module Ramaze
+      # Note that Ramaze::Cache is a class, not a module.
+      class Cache
+        # This is our own custom cache class
+        class CustomCache
+          # Pre defines the required methods. This ensures all cache drivers can
+          # be used in the same way
+          include Cache::API
+
+        end
+      end
+    end
+
+The next step is to override the methods that were created by including
+Ramaze::Cache::API. The first step is adding the method that prepares the cache
+by loading the driver provided by an external Rubygem (e.g. Dalli::Client for
+the Memcache driver) and creating the namespace for the cache. Assuming our gem
+is called "custom-cache" and the class it provides CustomCacheGem our
+cache_setup (that's the name of the setup method) method would look like the
+following:
+
+    def cache_setup(hostname, username, appname, cachename)
+      @namespace = [hostname, username, appname, cachename].compact.join('-')
+      @client    = CustomCacheGem.new(:namespace => @namespace)
+    end
+
+The next step is to add the remaining methods so that we can actually use the
+cache.
+
+    # Removes *all* keys from the cache
+    def cache_clear
+      @client.delete_all
+    end
+
+    # Removes the specified keys from the cache
+    def cache_delete(*keys)
+      keys.each do |k|
+        @client.delete(k)
+      end
+    end
+
+    # Retrieves the specified key or returns the default value
+    def cache_fetch(key, default = nil)
+      value = @client.get(key)
+
+      if !value.nil?
+        return value
+      else
+        return default
+      end
+    end
+
+    # Stores the data in the cache and return the value
+    def cache_store(key, value)
+      @client.set(key, value)
+      return value
+    end
+
+Depending on the API of your cache mechanism the method names and the way
+they're used may vary.
+
+The entire cache class now looks like the following:
+
+    # It's not required to declare the cache under the Ramaze namespace, feel free
+    # to use a different name.
+    module Ramaze
+      # Note that Ramaze::Cache is a class, not a module.
+      class Cache
+        # This is our own custom cache class
+        class CustomCache
+          # Pre defines the required methods. This ensures all cache drivers can
+          # be used in the same way
+          include Cache::API
+
+          # Prepares the cache
+          def cache_setup(hostname, username, appname, cachename)
+            @namespace = [hostname, username, appname, cachename].compact.join('-')
+            @client    = CustomCacheGem.new(:namespace => @namespace)
+          end
+
+          # Removes *all* keys from the cache
+          def cache_clear
+            @client.delete_all
+          end
+
+          # Removes the specified keys from the cache
+          def cache_delete(*keys)
+            keys.each do |k|
+              @client.delete(k)
+            end
+          end
+
+          # Retrieves the specified key or returns the default value
+          def cache_fetch(key, default = nil)
+            value = @client.get(key)
+
+            if !value.nil?
+              return value
+            else
+              return default
+            end
+          end
+
+          # Stores the data in the cache and return the value
+          def cache_store(key, value)
+            @client.set(key, value)
+            return value
+          end
+        end # CustomCache
+      end # Cache
+    end # Ramaze
+
+There really isn't that much to it when it comes to creating a cache driver. The
+important thing to remember is that the following methods are always required:
+
+* cache_setup
+* cache_clear
+* cache_delete
+* cache_fetch
+* cache_store

data/guide/general/configuration.md

@@ -0,0 +1,168 @@
+# Configuration
+
+Ramaze provides two ways of setting configuration options, using
+``Ramaze::Optioned`` and ``Ramaze::Traited``.
+
+Both Ramaze::Optioned and Ramaze::Traited are aliases for Innate::Optioned and
+Innate::Traited respectively.
+
+## Traits using Ramaze::Traited
+
+Traits provide a way of setting configuration options in a class similar to
+class variables. The advantage of using traits is that they are inherited in
+classes which allows you to use different values for a trait in a parent and
+child class. On top of that you can access traits outside of a class' scope
+(class variables are private). Ramaze uses traits for various configuration
+settings that are specific to a certain class' instance or module.
+``Ramaze::Optioned`` can't be used for this since the options set would be the
+same for all instances whereas traits can have their own values.
+
+Using traits is quite simple and can be done by including the module
+Ramaze::Traited into your class:
+
+    class Something
+      include Ramaze::Traited
+    end
+
+This module can be included into controllers, models or any other class. Once
+this module has been included into a class you can define a trait using the
+method ``trait()``. This method takes a hash where the key is the name of the
+trait and the value the value for that trait:
+
+    class Something
+      include Ramaze::Traited
+
+      trait :language => 'ruby'
+    end
+
+Inside a class instance traits can also be retrieved using this method by simply
+specifying the name of the trait:
+
+    class Something
+      include Ramaze::Traited
+
+      trait :language => 'ruby'
+
+      def language
+        puts "Language: #{trait[:language]}"
+      end
+    end
+
+Outside of a class' instance you can still retrieve a trait but you need to call
+``class_trait()`` instead:
+
+    Something.class_trait[:language] # => "ruby"
+
+Another cool feature of ``Ramaze::Traited`` is that you can get a list of all
+traits of a class and all it's parent classes using ``ancestral_trait()``. This
+method retrieves all traits where each trait that's redefined will overwrite the
+existing one. Example:
+
+    class Foo
+      include Ramaze::Traited
+      trait :one => :eins, :first => :erstes
+    end
+
+    class Bar < Foo
+      trait :two => :zwei
+    end
+
+    class Foobar < Bar
+      trait :three => :drei, :first => :overwritten
+    end
+
+    Foobar.ancestral_trait
+    # => {:three => :drei, :two => :zwei, :one => :eins, :first => :overwritten}
+
+## Options using Ramaze::Optioned
+
+Ramaze::Optioned can be used to set global options regardless of the instance of
+a class. Options set using this module are also inherited but you can't set
+different values for different instances. A good use case for Ramaze::Optioned
+is the helper ``Ramaze::Helper::Email``. This helper specifies certain options
+such as the SMTP host and username. These options don't change in a request or
+in an instance of a controller so using traits would be useless. It's also quite
+rare that you want to use different settings in a sub controller.
+
+Settings options using Ramaze::Optioned works a bit different compared to traits
+but don't worry, it's very easy. First you must include the module and then call
+``options.dsl()`` as shown below.
+
+    class Something
+      include Ramaze::Optioned
+
+      options.dsl do
+
+      end
+    end
+
+Inside the block passed to ``options.dsl()`` you can call the ``option`` method
+(aliased as ``o`` so you have to write less code). This method has the following
+syntax:
+
+    option(description, name, default value)
+
+Say we want to define a option that allows the user to change a username, this
+can be done as following:
+
+    class Something
+      include Ramaze::Optioned
+
+      options.dsl do
+        o 'Defines the username', :username, 'ramaze'
+      end
+    end
+
+Once an option is set it can be retrieved by calling ``options`` on the class
+(regardless of whether or not the call was made inside an instance):
+
+    # Outside of the class
+    Something.options.username # => "ramaze"
+
+    # Inside the class
+    options.username # => "ramaze"
+
+Dumping the entire options object to the command line using ``puts`` (or
+something similar) will also show the description of each option, the default
+value, etc:
+
+    Something.options # => {:username=>{:doc=>"Defines the username", :value=>"ramaze"}}
+
+## Configuring Paths
+
+While Ramaze is a very flexible framework it requires some basic information
+about the location of your views, layouts and so on. Ramaze does not
+automatically tries to locate these but instead uses a set of defined locations
+to look for. These paths are set using ``Ramaze::Optioned`` and can be found in
+the following options:
+
+* Ramaze.options.views
+* Ramaze.options.publics
+* Ramaze.options.layouts
+* Ramaze.options.roots
+
+Helpers aren't defined in these paths as they're considered a separate part of
+Ramaze. Instead of using ``Ramaze.options`` you'll have to update
+``Ramaze::HelpersHelper.options.paths``.
+
+Note that ``Ramaze.options.roots`` and ``Ramaze::HelpersHelper.options.paths``
+are the only two options that use absolute paths, all other paths are relative
+to the root directories.
+
+Let's say you want to have an extra view directory called "templates", this
+directory can be added as following:
+
+    Ramaze.options.views.push('templates')
+
+If the "templates" directory is located a level above the application root you'd
+do the following instead:
+
+    Ramaze.options.views.push('../templates')
+
+As mentioned before the root directories are absolute, this means that if you
+want to add a root directory you have to specify the full path to it:
+
+    Ramaze.options.roots.push('/path/to/another/root/directory')
+
+Technically you can specify relative paths but this might lead to unexpected
+behavior so it's not recommended.

data/guide/general/contributing.md

@@ -0,0 +1,108 @@
+# Contributing To Ramaze
+
+Everybody is welcome to contribute to Ramaze and/or the guide. This guide is
+meant to be a starting point for those interested in contributing code, writing
+documentation or advertising Ramaze.
+
+## Coding Standards
+
+* 2 spaces per indentation level for Ruby code.
+* Document your code as much as you can.
+* Write Bacon specifications for each change you make, especially when adding
+  new features.
+* Use Markdown for markup, both when documenting source code as well as when
+  writing pages for the guide.
+* Code should be hard wrapped at 80 characters.
+* Variables and methods are ``lower_cased`` while constants such as those used
+  to store version numbers use ``SCREAMING_SNAKE_CASE``. An example of this is
+  ``Ramaze::VERSION``. Class names and the like are ``PascalCased``.
+
+## Git Usage and Standards
+
+Ramaze uses [Git][git] as it's version control system. In order to contribute to
+Ramaze using Git there are a few things to keep in mind and a few standards to
+follow.
+
+### Commit Messages
+
+Commit messages should be splitted up in two parts, a short description of the
+commit in 50 characters or less. This short description should be followed by an
+empty line which in turn is followed by a long description. The short
+description can be seen as an Email subject while the long description would be
+the actual Email body. An example of such a commit message is the following:
+
+    Moved some chapters around.
+
+    The chapters on helpers and logging data have been moved to their own file
+    instead of being displayed in the README. Next up is writing the actual
+    documentation on logging data.
+
+    Signed-off-by: Yorick Peterse <yorickpeterse@gmail.com>
+
+Each commit should only contain a related set of changes. If you're adding a
+feature but found a bug and fixed it it's easier to keep track of changes if the
+bug and the feature are divided into two separate commits (if possible). This
+makes it easier to revert certain changes when needed or pick specific commits
+from a branch (using ``git  cherry-pick``).
+
+### Branching
+
+When working on code your changes should be made in a separate branch. The name
+of this branch should be related to the changes you're making and should be
+short. For example, if you're working on a chapter for the guide you could name
+it "documentation". Or maybe you're working on a helper, in that case you could
+name it "example-helper". In the end it doesn't really matter, just keep the
+length down a bit. Putting your changes in a separate branch makes it easier to
+manage them and pull them into the main (master) branch.
+
+### Pull Requests
+
+Once you've finished working on your changes you should notify us about the
+changes. The easiest way to do this is to send a pull request on Github.
+Information about sending and handling pull requests can be found on the [Pull
+request][pull requests] page on Github.
+
+## Writing Documentation
+
+The documentation (both the guides and the API documentation) use
+[Markdown][markdown] as its markup engine. All the text should be written in
+English. Try writing as clear as possible and remove as much spelling/grammar
+errors as you can find before submitting it to Ramaze.
+
+Linking to classes and methods can be done by wrapping the namespace/method in
+``{}``:
+
+    {Ramaze::VERSION}
+
+If you want to link to an internal file you should use the following syntax
+instead:
+
+    {file:path/to/file Title}
+
+Markdown files should be lower cased, spaces should be replaced with
+underscores. Examples of this are ``ramaze_command.md`` and
+``special_thanks.md``. Just like the Ruby code the text for the guide should be
+wrapped at 80 characters.
+
+## Spreading The Word
+
+Maybe you're not familiar with Git or perhaps you just don't have the time to
+contribute code. In both cases there are things you can do to help Ramaze grow.
+The easiest way is to just tell people about it. Talk to co-workers, give
+presentations or just suggest it whenever you think it could be useful for
+people.
+
+If you like to use the Ramaze logo for a presentation or something else you can
+freely use the official Ramaze logo displayed below. The logo is licensed under
+a [Creative Commons][cc license] license. The logo comes in two formats, a SVG
+file and a PNG of which both are displayed below.
+
+![Logo SVG][logo svg]
+![Logo PNG][logo png]
+
+[git]: http://git-scm.com/
+[pull requests]: http://help.github.com/send-pull-requests/
+[markdown]: http://daringfireball.net/projects/markdown/
+[cc license]: http://creativecommons.org/licenses/by-sa/3.0/
+[logo svg]: _static/logo.svg "The logo in SVG format"
+[logo png]: _static/logo.png "The logo in PNG format"