RubyGems - browsercms - Versions diffs - 3.0.6 → 3.1.0 - Mend

browsercms 3.0.6 → 3.1.0

Files changed (995) hide show

data/doc/guides/html/authentication.html ADDED

@@ -0,0 +1,201 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <title></title>
+    <link rel="stylesheet" type="text/css" href="files/stylesheets/syntax.css" />
+    <script type="text/javascript" src="files/javascripts/code_highlighter.js"></script>
+    <script type="text/javascript" src="files/javascripts/highlighters.js"></script>
+    <style type="text/css">
+      body {
+        background: #FFFFFF url(images/bg.png) repeat-x scroll 0 0;
+        font-family: "Trebuchet MS", Helvetica, Verdana, Arial, sans-serif;
+        margin: 0;
+        padding: 0;
+      }
+      #page {
+        margin: 0 auto;
+        text-align: left;
+        width: 1000px;
+      }
+      #header {
+        height: 110px;
+      }
+      div.top_cap {
+        background: transparent url(images/top_cap.png) no-repeat scroll 0 0;
+        height: 10px;
+      }
+      #contentwrap {
+        background: transparent url(images/dot.png) repeat scroll 0 0;
+        float: left;
+        width: 1000px;
+      }
+      div.bottom_cap {
+        background: transparent url(images/bottom_cap.png) no-repeat scroll 0 0;
+        height: 9px;
+      }
+      div.top_cap_content {
+        background: transparent url(images/top_cap_content.png) no-repeat scroll 0 0;
+        height: 5px;
+      }
+      #content {
+        background-color: #FFFFFF;
+        margin: 0 5px;
+        padding: 0 10px;
+      }
+      div.title {
+        padding: 20px;
+      }
+      div.title h1 {
+        border-bottom: 3px solid #505358;
+        color: #FFFFFF;
+        font-size: 24pt;
+        font-weight: normal;
+        line-height: 1;
+        margin: 0 0 10px;
+        padding-bottom: 10px;
+      }
+      td.sidebar {
+        font-size: 8pt;
+        width: 165px;
+        padding: 5px;
+      }
+      td.sidebar ol {
+        margin-left: 20px;
+        padding: 0;
+        line-height: 1.5;
+      }
+      td.sidebar ol li {
+        margin: 0;
+        padding: 0;
+      }
+      td.sidebar ol li ul {
+        list-style-type: none;
+        padding-left: 10px;
+      }
+      td.guides {
+        font-size: 10pt;
+        width: 800px;
+        padding: 10px;
+      }
+      .code_container {
+        padding: 10px;
+        background: #eee;
+        border: 1px solid #ccc;
+        overflow: auto;
+        width: 760px;
+      }
+      pre, code {
+        overflow: auto;
+        white-space:pre;
+      }
+      .note {
+	-moz-background-clip:border;
+	-moz-background-inline-policy:continuous;
+	-moz-background-origin:padding;
+	background:#FFF9D8 url(../images/tab_note.gif) no-repeat scroll left top;
+	border:medium none;
+	margin:0.25em 0 1.5em;
+	padding:1em 1em 0.25em 48px;
+	}
+    </style>
+  </head>
+  <body>
+    <div id="page">
+      <div id="header">
+        <a href="index.html"><img style="border:0px" src="images/browsercms_logo.png" alt="BrowserCMS"/></a>
+      </div>
+      <div id="main">
+        <div class="top_cap"></div>
+        <div id="contentwrap">
+          <div class="title">
+            <h1></h1>
+          </div>
+          <div class="top_cap_content"></div>
+          <div id="content">
+            <table width="100%" cellpadding="0" cellspacing="0" border="0">
+              <tr>
+                <td class="sidebar" valign="top">
+                        <div id="subCol">
+        <h3 class="chapter"><img src="images/chapters_icon.gif" alt="" />Chapters</h3>
+        <ol class="chapters">
+</ol></div>
+                </td>
+                <td class="guides">
+                  <h2>Using <span class="caps">CMS</span> Authentication</h2>
+<p>When you create public controllers, you may want to take advantage of the <span class="caps">CMS</span> authentication system. Create an action that
+looks like this:</p>
+<div class="code_container"><code class="ruby">class MyNewController &lt; ApplicationController
+  # This adds methods to your controller to work with the authenticated user.
+  include Cms::Authentication::Controller
+  def do_something_interesting
+    # The current_user method looks up the user based on either a cookie, or session variable.
+    user = current_user
+    if user.guest?
+      redirect_to &quot;/system/access-denied&quot;
+    else
+      redirect_to &quot;/my_target/page&quot;
+    end
+  end
+end</code></div>
+<p>The current_user method is also available in Portlets (maybe), as well as in the view files for both portlets and templates.</p>
+<h3>Understanding Guest users
+Many visitors to a <span class="caps">CMS</span> site will not be logged in. These users are considered to be members of a special group, called &#8216;Guest&#8217;. This
+group allows staff to set permissions for denying entry to specific sections. When you call the following:</h3>
+<div class="code_container"><code class="ruby">user = current_user</code></div>
+<p>if there the user is not logged in, a
+dirty_workaround_for_notextile_2
+ object will be returned. This user has all the permissions of the guest group, which are
+usually limited to viewing public sections.</p>
+<h2>Working with the Content <span class="caps">API</span>
+One of the central features that the content <span class="caps">API</span> adds to models is versioning and publishing. Each content block can either be published or in draft. The data for a block is split between two tables, the primary table and it&#8217;s version table. The primary table
+stores the &#8216;live&#8217; version of a block, typically the last &#8216;Published&#8217; version of a block. The versions table stores all other versions, including future edits which are unpublished.</h2>
+<h3>Differences between ActiveRecord and Content <span class="caps">API</span>
+This can cause some confusion when using basic ActiveRecord operations, where you might not get what you expect. For example, suppose we create an Event Block</h3>
+<div class="code_container"><code class="ruby">class Event &lt; ActiveRecord::Base
+  acts_as_content_block
+end
+event = Event.create!(:name=&gt;&quot;Event #1&quot;, :save_and_publish=&gt;true)
+event.name = &quot;Event #2&quot;
+event.save!
+assert_equals &quot;Event #2&quot;, Event.find(event.id) # This is false, and will fail.</code></div>
+<p>In this case, &#8220;Event #2&#8221; is a draft, stored in the &#8216;events_versions&#8217; table. To create and publish the event, you can do this:</p>
+<div class="code_container"><code class="ruby">event = Event.create!(:name=&gt;&quot;Event #1&quot;, :save_and_publish=&gt;true)
+event.name = &quot;Event #2&quot;
+event.publish! # This will both publish and save the record.
+assert_equals &quot;Event #2&quot;, Event.find(event.id) # This is now true.</code></div>
+                </td>
+              </tr>
+            </table>
+          </div>
+        </div>
+        <br clear="all"/>
+        <div class="bottom_cap"></div>
+      </div>
+    </div>
+  </body>
+</html>

data/doc/guides/html/build_it_yourself.html CHANGED

@@ -105,7 +105,15 @@
         overflow: auto;
         white-space:pre;
       }
+      .note {
+	-moz-background-clip:border;
+	-moz-background-inline-policy:continuous;
+	-moz-background-origin:padding;
+	background:#FFF9D8 url(../images/tab_note.gif) no-repeat scroll left top;
+	border:medium none;
+	margin:0.25em 0 1.5em;
+	padding:1em 1em 0.25em 48px;
+	}
     </style>
   </head>
   <body>
@@ -127,40 +135,35 @@
                         <div id="subCol">
         <h3 class="chapter"><img src="images/chapters_icon.gif" alt="" />Chapters</h3>
         <ol class="chapters">
-<li><a href="#things-you-need-first">Things you need first</a><ul></ul></li><li><a href="#getting-the-source-from-github">Getting the source from GitHub</a><ul></ul></li><li><a href="#installing-the-gem-locally">Installing the Gem locally</a><ul></ul></li><li><a href="#quick-start">Quick Start</a><ul></ul></li></ol></div>
+<li><a href="#things-you-need-first">Things you need first</a><ul></ul></li><li><a href="#getting-the-source-from-github">Getting the source from GitHub</a><ul></ul></li><li><a href="#installing-the-gem-locally">Installing the Gem locally</a><ul></ul></li></ol></div>
                 </td>
                 <td class="guides">
                   <h2>Building on the Edge</h2>
 <p>The purpose of this guide is to help developers who want to work with the very latest code from Github. It covers how to:</p>
 <ul>
 	<li>Get the latest copy of the source code from Github.</li>
-	<li>Build and install the BrowserCMS product.</li>
-	<li>Create a new project which uses BrowserCMS</li>
+	<li>Build and install BrowserCMS as a gem.</li>
 </ul>
-<p>If you want to get BrowserCMS the easy way, see link:getting_started.html[Getting Started] instead.</p>
+<p>If you want to get BrowserCMS the easy way, see <a href="getting_started.html">Getting Started</a> instead.</p>
+<p>This guide is for BrowserCMS <strong>3.1</strong>. Some code shown here may not work with older versions of BrowserCMS.</p>
                   <h3 id="things-you-need-first">1 Things you need first</h3>
 <p>Before you can build BrowserCMS locally, there are few other bits of software you should have installed.</p>
-<p>1. <strong>Git</strong> &#8211; Distributed version control system. The code for BrowserCMS is on http://github.com/browsermedia/browsercms/[Git Hub], so you need to http://git-scm.com[get Git] to get it.
-2. <strong>Rails 2.3</strong> (or later) &#8211; We make use of some of the newer features from Rails like templates.
-3. <strong>A Database</strong> &#8211; Either Mysql or the Sqlite gems should be installed.
-4. <strong>Jeweler</strong> &#8211; Another gem http://technicalpickles.github.com/jeweler[Jeweler] is required to build the gem yourself locally.</p>
+<ol>
+	<li><strong>Git</strong> &#8211; Distributed version control system. The code for BrowserCMS is on <a href="http://github.com/browsermedia/browsercms">Github</a>, so you need to have <a href="http://git-scm.com">Git</a> fetch the code.</li>
+	<li><strong>Rails 2.3</strong> (or later) &#8211; We make use of some of the newer features from Rails like templates.</li>
+	<li><strong>A Database</strong> &#8211; Either Mysql or the Sqlite gems should be installed. MySQL is required if you want to do development on the core.</li>
+	<li><strong>Jeweler</strong> &#8211; Another gem <a href="http://technicalpickles.github.com/jeweler">Jeweler</a> is required to build the gem yourself locally.</li>
+</ol>
 <h3 id="getting-the-source-from-github">2 Getting the source from GitHub</h3>
 <p>To build the gem from source, and install it on your system, type the following:</p>
 <div class="code_container"><code class="html">$ git clone git://github.com/browsermedia/browsercms.git</code></div>
 <h3 id="installing-the-gem-locally">3 Installing the Gem locally</h3>
 <p>Once you have the source code, you can build and install the Gem via:</p>
 <div class="code_container"><code class="html">$ cd browsercms
 $ rake install</code></div>
-<p>On *unix, this will sudo install, so you will need to provide your password. Once you have the BrowserCMS Gem installed,
+<p>This will use Jeweler to build and install the gem. Once you have the BrowserCMS Gem installed,
 you can use it to create new projects, which will be configured to use it. At this point, you now have the gem installed,
-so you can follow the instructions in <a href="getting_started.html">Getting Started</a> starting with section 2 (Trying out BrowserCMS).</p>
-<h3 id="quick-start">4 Quick Start</h3>
-<p>You can also just do the following to create a demo project.</p>
-<div class="code_container"><code class="html">$ cd ~/projects
-$ rails my_new_project_name -d mysql -m http://browsercms.org/templates/demo.rb
-$ cd my_new_project_name
-$ script/server</code></div>
+so you can follow the instructions in <a href="getting_started.html">Getting Started</a>.</p>
                 </td>
               </tr>
             </table>

data/doc/guides/html/building_modules.html CHANGED

@@ -2,7 +2,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
-    <title></title>
+    <title>Creating your own modules</title>
     <link rel="stylesheet" type="text/css" href="files/stylesheets/syntax.css" />
     <script type="text/javascript" src="files/javascripts/code_highlighter.js"></script>
     <script type="text/javascript" src="files/javascripts/highlighters.js"></script>
@@ -105,7 +105,15 @@
         overflow: auto;
         white-space:pre;
       }
