v1.1.0

If you've built something interesting with Vesper, let us know.

Take a sneak peek at the new plug and play Ruby web app framework.
Source (available in HD)

Installation

Set Up Your Dev Environment

Vesper includes almost everything required to write a web app, but first you have to set up your dev environment. Here's what you'll need to get started:

Git: http://git-scm.com/

Ruby 1.9.3 or above: http://www.ruby-lang.org/

Pro Tip: Using rbenv and ruby-build should make this simpler.

SQLite: http://www.sqlite.org/

You can use a different database (or none at all) - SQLite is just the default.

A text editor and web browser also help. I recommend TextMate and Safari.

Download the Gem

Now that you're all set up, installation should be simple.

You may need to sudo this.
~: gem install vesper

That's it! You're ready to start writing web apps with Vesper.

Basics

Create an App

~: vesper create app HelloWorld
~: cd HelloWorld
~/HelloWorld: rackup

View your new app at http://localhost:9292.

Control-C will stop the server.

So how does this work? At the core of every Vesper app is Sinatra, the Ruby DSL for quickly creating web applications with minimal effort.

application/hello_world.rb
4: get '/?' do
5:   erb :hello_world
6: end

This will render views/hello_world.html at the root url of your app.

Your application folder can be organized however you see fit. A single file, collection of libraries, or model & controller (and helper) subdirectories... it all just works.

Read more about Sinatra to see what all it can do.

Take a Look Around

.gitignore
Tell git which files to ignore. Learn more from The Git Community Book.
application/
Here's where you'll write the Ruby code for your app, including classes, routes and helpers. You can structure it as MVC, a collection of libraries, a single file, or any other way you see fit. Support for subdirectories is included.
config/
Add any sitewide and/or environment settings here. Separate from plugins, which have their own configuration. Again, support for subdirectories is included.
config.ru
Required by Rack servers to get things started.
data/
Created by the DataMapper plugin, this is where your SQLite databases will be created, along with scripts for seeding and transmogrifying data.
Gemfile
Used by Bundler, here's where you can specify which gems your app should use. It also handles loading gems required by plugins.
Gemfile.lock
Created by Bundler from your Gemfile, this ensures exact versioning of the required gems. Be sure to check this into version control.
plugins/
Plugins are shared, reusable, configurable mini apps that can be installed and modified to help with the legwork in creating your app. They can include their own application code, configuration, assets, tasks, hooks, and gems.
public/
Stylesheets, images, JavaScripts, and error pages. This is the only directory accessible from a browser.
Rakefile
Loads your app and your rake tasks from tasks/ into the command line.
Readme.md
Use this to give other people instructions on how to run, modify or just read your code. It uses Markdown formatting by default to make sure it renders well on GitHub.
tasks/
Drop your own Rake tasks in here and they'll be loaded, along with your app, from the command line.
Example: Loads the HelloWorld app into an IRB session.
~/HelloWorld: rake irb
tests/
Created by the MiniTest plugin, write your tests here and they'll be automatically loaded, along with your app, when you run the MiniTest command. ~/HelloWorld: rake minitest
tmp/
Temporary holding for uploaded files and downloaded plugins. Also includes restart.txt, which Rack can use to restart your app. ~/HelloWorld: touch tmp/restart.txt
views/
All your views should be created here. Ruby is embedded into .html and .erb files, layout.html is the default template, and subdirectories are supported.
Pro Tip: Check out the Mobile Request Router plugin for easy mobile designs.

Plugins

Plug and Play

Plugins are shared, reusable, configurable mini apps that can be installed and modified to help with the legwork in creating your app. They can include their own application code, configuration, assets, tasks, hooks, and gems.

Pro Tip: Plugins usually come with readme files to help you understand more about what the plugin does, if there are any prerequisites, what can be configured or modified, and any other plugin-specific info.
Pro Tip: Many plugins come with their own config files. These are meant to be modified. Do so.

Pre-installed Plugins

Vesper comes with a few plugins pre-installed to help get things moving.

Installing & Removing Plugins

To install a plugin, tell Vesper where to find it's git repo.

~/HelloWorld: vesper plugin install git@github.com:jarrodtaylor/logger.vpi.git

Now your plugin should be working as soon as you restart your app. Don't forget to read through any config and readme files.

If you decide you'd rather not use a plugin, removal is just as easy.

~/HelloWorld: vesper plugin remove logger.vpi

More Plugins

Creating Plugins

Anything you can do in an app, you can do with a plugin. Think of them as miniature apps. Start by creating an empty plugin.

~/HelloWorld: vesper plugin create my-great-plugin.vpi

You should now have the following files and folders to fill up with your code:

Not all plugins require all the default files and folders. You can delete anything you aren't using.
/application
Just like a full Vesper app, this where your plugin will do most of it's work. Classes, routes, subdirectories... they all go here.
/assets
If your plugin has any resources that need to be installed in the main app directory, put them here. The install plugin command will move them for you.
/config
Because plugins are more generalized than full Vesper apps, they often require some configuration. You can set that up here.
/tasks
Rake tasks in this folder will be loaded along with the rest of the main app's tasks.
Gemfile
Add any required gems here and Vesper will load them into the main app as part of the bundle command.
Readme.md
Use this to tell others what your plugin does, what needs to be configured and anything else they need to know.

Last, initialize your plugin folder as a git repo and upload it to a server. The repo link will be used to install your new plugin

Create an App Without Plugins

You can generate a new Vesper app with only the Core Extensions plugin by adding the -core option:

~: vesper create app HelloWorld -core

Plugin Recipes

Recipes let you create new Vesper apps with a custom set of plugins.

In your user or home directory, create a file called .vesper.rb with an array of your desired plugins.

Don't forget the . in front of the filename - it is a hidden file.
~/.vesper.rb
 1: @recipes = {
 2:   :dm_test => [
 3:     'git@github.com:jarrodtaylor/data-mapper.vpi.git',
 4:     'git@github.com:jarrodtaylor/mini-test.vpi.git'
 5:   ],
 6:   :mobile_markdown => [
 7:     'git@github.com:jarrodtaylor/markdown-parser.vpi.git',
 8:     'git@github.com:jarrodtaylor/mobile-request-router.vpi.git',
 9:     'git@github.com:jarrodtaylor/logger.vpi.git'
10:   ]
11: }

Now you can add the -recipe option when creating an app.

~: vesper create app HelloWorld -recipe mobile_markdown

Coming Soon

More detailed walkthroughs, more videos, deployment instructions, how it was made, and much more. Stay tuned.

Vesper was created by:
Jarrod Taylor Richard Rissanen