website_builder_engine

h1. Website Builder Engine

Add this Rails 3.1 engine to any Rails 3.1 application and generate static HTML5 web pages. It creates a simple website suitable for a typical Internet marketing campaign, with a home page, a template page for an offer (for example, to sell a product or capture an email address), plus template pages for related articles.

Any issues? Please create a "GitHub issue":https://github.com/DanielKehoe/website_builder_engine/issues.

h2. Intended Use

The goal of this project is to streamline the process of producing a simple web "microsite."

It is suitable for experienced Rails developers who want a speedy way to produce simple web sites.

h4. For Simple Microsites

Web developers often are asked to produce a simple site composed of a home page, a few articles (for search engine optimization), plus a landing page for a product or service offer.

h4. For Free Hosting on Heroku

This engine can be added to any simple Rails application and hosted on Heroku for free.

h4. Copy, Paste, and Publish

Text for the web pages is entered into simple forms, saved into a database, "poured" into well-structured templates, and published as static HTML5 web pages.

h4. Requires Textile for Content Markup

Textile markup is required for content. Requiring Textile imposes consistency. Textile is easy for a writer to format in a text editor. HTML can be copied from existing sites and will be saved in the database as Textile (eliminating any inconsistent or substandard HTML markup).

h4. Easily Customized Web Pages

After publishing, generated web pages are saved as well-structured, standard HTML5 files. The generated files can be downloaded, customized as needed, and hosted anywhere. It's easier to edit a well-formed HTML file than to create it from scratch.

h2. Other Approaches

Web developers can build a simple microsite in HTML/CSS with a text editor or WYSIWYG editor. Or they can use Wordpress. This Rails engine offers an alternative for Rails developers who don't want to write raw HTML from scratch or use Wordpress.

h4. Versus Writing HTML From Scratch

• It is tedious to build a site from scratch using HTML
• It can be difficult to find an example of well-structured, clean, current HTML5 to use as a template

h4. An Alternative to Wordpress

• The engine uses a templating language that is familar to Rails developers (ERB or Haml)
• Generated code is well-structured HTML5 and easy to edit for customization
• A site be hosted for free on Heroku
• Static HTML5 files offer a faster site response
• Website versions can be saved to GitHub for Git-based version control

h2. Dependencies

Before running this app, you will need:

• The Ruby language (version 1.9.2) ** @$ ruby -v@
• Rails 3.1 ** @$ rails -v@
• A working installation of "MongoDB":http://www.mongodb.org/ (version 1.6.0 or newer)

See "Installing Rails 3.1":http://railsapps.github.com/installing-rails-3-1.html and "Managing Rails Versions and Gems":http://railsapps.github.com/managing-rails-versions-gems.html for detailed instructions and advice.

h4. Installing MongoDB

If you don't have MongoDB installed on your computer, you'll need to install it and set it up to be always running on your computer (run at launch). On Mac OS X, the easiest way to install MongoDB is to install "Homebrew":http://mxcl.github.com/homebrew/ and then run the following:

brew install mongodb

Homebrew will provide post-installation instructions to get MongoDB running. The last line of the installation output shows you the MongoDB install location (for example, /usr/local/Cellar/mongodb/1.8.0-x86_64). You'll find the MongoDB configuration file there. After an installation using Homebrew, the default data directory will be /usr/local/var/mongodb.

h4. Your Parent Application

This gem provides an "app within an app" (a Rails engine). You must create your application and then add the Website Builder Engine to it. You may simply use the @rails new@ comand to create an application. For a full-featured and compatible starter app, I recommend creating an application using the application template supplied for the "RailsApps Rails3-Mongoid-Devise":https://github.com/RailsApps/rails3-mongoid-devise project. You can create a ready-to-use application with this command:

  $ rails new APP_NAME -m https://github.com/RailsApps/rails3-application-templates/raw/master/rails3-mongoid-devise-template.rb -T -O

Use the -T -O flags to skip Test::Unit files and Active Record files. See the "Rails3-Mongoid-Devise":https://github.com/RailsApps/rails3-mongoid-devise documentation for instructions.

h2. Gems

Add the Website Builder Engine gem to your application's Gemfile. You'll need several other gems as well.

gem "website_builder_engine"
gem "frontend-helpers"
gem 'RedCloth'
gem 'bourbon'
gem 'html2textile', :git => 'git://github.com/jystewart/html2textile.git'

If you intend to deploy to Heroku, add:

gem "thin", :group => :production
gem "heroku"

See an example "Rails 3.1 Gemfile":http://railsapps.github.com/rails-3-1-example-gemfile.html.

h2. Install the Required Gems

Install the required gems on your computer:

@$ bundle install@

You can check which gems are installed on your computer with:

@$ gem list --local@

Keep in mind that you have installed these gems locally. When you deploy the app to another server, the same gems (and versions) must be available.

h2. Mount the Engine

If you don't restrict access, anyone can change the generated web pages if they know the administrative interface's URL.

