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/customizing_browsercms.html ADDED

@@ -0,0 +1,173 @@
+<!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>Customizing BrowserCMS</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>Customizing BrowserCMS</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">
+<li><a href="#overview">Overview</a><ul></ul></li><li><a href="#content-blocks">Content Blocks</a><ul></ul></li><li><a href="#portlets">Portlets</a><ul></ul></li><li><a href="#modules">Modules</a><ul></ul></li></ol></div>
+                </td>
+                <td class="guides">
+                  <h2>Customizing BrowserCMS</h2>
+<p>This guide serves an overview for the different ways that developers can customize and extent BrowserCMS websites. It will
+cover the following concepts:</p>
+<ul>
+	<li>Content Blocks provide both Model and UI scaffolding</li>
+	<li>Portlets provide reusuable component behavior that can be added to pages</li>
+	<li>Modules provide a way to package blocks and portlets as resuable gems for other BrowserCMS projects.</li>
+</ul>
+                  <h3 id="overview">1 Overview</h3>
+<p>As a content management system, BrowserCMS offers a number of avenues for customizing a website. In addition, to the
+standard Rails extension points like Models, Views and Controllers, there are several additional extensions points. These
+include:</p>
+<ul>
+	<li>Content Blocks</li>
+	<li>Portlets</li>
+	<li>Pages</li>
+	<li>Modules</li>
+</ul>
+<h3 id="content-blocks">2 Content Blocks</h3>
+<h3 id="portlets">3 Portlets</h3>
+<h3 id="modules">4 Modules</h3>
+                </td>
+              </tr>
+            </table>
+          </div>
+        </div>
+        <br clear="all"/>
+        <div class="bottom_cap"></div>
+      </div>
+    </div>
+  </body>
+</html>

data/doc/guides/html/deployment_guide.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,15 +135,20 @@
                         <div id="subCol">
         <h3 class="chapter"><img src="images/chapters_icon.gif" alt="" />Chapters</h3>
         <ol class="chapters">
-<li><a href="#configure-the-production-environment">Configure the Production Environment</a><ul></ul></li><li><a href="#setting-up-virtual-hosts-for-page-caching">Setting Up Virtual Hosts for Page Caching</a><ul></ul></li></ol></div>
+<li><a href="#configure-the-production-environment">Configure the Production Environment</a><ul></ul></li><li><a href="#setting-up-virtual-hosts-for-page-caching">Setting Up Virtual Hosts for Page Caching</a><ul></ul></li><li><a href="#using-capistrano-to-deploy">Using Capistrano to Deploy</a><ul></ul></li></ol></div>
                 </td>
                 <td class="guides">
                   <h2>BrowserCMS Deployment Guide</h2>
 <p>This guide covers how to setup the Apache Passenger (mod_rails) production environment for your BrowserCMS application.</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="configure-the-production-environment">1 Configure the Production Environment</h3>