+      .note {
+	-moz-background-clip:border;
+	-moz-background-inline-policy:continuous;
+	-moz-background-origin:padding;
+	background:#FFF9D8 url(../images/tab_note.gif) no-repeat scroll left top;
+	border:medium none;
+	margin:0.25em 0 1.5em;
+	padding:1em 1em 0.25em 48px;
+	}
     </style>
   </head>
   <body>
@@ -117,7 +125,7 @@
         <div class="top_cap"></div>
         <div id="contentwrap">
           <div class="title">
-            <h1></h1>
+            <h1>Creating your own modules</h1>
           </div>
           <div class="top_cap_content"></div>
           <div id="content">
@@ -127,58 +135,106 @@
                         <div id="subCol">
         <h3 class="chapter"><img src="images/chapters_icon.gif" alt="" />Chapters</h3>
         <ol class="chapters">
-</ol></div>
+<li><a href="#getting-started">Getting Started</a><ul><li><a href="#generated-files">Generated Files</a></li></ul></li><li><a href="#creating-blocks">Creating Blocks</a><ul><li><a href="#defining-routes-for-the-module">Defining routes for the module</a></li></ul></li><li><a href="#displaying-products-in-our-site">Displaying Products in our Site</a><ul></ul></li><li><a href="#copying-files-into-projects">Copying files into projects.</a><ul></ul></li><li><a href="#conventions-when-building-your-module">Conventions When Building Your Module</a><ul></ul></li><li><a href="#testing-your-gem">Testing Your Gem</a><ul></ul></li></ol></div>
                 </td>
                 <td class="guides">