The examples below make the website-building administrative interface available at "http://localhost:3000/builder":http://localhost:3000/builder but you can provide any path you'd like.

h4. Without Authentication (Not Recommended)

Install the engine in your application by adding to your config/routes.rb file:

mount WebsiteBuilderEngine::Engine, :at => '/builder'

h4. With Authentication (Using Devise)

If you application is using Devise for authentication, it is easy to restrict access to the engine's administrative interface using routes-based authentication:

authenticate :user do
  mount WebsiteBuilderEngine::Engine, :at => '/builder'
end

If necessary, you can build your own routes-based authentication (but use Devise, it's easier).

h2. Add Stylesheet Files

This step should be implemented with a Rails generator. But it's not. So...

Copy the following files from the GitHub repository to the app/assets/stylesheets directory:

$ cd app/assets/stylesheets
$ curl -o articles.css.scss https://raw.github.com/DanielKehoe/website_builder_engine/master/app/assets/stylesheets/website_builder_engine/articles.css.scss
$ curl -o offerpages.css.scss https://github.com/DanielKehoe/website_builder_engine/blob/master/app/assets/stylesheets/website_builder_engine/offerpages.css.scss

h2. Initialize the Database

h4. Set Up a Database Seed File

If you are using Devise, you may want to set up a default user so you can easily log in to test the app. You may also want to add default data for the web pages you'll generate. You can see an example of a "default db/seeds.rb file":https://github.com/DanielKehoe/website_builder_engine/blob/master/db/seeds.rb.

h4. Seed the Database

Initialize the MongoDB database by running the command:

$ rake db:seed

h2. Test the App

You can check that your app runs properly by entering the command

$ rails server

To see the engine in action, open a browser window and navigate to "http://localhost:3000/builder":http://localhost:3000/builder.

h2. Usage

In its current form, the engine provides links to create "offer pages" and "articles".

For example, you can navigate to "http://localhost:3000/builder/articles/new":http://localhost:3000/builder/articles/new and enter data for a new article. Fields that are text areas can be populated with text in the "Textile":http://redcloth.org/textile/ markup format. Or you can enter HTML and the engine will downgrade it to Textile (useful if you are copying from an existing website).

After you save data for an article, you'll find a link you can use to "Publish" the article. Clicking "Publish" pours the data into an HTML5 template and saves the file as a static web page. After publishing, you can follow a link to the static web page to inspect the results.

Publishing any "article" page also generates a home page at "http://localhost:3000/index.html":http://localhost:3000/index.html.

h2. Customizing Web Pages

Published web pages are well-structured standard HTML5 files generated from template files that Rails can parse (either ERB or Haml templating languages).

h4. Modify a Stylesheet

You can modify the look and feel of the web pages by changing the corresponding CSS files:

• app/assets/stylesheets/articles.css.scss
• app/assets/stylesheets/offerpages.css.scss

h4. Modify a Template File

You change the structure of the files by overriding the engine's template files. Copy the originals from the GitHub repository:

$ curl -o app/views/website_builder_engine/templates/article.html.haml https://github.com/DanielKehoe/website_builder_engine/blob/master/app/views/website_builder_engine/templates/article.html.haml
$ curl -o app/views/website_builder_engine/templates/offerpage.html.haml https://github.com/DanielKehoe/website_builder_engine/blob/master/app/views/website_builder_engine/templates/offerpage.html.haml

Modify or replace the originals with templates of your own design.

h4. Create Additional Pages

In its current form, the engine only generates "offer pages" and "articles" (plus a home page). If you want other types of pages (for example, "about" or "contact"), you can fork the project. Make a pull request and I will add your additional pages to the gem.

You can use a forked vesion of the gem to publish pages locally. If you wish to deploy to Heroku, you'll need to publish (release) a new gem (or submit your contributions and I'll release a new version of this gem).

h2. Deploy to Heroku

For your convenience, here are "instructions for deploying your app to Heroku":http://railsapps.github.com/rails-heroku-tutorial.html. Heroku provides low cost, easily configured Rails application hosting.

h2. Issues

Please create an "issue on GitHub":https://github.com/DanielKehoe/website_builder_engine/issues if you identify any problems or have suggestions for improvements.

h2. Contributing

If you make improvements to this application, please share with others.

Send the author a message, create an "issue":https://github.com/DanielKehoe/website_builder_engine/issues, or fork the project and submit a pull request.

If you add functionality to this gem, create an alternative implementation, or release an gem that is similar, please contact me and I'll add a note to the README so that others can find your work.

h2. Credits

Daniel Kehoe ("http://danielkehoe.com/":http://danielkehoe.com/) implemented the gem.

Is the gem useful to you? Follow me on Twitter: "@rails_apps":http://twitter.com/rails_apps and tweet some praise. I'd love to know you were helped out by what I've put together.

h2. MIT License

Copyright 2011 Daniel Kehoe

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.