-<p>Make sure the config/environments/production.rb file has these two configuration settings.  If you created your BrowserCMS Rails app using one of the application templates, this will already have been added.</p>
-<div class="code_container"><code class="ruby">config.action_view.cache_template_loading = false
-config.action_controller.page_cache_directory = RAILS_ROOT + &quot;/public/cache/&quot;</code></div>
+<p>Make sure the config/environments/production.rb file has these following configuration settings.  If you created your BrowserCMS Rails app using one of the application templates, this will already have been added but you may need to configure them to match your site&#8217;s domain and mail server.</p>
+<div class="code_container"><code class="ruby">SITE_DOMAIN=&quot;www.sitedomain.com&quot; # This should match the URL for your public CMS site.
+config.action_view.cache_template_loading = false
+config.action_controller.page_cache_directory = RAILS_ROOT + &quot;/public/cache/&quot;
+config.action_mailer.smtp_settings = {:address =&gt; 'mail.yourmailserver.com',
+                                      :domain =&gt; &quot;#{SITE_DOMAIN}&quot;}</code></div>
+<p>The SITE_DOMAIN in particular is used to build links to <span class="caps">CMS</span> pages that can be emailed.</p>
 <h3 id="setting-up-virtual-hosts-for-page-caching">2 Setting Up Virtual Hosts for Page Caching</h3>
 <p>In order to setup BrowserCMS to due page caching, you need to create two virtual hosts for your site.  The main purpose for this is to allow page caching to work when you access a page on the main site, but then have the pages not be served from the cache when you are working in the BrowserCMS interface.</p>
 <div class="code_container"><code class="plain">&lt;VirtualHost *:80&gt;
@@ -167,6 +180,19 @@ config.action_controller.page_cache_directory = RAILS_ROOT + &quot;/public/cache
     Allow from all
   &lt;/directory&gt;
 &lt;/VirtualHost&gt;</code></div>
+<h3 id="using-capistrano-to-deploy">3 Using Capistrano to Deploy</h3>
+<p>If you plan to use Capistrano to deploy your sites, you will likely need to make some additional configuration changes. In particular, you will want to change where files are uploaded to. For example, add the following your <em>config/initializers/browsercms.rb</em> file.</p>
+<div class="code_container"><code class="ruby">if RAILS_ENV == 'production'
+  # Uploaded files/images will be written out to this directory instead of the default (tmp/uplaods) directory
+  Attachment.storage_location = File.join(Rails.root, &quot;uploads&quot;)
+end</code></div>
+<p>Then update your config/deploy.rb (which Capistrano should generate) so that it creates an shared/uploads directory, and a symlink to it from within your project.</p>
+<div class="code_container"><code class="ruby">task :link_shared_directories do
+  run &quot;ln -s #{shared_path}/uploads #{release_path}/uploads&quot;
+end
+after &quot;deploy:update_code&quot;, :link_shared_directories</code></div>
+<p>The binary data for uploaded files will be placed in shared/uploads and the <span class="caps">CMS</span> will serve the data from there.</p>
                 </td>
               </tr>
             </table>

data/doc/guides/html/getting_started.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,46 +135,73 @@
                         <div id="subCol">
         <h3 class="chapter"><img src="images/chapters_icon.gif" alt="" />Chapters</h3>
         <ol class="chapters">
-<li><a href="#installing-browsercms">Installing BrowserCMS</a><ul><li><a href="#things-you-need-first">Things you need first</a></li></ul></li><li><a href="#trying-out-browsercms">Trying out BrowserCMS</a><ul><li><a href="#with-sqlite3">With SQLite3</a></li><li><a href="#with-mysql">With MySQL</a></li><li><a href="#using-your-site">Using your Site</a></li></ul></li><li><a href="#starting-a-real-project">Starting a &#8216;Real&#8217; project</a><ul></ul></li></ol></div>
+<li><a href="#this-guide-assumes">This Guide Assumes</a><ul></ul></li><li><a href="#starting-a-demo-project">Starting a demo project</a><ul><li><a href="#installing-browsercms">Installing BrowserCMS</a></li><li><a href="#creating-a-demo-website">Creating a Demo Website</a></li><li><a href="#using-your-site">Using your Site</a></li></ul></li><li><a href="#starting-a-real-project">Starting a &#8216;Real&#8217; project</a><ul></ul></li><li><a href="#the-short-command">The short command</a><ul></ul></li><li><a href="#getting-command-line-help">Getting Command line Help</a><ul></ul></li><li><a href="#trouble-shooting">Trouble Shooting</a><ul><li><a href="#creation-fails-to-create-mysql-database">Creation fails to create MySQL Database</a></li></ul></li><li><a href="#deploying-to-production">Deploying to production</a><ul></ul></li></ol></div>
                 </td>
                 <td class="guides">
                   <h2>Getting Started</h2>
 <p>The purpose of this guide is help new developers get up and running with BrowserCMS. It covers how to:</p>
 <ul>
 	<li>Install the BrowserCMS gem</li>
-	<li>Create a new project which uses BrowserCMS</li>
+	<li>Create a demo project to explore BrowserCMS</li>
+	<li>Create a blank project for building a website from scratch</li>
 </ul>
-                  <h3 id="installing-browsercms">1 Installing BrowserCMS</h3>
-<p>BrowserCMS is packaged as a gem, which can be included in any Rails project. The gem contains the code for the cms application itself, as well as public assets, including stylesheets, images and javascript. These assets will be copied from the gem into your project as part of the install process.</p>
-<p>The gem is hosted at RubyForge, so you can install it by doing:</p>
-<div class="code_container"><code class="html">$ sudo gem install browsercms</code></div>
-<h4 id="things-you-need-first">1.1 Things you need first</h4>
+<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="this-guide-assumes">1 This Guide Assumes</h3>
 <p>Before you can create a project using BrowserCMS, you will need to have the following installed.</p>
-<p>1. <strong>Rails 2.3</strong> (or later) &#8211; We make use of some of the newer features from Rails like application generator templates.
-2. <strong>A Database</strong> &#8211; Either Mysql or the Sqlite gems should be installed.</p>
-<h3 id="trying-out-browsercms">2 Trying out BrowserCMS</h3>
-<p>This section will cover how to create a demo project using BrowserCMS, so you can play around with it. It will create a sample project, with some pages and content to play around with. You will need to choose one of the following options, depending on which database you want to use.</p>
-<h4 id="with-sqlite3">2.1 With SQLite3</h4>
-<div class="code_container"><code class="html">$ rails my_new_project_name -m http://browsercms.org/templates/demo.rb
-$ cd my_new_project_name
-$ script/server</code></div>
-<p>By default, Rails assumes that if you do not specify a -d flag, that you want to use SQLite as your project&#8217;s database. You need to have the sqlite3-ruby gem installed for this to work.</p>
-<h4 id="with-mysql">2.2 With MySQL</h4>
-<div class="code_container"><code class="html">$ rails my_new_project_name -d mysql -m http://browsercms.org/templates/demo.rb
-$ cd my_new_project_name
+<ol>
+	<li>The <a href="http://www.ruby-lang.org/en/downloads">Ruby</a> Language</li>
+	<li>The <a href="http://rubyforge.org/frs/?group_id=126">RubyGems</a> packaging system</li>
+	<li>The <a href="http://rubyonrails.org/download">Rails</a> framework (2.3 or later &#8211; But not 3.0 yet)</li>
+	<li>A working installation of <a href="http://www.sqlite.org/">SQLite</a> or <a href="http://www.mysql.com/">MySQL</a> as well as the gems for your database of choice.</li>
+</ol>
+<h3 id="starting-a-demo-project">2 Starting a demo project</h3>
+<p>This section of the guide will cover creating a sample website with BrowserCMS, using a demo website layout and content.
+ The goal is to give you some content and templates to play with to explore the <span class="caps">CMS</span>. Later sections of this guide will
+ cover the more common cases where you are creating a new website from scratch and want only the bare minimums.</p>
+<h4 id="installing-browsercms">2.1 Installing BrowserCMS</h4>
+<p>BrowserCMS is packaged as a gem which can be included in any Rails project. To install the gem, do the following:</p>
+<div class="code_container"><code class="html">$ gem install browsercms</code></div>
+<h4 id="creating-a-demo-website">2.2 Creating a Demo Website</h4>
+<p>Run the following from your terminal window.</p>
+<div class="code_container"><code class="html">$ browsercms project_name -m demo
+$ cd project_name
 $ script/server</code></div>
-<p>Here we specify the -d mysql flag to rails, which will create our project using MySQL. You need to have the mysql gem installed for this to work.</p>
+<p>This will create a BrowserCMS project which used SQLite as the data storage. You need to have the sqlite3-ruby gem installed for this to work.</p>
 <h4 id="using-your-site">2.3 Using your Site</h4>
 <p>Open your browser to <a href="http://localhost:3000/cms">http://localhost:3000/cms</a> to log into the admin for the <span class="caps">CMS</span>. Enter the default username/password (in development mode) is username=cmsadmin, password=cmsadmin. You should be now be logged in, viewing the home page of the site. You can now edit or add new content via the admin interface.</p>
 <p>To learn more about the types of things you can do with BrowserCMS, see the <a href="user_guide.html">User&#8217;s Guide</a>.</p>
 <h3 id="starting-a-real-project">3 Starting a &#8216;Real&#8217; project</h3>
-<p>Demo sites are fine for learning the ropes, but when its time to start working on a &#8216;real&#8217; project, you don&#8217;t want a lot of dummy data that needs to be cleaned out. Using Rails&#8217; 2.3 application template feature, we have a blank template (templates/blank.rb) which will create a more stripped down version of site. BrowserCMS projects are started like any other Rails project, using an application generator template, which is hosted on github.</p>
-<p>Assuming you want to use MySQL as the database. Run the following:</p>
-<div class="code_container"><code class="html">$ cd ~/projects
-$ rails my_new_project_name -d mysql -m http://browsercms.org/templates/blank.rb
-$ cd my_new_project_name
+<p>Demo sites are fine for learning the ropes, but when its time to start working on a &#8216;real&#8217; project, you don&#8217;t want a lot
+of dummy data that needs to be cleaned out. To start a typical, &#8216;blank&#8217; project, you can run the following command. Here
+we will specify the -d flag, which will use MySQL as the database.</p>
+<p>Run the following:</p>
+<div class="code_container"><code class="html">$ browsercms project_name -d mysql
+$ cd project_name
 $ script/server</code></div>
-<p>This is going to create the development and testing copies of the database, migrate the db, populate it with the bare minimum content it needs, and copy all of the necessary files from the gem into the rails project. Open your browser to <a href="http://localhost:3000/cms">http://localhost:3000/cms</a> to log in, using cmsadmin/cmsadmin as the username/password.</p>
+<p>You need to have the mysql gem installed for this to work. This is going to create the development and testing copies of
+the database, migrate the db, populate it with the bare minimum content it needs, and copy all of the necessary files
+from the gem into the rails project. Open your browser to <a href="http://localhost:3000/cms">http://localhost:3000/cms</a> to log in,
+using cmsadmin/cmsadmin as the username/password.</p>
+<h3 id="the-short-command">4 The short command</h3>
+<p>There is a shorter version of the command line script, which works identically to the longer form detailed above.</p>
+<div class="code_container"><code class="html">$ bcms project_name -d mysql</code></div>
+<p>No difference in functionality, just less to type.</p>
+<h3 id="getting-command-line-help">5 Getting Command line Help</h3>
+<p>You can get assistance from the commandline tool by running <tt>browsercms</tt> with no arguments, like so:</p>
+<div class="code_container"><code class="html">$ browsercms</code></div>
+<p>This will show common usages, as well as all the help options available. The <tt>browsercms</tt> command piggybacks on top of the
+<tt>rails</tt> command, so many of the options available are the same as <tt>rails</tt>, including <tt>-f</tt> or <tt>--force</tt>.</p>
+<h3 id="trouble-shooting">6 Trouble Shooting</h3>
+<p>This section covers some potential problems you might run into when trying to create a BrowserCMS project.</p>
+<h4 id="creation-fails-to-create-mysql-database">6.1 Creation fails to create MySQL Database</h4>
+<p>BrowserCMS will attempt to create and populate the database. When running against mysql, Rails will assume you have a username called <tt>root</tt> with an empty password.
+The database create/migrations will fail if you don&#8217;t have that username/password set. If this occurs, you can update the config/database.yml with correct username/password
+ and rerun the <tt>bcms</tt> command which will regenerate the entire project.</p>
+Choose &#8216;n&#8217; (No) when it prompts you to overwrite the config/database.yml and then &#8216;a&#8217; (Overwrite all) for all files after that.
+This should complete the project generation using the new username/password.
+<h3 id="deploying-to-production">7 Deploying to production</h3>
+<p>Once you get ready to start deploying your application into production environments, be sure to review the <a href="deployment_guide.html">Deployment Guide</a>.
+There are several &#8216;gotchas&#8217; to be aware of that may differ from deploying other Rails applications.</p>
                 </td>
               </tr>
             </table>

data/doc/guides/html/images/content_blocks/add_field_to_form.png ADDED

Binary file

data/doc/guides/html/images/content_blocks/add_second_block.png ADDED

Binary file

data/doc/guides/html/images/nfl_sitemap.png ADDED

Binary file

data/doc/guides/html/index.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,32 +135,33 @@
                         <div id="subCol">
         <h3 class="chapter"><img src="images/chapters_icon.gif" alt="" />Chapters</h3>
         <ol class="chapters">
-<li><a href="#guides">Guides</a><ul><li><a href="#getting-startedgetting-startedhtml"><a href="getting_started.html">Getting Started</a></a></li><li><a href="#users-guideuser-guidehtml"><a href="user_guide.html">User&#8217;s Guide</a></a></li><li><a href="#installing-a-moduleinstalling-moduleshtml"><a href="installing_modules.html">Installing a Module</a></a></li><li><a href="#developer-guidedeveloper-guidehtml"><a href="developer_guide.html">Developer Guide</a></a></li><li><a href="#designers-guidedesigner-guidehtml"><a href="designer_guide.html">Designer&#8217;s Guide</a></a></li><li><a href="#deployment-guidedeployment-guidehtml"><a href="deployment_guide.html">Deployment Guide</a></a></li><li><a href="#building-on-the-edgebuild-it-yourselfhtml"><a href="build_it_yourself.html">Building on the Edge</a></a></li></ul></li></ol></div>
+<li><a href="#getting-started">Getting Started</a><ul><li><a href="#getting-started-with-browsercmsgetting-startedhtml"><a href="getting_started.html">Getting Started with BrowserCMS</a></a></li></ul></li><li><a href="#using-browsercms">Using BrowserCMS</a><ul><li><a href="#interface-guideuser-guidehtml"><a href="user_guide.html">Interface Guide</a></a></li></ul></li><li><a href="#installation--deployment">Installation / Deployment</a><ul><li><a href="#installing-a-moduleinstalling-moduleshtml"><a href="installing_modules.html">Installing a Module</a></a></li><li><a href="#deployment-guidedeployment-guidehtml"><a href="deployment_guide.html">Deployment Guide</a></a></li></ul></li><li><a href="#developing-on-browsercms">Developing on BrowserCMS</a><ul><li><a href="#content-blockscontent-blockshtml"><a href="content_blocks.html">Content Blocks</a></a></li><li><a href="#portletsportletshtml"><a href="portlets.html">Portlets</a></a></li><li><a href="#building-templatesbuilding-templateshtml"><a href="building_templates.html">Building Templates</a></a></li><li><a href="#building-modulesbuilding-moduleshtml"><a href="building_modules.html">Building Modules</a></a></li><li><a href="#building-on-the-edgebuild-it-yourselfhtml"><a href="build_it_yourself.html">Building on the Edge</a></a></li></ul></li></ol></div>
                 </td>
                 <td class="guides">
                   <h2>BrowserCMS Reference Documentation</h2>
-<p>BrowserCMS is a general purpose, open source Web Content Management System (<span class="caps">CMS</span>), written in Ruby on Rails. It is designed to support three distinct groups of people:</p>
-<ol>
-	<li>Non-technical web editors who want a humane system to manage their site, without needing to understand what <span class="caps">HTML</span> or even Rails is.</li>
-	<li>Designers who want to create large and elegantly designed websites with no artificial constraints by the <span class="caps">CMS</span>.</li>
-	<li>Developers who want to add a <span class="caps">CMS</span> into their Rails projects, or create <span class="caps">CMS</span> driven websites for their clients.</li>
-</ol>
-<p>This guide is for BrowserCMS v3.0.1.</p>
-                  <h3 id="guides">1 Guides</h3>
-<p>Below are a list of guides on how the above groups can use BrowswerCMS, to design, build and maintain websites.</p>
-<h4 id="getting-startedgetting-startedhtml">1.1 <a href="getting_started.html">Getting Started</a></h4>
-<p>The easy way to install BrowserCMS and create a project with it.</p>
-<h4 id="users-guideuser-guidehtml">1.2 <a href="user_guide.html">User&#8217;s Guide</a></h4>
-<p>How to use the basic features of BrowserCMS.</p>
-<h4 id="installing-a-moduleinstalling-moduleshtml">1.3 <a href="installing_modules.html">Installing a Module</a></h4>
+<p>These guides are designed to provide details on how to work with BrowserCMS, and to assist in understanding how different parts of the <span class="caps">CMS</span> work together. As a Web Content Management system, there are two general pieces to understand; how to use the <span class="caps">CMS</span> interface to build websites and how to extend/deploy BrowserCMS websites.</p>
+<p>These guides are for BrowserCMS v3.1.0.</p>
+                  <h3 id="getting-started">1 Getting Started</h3>
+<h4 id="getting-started-with-browsercmsgetting-startedhtml">1.1 <a href="getting_started.html">Getting Started with BrowserCMS</a></h4>
+<p>Everything you need to know to install BrowserCMS and create your first website.</p>
+<h3 id="using-browsercms">2 Using BrowserCMS</h3>
+<h4 id="interface-guideuser-guidehtml">2.1 <a href="user_guide.html">Interface Guide</a></h4>
+<p>Designed as an overview of the BrowserCMS interface for Cms editors and site builders.</p>
+<h3 id="installation--deployment">3 Installation / Deployment</h3>
+<h4 id="installing-a-moduleinstalling-moduleshtml">3.1 <a href="installing_modules.html">Installing a Module</a></h4>
 <p>How to add a module to your BrowserCMS project.</p>
-<h4 id="developer-guidedeveloper-guidehtml">1.4 <a href="developer_guide.html">Developer Guide</a></h4>
-<p>How to customize and extend a BrowserCMS site to add dynamic behavior and content.</p>
-<h4 id="designers-guidedesigner-guidehtml">1.5 <a href="designer_guide.html">Designer&#8217;s Guide</a></h4>
-<p>How to turn a design into a styled website, by building templates. (Incomplete)</p>
-<h4 id="deployment-guidedeployment-guidehtml">1.6 <a href="deployment_guide.html">Deployment Guide</a></h4>
+<h4 id="deployment-guidedeployment-guidehtml">3.2 <a href="deployment_guide.html">Deployment Guide</a></h4>
 <p>How to configure Apache and Passenger to work with BrowserCMS in production mode.</p>
-<h4 id="building-on-the-edgebuild-it-yourselfhtml">1.7 <a href="build_it_yourself.html">Building on the Edge</a></h4>
+<h3 id="developing-on-browsercms">4 Developing on BrowserCMS</h3>
+<h4 id="content-blockscontent-blockshtml">4.1 <a href="content_blocks.html">Content Blocks</a></h4>
+<p>This guide covers how to create, customize and use Content Blocks.</p>
+<h4 id="portletsportletshtml">4.2 <a href="portlets.html">Portlets</a></h4>
+<p>This guide covers how to create and customize Portlets.</p>
+<h4 id="building-templatesbuilding-templateshtml">4.3 <a href="building_templates.html">Building Templates</a></h4>
+<p>This guide covers how to create and organize page templates which govern the design/theme of a website.</p>
+<h4 id="building-modulesbuilding-moduleshtml">4.4 <a href="building_modules.html">Building Modules</a></h4>
+<p>This guide covers how to create new modules to be packaged and shared with other BrowserCMS developers. (In Progress)</p>
+<h4 id="building-on-the-edgebuild-it-yourselfhtml">4.5 <a href="build_it_yourself.html">Building on the Edge</a></h4>
 <p>For developers who want the very latest source code from Github and build the BrowserCMS gem themselves.</p>
                 </td>
               </tr>

data/doc/guides/html/installing_modules.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,7 +135,7 @@
                         <div id="subCol">
         <h3 class="chapter"><img src="images/chapters_icon.gif" alt="" />Chapters</h3>
         <ol class="chapters">
-<li><a href="#installation">Installation</a><ul><li><a href="#build-and-install-the-gem-from-source">Build and install the gem from source</a></li><li><a href="#adding-the-module-to-your-project">Adding the Module to your project</a></li></ul></li></ol></div>
+<li><a href="#overview">Overview</a><ul></ul></li><li><a href="#getting-the-module-from-gemcutter">Getting the module from Gemcutter</a><ul></ul></li><li><a href="#adding-the-module-to-your-project">Adding the Module to your project</a><ul><li><a href="#edit-the-configenvironmentrb-file">Edit the config/environment.rb file</a></li><li><a href="#edit-the-routesrb-file">Edit the routes.rb file</a></li><li><a href="#install-the-new-module-code">Install the new module code</a></li><li><a href="#run-migrations-and-start-the-server">Run migrations and start the server</a></li><li><a href="#adding-content">Adding Content</a></li></ul></li></ol></div>
                 </td>
                 <td class="guides">
                   <h2>How to Install a Module</h2>
@@ -139,33 +147,33 @@
 	<li>Running migrations</li>
 </ol>
 <p>Once you have done the above steps, you should have access to the Content blocks and portlets that each module provides, and you can add them to your pages.</p>
-                  <h3 id="installation">1 Installation</h3>
-<p>This module assumes you are going to be building the module from source code, and installing to a project locally to your computer. Let&#8217;s assume you want to install the News module, who&#8217;s project name (and gem name) is &#8216;bcms_news&#8217;. If you want to install other modules, just substitute the name of the module you want for &#8216;bcms_news&#8217;.</p>
-<h4 id="build-and-install-the-gem-from-source">1.1 Build and install the gem from source</h4>
-<p>This assumes you have the latest copy of the code from github on your machine, in a directory <tt>~/my_projects_dir/bcms_news_dir</tt>.</p>
-<div class="code_container"><code class="html">$ cd ~/my_projects_dir/bcms_news
-$ gem build bcms_news.gemspec
-$ sudo gem install bcms_news-1.0.0.gem</code></div>
+<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="overview">1 Overview</h3>
+<p>This module assumes you are going to be building installing module as gems. Let&#8217;s assume you want to install the News module, who&#8217;s project name (and gem name) is &#8216;bcms_news&#8217;. If you want to install other modules, just substitute the name of the module you want for &#8216;bcms_news&#8217;.</p>
+<p>Before installing a module, its worth reviewing the <tt>README</tt> file for the module. It may contain some specific instructions on how to install and use the module, in addition to the basic steps outlined here. The <tt>README</tt> file can be found as the landing page on the github repository for a module. For example, the <a href="http://github.com/browsermedia/bcms_page_comments">Page Comments</a> module has an overview of the module and its installation instructions.</p>
+<h3 id="getting-the-module-from-gemcutter">2 Getting the module from Gemcutter</h3>
+<p>For modules released as gems, they should be hosted on <a href="http://gemcutter.org">Gemcutter</a>. If you have a new enough version of <a href="http://docs.rubygems.org">RubyGems</a> you should be able to download gems via:</p>
+<div class="code_container"><code class="html">$ gem install bcms_news</code></div>
 <p>At this point, the News module gem should be installed as a gem on your system, and can be added to your projects.</p>
-<h4 id="adding-the-module-to-your-project">1.2 Adding the Module to your project</h4>
+<h3 id="adding-the-module-to-your-project">3 Adding the Module to your project</h3>
 <p>In your BrowserCMS application, do the following steps.</p>
-<h5 id="edit-the-confingenvironmentrb-file">1.2.1 Edit the confing/environment.rb file</h5>
-<div class="code_container"><code class="ruby">config.gem 'browsercms'
+<h4 id="edit-the-configenvironmentrb-file">3.1 Edit the config/environment.rb file</h4>
+<div class="code_container"><code class="ruby">config.gem 'browsercms', :version=&gt;&quot;3.1.0&quot;
 # Add this next line after the browsercms gem
-config.gem &quot;bcms_news&quot;</code></div>
-<h5 id="edit-the-routesrb-file">1.2.2 Edit the routes.rb file</h5>
+config.gem &quot;bcms_news&quot;, :version=&gt;&quot;1.0.0&quot;</code></div>
+<h4 id="edit-the-routesrb-file">3.2 Edit the routes.rb file</h4>
 <div class="code_container"><code class="ruby"># Add this route. It must be before the core browser_cms route.
 map.routes_for_bcms_news
 map.routes_for_browser_cms</code></div>
-<h5 id="install-the-new-module-code">1.2.3 Install the new module code</h5>
+<h4 id="install-the-new-module-code">3.3 Install the new module code</h4>
 <p>From the root directory of your cms project, run:</p>
 <div class="code_container"><code class="html">$ script/generate browser_cms</code></div>
 <p>This will copy all the necessary views and migrations from the gems into your local project. You should messages checking to see if files already exist or were created.</p>
-<h5 id="run-migrations-and-start-the-server">1.2.4 Run migrations and start the server</h5>
+<h4 id="run-migrations-and-start-the-server">3.4 Run migrations and start the server</h4>
 <p>Modules will often add new data types, like content blocks, so you need to run the migrations to add them to your project.</p>
 <div class="code_container"><code class="html">$ rake db:migrate
 $ script/server</code></div>
-<h5 id="add-new-content-to-your-site">1.2.5 Add New Content to your Site</h5>
+<h4 id="adding-content">3.5 Adding Content</h4>
 <p>Most modules will come with a few new types of content, either a new Content Block and one or more Portlets, which are designed to display those Content Blocks in interesting ways. To discover what new contents have been added, you can look at the Content Library for a new group (like &#8216;News&#8217;) or add a new Portlet, which will list all available portlets in the system.</p>
                 </td>
               </tr>