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.
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.
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.
This engine can be added to any simple Rails application and hosted on Heroku for free.
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.
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).
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.
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.
- 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
- 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
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 (version 1.6.0 or newer)
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 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.
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 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 documentation for instructions.
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.
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.
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 but you can provide any path you’d like.
Install the engine in your application by adding to your config/routes.rb file:
mount WebsiteBuilderEngine::Engine, :at => '/builder'
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).
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
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.
Initialize the MongoDB database by running the command:
$ rake db:seed
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.
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 and enter data for a new article. Fields that are text areas can be populated with text in the 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.
Published web pages are well-structured standard HTML5 files generated from template files that Rails can parse (either ERB or Haml templating languages).
You can modify the look and feel of the web pages by changing the corresponding CSS files:
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.
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).
For your convenience, here are instructions for deploying your app to Heroku. Heroku provides low cost, easily configured Rails application hosting.
Please create an issue on GitHub if you identify any problems or have suggestions for improvements.
If you make improvements to this application, please share with others.
Send the author a message, create an issue, 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.
Daniel Kehoe (http://danielkehoe.com/) implemented the gem.
Is the gem useful to you? Follow me on Twitter:
and tweet some praise. I’d love to know you were helped out by what I’ve put together.
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.