-                  <h2>Using <span class="caps">CMS</span> Authentication</h2>
-<p>When you create public controllers, you may want to take advantage of the <span class="caps">CMS</span> authentication system. Create an action that
-looks like this:</p>
-<div class="code_container"><code class="ruby">class MyNewController &lt; ApplicationController
-  # This adds methods to your controller to work with the authenticated user.
-  include Cms::Authentication::Controller
-  def do_something_interesting
-    # The current_user method looks up the user based on either a cookie, or session variable.
-    user = current_user
-    if user.guest?
-      redirect_to &quot;/system/access-denied&quot;
-    else
-      redirect_to &quot;/my_target/page&quot;
-    end
+                  <h2>Creating your own modules</h2>
+<p>This guide covers how to create and package modules for BrowserCMS. Modules are the primary way to expand the functionality of the BrowserCMS core project.  After reading this guide, you should understand how to:</p>
+<ul>
+	<li>Create a new module</li>
+	<li>Add blocks and portlets</li>
+	<li>Add new controllers</li>
+	<li>How to modify core modules using open classes</li>
+	<li>Package and Test your module in another <span class="caps">CMS</span> project.</li>
+</ul>
+<p>This guide is for BrowserCMS <strong>3.1</strong>. Some code shown here may not work with older versions of BrowserCMS.</p>
+                  <h3 id="getting-started">1 Getting Started</h3>
+<p>The guide is going to walk how a new module can be created from scratch. The goal for our sample module will be to add some Pet Store functionality to BrowserCMS, and allow editors to create new products and users to browse a product catalog. This module will be built to show off some of the most common techniques used to add dynamic behavior to BrowserCMS projects.</p>
+<p>To start a new module, run the following command:</p>
+<div class="code_container"><code class="html">$ bcms bcms_pet_store -m module</code></div>
+<p>This will create a browsercms project, which will be structured to help test your module as its being built. The <tt>-m module</tt> flag will a project design to be packaged as gem for reuse. Note that the name of any module must start with <tt>bcms_</tt> or the files won&#8217;t be generated correctly.</p>
+<h4 id="generated-files">1.1 Generated Files</h4>
+<p>After the project has been created, there are a number of files which are created. Here&#8217;s a brief list of the notable files and their purpose.</p>
+<table>
+	<tr>
+		<th>File </th>
+		<th>Purpose </th>
+	</tr>
+	<tr>
+		<td> .gitignore </td>
+		<td> Contains a list of files which will not be checked into git </td>
+	</tr>
+	<tr>
+		<td> bcms_pet_store.gemspec</td>
+		<td> An initial gemspec to package the module as a gem. </td>
+	</tr>
+	<tr>
+		<td> config/initializers/init_module.rb </td>
+		<td> Called by BrowserCMS startup to load the module&#8217;s files. (You shouldn&#8217;t need to modify this) </td>
+	</tr>
+	<tr>
+		<td> lib/bcms_pet_store.rb </td>
+		<td> Used to require files not in the app/ loadpath. You may need to update this if you add new files under lib. </td>
+	</tr>
+	<tr>
+		<td> public/bcms/bcms_petstore/ </td>
+		<td> A directory for public files which should be copied into projects that use this module. </td>
+	</tr>
+	<tr>
+		<td> lib/bcms_pet_store/routes.rb </td>
+		<td> A place to define routes for this module, like content blocks. These routes will be included in projects that use this gem. </td>
+	</tr>
+	<tr>
+		<td> rails/init.rb </td>
+		<td> Add the gem root to the Rails load path, including determining which files will be copied from the gem into projects .</td>
+	</tr>
+</table>
+<p>Note the gemspec, license (<span class="caps">LGPL</span>) and copywrite files specific to BrowserMedia, therefore you will likely want to edit these later to reflect your own purposes.</p>
+<h3 id="creating-blocks">2 Creating Blocks</h3>
+<p>One of the most common reason to creating a module is to define one or more Content blocks that can be added to projects. For our Pet Store example, we will create a Product block which will represent a purchasable good in our Store. Run the following command inside the project.</p>
+<div class="code_container"><code class="html">$ script/generate content_block product name:string price:integer description:html</code></div>
+<p>This is the exact same generator used to create content blocks for any BrowserCMS project. You can run <tt>rake db:migrate</tt> and see this block in the <span class="caps">CMS</span> Admin UI.</p>
+<h4 id="defining-routes-for-the-module">2.1 Defining routes for the module</h4>
+<p>Each content block will have its own routes for the Admin UI, which the generator will place into the <tt>config/routes.rb</tt>. This works fine for a BrowserCMS project, but not as a module as the <tt>config/routes.rb</tt> file won&#8217;t be packaged in the gem. To fix this, we need to move the route from the <tt>config/routes.rb</tt> to the <tt>lib/bcms_pet_store/routes.rb</tt>. Open the latter file and alter to look like this:</p>
+<div class="code_container"><code class="ruby">module Cms::Routes
+  def routes_for_bcms_pet_store
+    namespace(:cms) do |cms|
+       cms.content_blocks :products
+    end
   end
 end</code></div>
-<p>The current_user method is also available in Portlets (maybe), as well as in the view files for both portlets and templates.</p>
-<h3>Understanding Guest users
-Many visitors to a <span class="caps">CMS</span> site will not be logged in. These users are considered to be members of a special group, called &#8216;Guest&#8217;. This
-group allows staff to set permissions for denying entry to specific sections. When you call the following:</h3>
-<div class="code_container"><code class="ruby">user = current_user</code></div>
-<p>if there the user is not logged in, a
-dirty_workaround_for_notextile_2
- object will be returned. This user has all the permissions of the guest group, which are
-usually limited to viewing public sections.</p>
-<h2>Working with the Content <span class="caps">API</span>
-One of the central features that the content <span class="caps">API</span> adds to models is versioning and publishing. Each content block can either be published or in draft. The data for a block is split between two tables, the primary table and it&#8217;s version table. The primary table
-stores the &#8216;live&#8217; version of a block, typically the last &#8216;Published&#8217; version of a block. The versions table stores all other versions, including future edits which are unpublished.</h2>
-<h3>Differences between ActiveRecord and Content <span class="caps">API</span>
-This can cause some confusion when using basic ActiveRecord operations, where you might not get what you expect. For example, suppose we create an Event Block</h3>
-<div class="code_container"><code class="ruby">class Event &lt; ActiveRecord::Base
-  acts_as_content_block
-end
-event = Event.create!(:name=&gt;&quot;Event #1&quot;, :save_and_publish=&gt;true)
-event.name = &quot;Event #2&quot;
-event.save!
-assert_equals &quot;Event #2&quot;, Event.find(event.id) # This is false, and will fail.</code></div>
-<p>In this case, &#8220;Event #2&#8221; is a draft, stored in the &#8216;events_versions&#8217; table. To create and publish the event, you can do this:</p>
-<div class="code_container"><code class="ruby">event = Event.create!(:name=&gt;&quot;Event #1&quot;, :save_and_publish=&gt;true)
-event.name = &quot;Event #2&quot;
-event.publish! # This will both publish and save the record.
-assert_equals &quot;Event #2&quot;, Event.find(event.id) # This is now true.</code></div>
+<p>Then edit the +config/routes.rb file to look like this:</p>
+<div class="code_container"><code class="ruby">ActionController::Routing::Routes.draw do |map|
+  map.routes_for_bcms_pet_store
+  map.routes_for_browser_cms
+end</code></div>
+<p>By doing this, we are defining our routes in a reusuable way, both for the gem as well as the bcms_pet_store project for testing. All routes that you want to make available to projects should be defined in the <tt>lib/bcms_pet_store/routes.rb</tt> file, which developers will add to their routes by calling <tt>map.routes_for_bcms_pet_store</tt>.</p>
+<p>Restart your server and verify that you see that the routes still work.</p>
+<h3 id="displaying-products-in-our-site">3 Displaying Products in our Site</h3>
+<p>Now that we have our product data, we can use the Admin UI to create some sample product data. But how do we display our products to our site visitors. In a typical Rails project, you might create a controller that looks up the products and shows them in a view. However, in a BrowserCMS project we probably want to take advantage of displaying products on <span class="caps">CMS</span> page which can be styled by our <span class="caps">CMS</span> editors.</p>
+<p>To do this, we need to use portlets.</p>
+<h3 id="copying-files-into-projects">4 Copying files into projects.</h3>
+<ul>
+	<li><code>rails/init.rb</code></li>
+</ul>
+<blockquote>
+<p>Adds the gem root to the rails paths, adds all migration files to the list of files that will be copied into any application using the module when <code>script/generate browser_cms</code> is run, and adds all files in <code>public/bcms/bcms_[module name]/</code> to the list of files that will be copied into any application using the module when <code>script/generate browser_cms</code> is run.</p>
+</blockquote>
+<h3 id="conventions-when-building-your-module">5 Conventions When Building Your Module</h3>
+<p>Build your module as if you were building a rails application that does whatever you want.</p>
+<p>That said, there are some conventions that tend to make things easier.</p>
+<p>First, place any files that are used as configuration files for public assects (for example, the fckeditor) in the <code>public/bcms_config/[module_name]</code> directory and have the gem only copy them if they are not already there.  For example you can add code like the following to the <code>rails/init.rb</code> file.</p>
+<div class="code_container"><code class="ruby">unless File.exists?(&quot;#{RAILS_ROOT}/public/bcms_config/fckeditor/fckstyles.xml&quot;)
+  Cms.add_generator_paths gem_root, &quot;public/bcms_config/fckeditor/fckstyles.xml&quot;
+end</code></div>
+<p>This will make the required configuration file available to the fckeditor, but it won&#8217;t overwrite it (or even ask you if you want to overwrite it) every time you run <code>script/generate browser_cms</code> for your application.</p>
+<h3 id="testing-your-gem">6 Testing Your Gem</h3>
+<p>We strongly encourage the creation of unit, functional, and integration tests as part of your module.</p>
+<p>We also suggest that you test your gem against a BrowserCMS application.  To do this, first run</p>
+<p><code>bcms module_tester -m demo</code></p>
+<p>wherever (I use <code>/var/tmp</code>).  Edit the <code>config/environment.rb</code> file to include the line</p>
+<p><code>gem.config 'bcms_[module name]'</code></p>
+<p>then run the app locally and make sure your module works as expected.</p>
                 </td>
               </tr>
             </table>