RevSpark — A minimalist web framework for LiveCode Server

Introduction

revSpark is a minimalist web library for RevServer. It was inspired by Ruby Sinatra library. It is a single include file and provides some basic features that make writing a web application in RevServer quite easy.

Installation

Just drop revSpark.inc where you want to build your application. Optionally but highly recommended, use a .htaccess file to rewrite all requests to your application, for this is how revSpark shine.

Hello World Example

hello.irev:
<?rev
include "revspark.inc"

if match_get("/") then
put "Hello World!"
end if
?>
.htaccess:
RewriteEngine on
RewriteBase /
RewriteCond $1 !^(hello\.irev)
RewriteRule ^(.*)$ hello.irev?/$1 [L]
Now, if you try to access this file such as http://andregarzia.com/revspark/demo/helloworld you'll see "Hello World!". Okay, this was easy, let us spicy it up, lets change hello.irev.

hello.irev:
<?rev
include "revspark.inc"

if match_get("/") or match_get("/hello") then
put "Hello World!"
end if

if match_get("/hi") then
put "Hi There!"
end if
?>

Check out these three urls now:


See how it is matching the GET requests with those if clauses, this is called routing. revSpark provides many functions to match HTTP methods and URLs. The URLs can have place holders, let me demo them:

<?rev
include "revspark.inc"

if match_get("/") or match_get("/hello") then
put "Hello World!"
end if

if match_get("/hello/:name") then
put "Hello," && para("name")
end if

if match_get("/hi") then
put "Hi There!"
end if
?>

Now access http://andregarzia.com/revspark/demo/helloworld/hello/Andre+Garzia and you'll see how it works. the :name in the url is matched and extracted, then you can access that place holder with the function para(). revSpark can match multiple place holders, such as:

<?rev
include "revspark.inc"

if match_get("/") or match_get("/hello") then
put "Hello World!"
end if

if match_get("/hello/:name") then
put "Hello," && para("name")
end if

if match_get("/sum/:num1/:num2") then
put "Hello," && para("num1") && "+" && para("num2") && "=" && para("num1") + para("num2")
end if

if match_get("/hi") then
put "Hi There!"
end if
?>

try it out http://andregarzia.com/revspark/demo/helloworld/sum/2/2 and you'll what I am talking about.

Typically, if you're building a RESTful service, you will work like this:

include "revspark.inc"

if match_get("/") then
... display something ...
end if

if match_post("/") then
... create something ...
end if

if match_put("/") then
... update something ...
end if

if match_delete("/") then
... delete something ...
end if

Just so you can see the source file for the demo, try http://andregarzia.com/revspark/demo/helloworld/source

Routes

Like in Sinatra, revSpark routes are a pair of a HTTP method and a URL Scheme. A requested URL will match if it uses the same method as the one being called in the function and if the URL Scheme maps well over the requested URL. URL Schemes

A simple URL Scheme: /hello will match:

  • /hello (Duh!)

A URL Scheme with a place holder: /hello/:name will match:

  • /hello/Andre
  • /hello/Lili
  • /hello/Mark
  • ...

A URL Scheme with multiple place holders: /contacts/:name/emails/:workemail will match:

  • /contacts/Obama/emails/spam@whitehouse.gov
  • /contacts/Donald+Duck/emails/donald@ducks.com
  • /contacts/Mr+Sandman/emails/sleepwell@morpheus.com
  • ...

You can then query any of the place holder with the function para() in the above example for the first URL:
para("name") would be Obama and para("workemail") would be spam@whitehouse.gov

Methods

  • match_get: matches a url with GET method
  • match_post: matches a url with POST method
  • match_put: matches a url with PUT method
  • match_delete: matches a url with DELETE method

Halting

In case you want to halt your application at any give time, the halt command is provided.

halt status code, message body, [header array]: interrupts web application with status code and message body and optional header array may be provided, every key of this array becomes an HTTP response header.

Example:
include "revspark.inc"

if match_get("/") then
...
put "text/plain" into tArrayA["Content-Type"]
put "blue" into tArrayA["x-favorite-color"]
halt 400, "Boom!", tArrayA
end if

Cookies

cookies()

The cookies() function returns an array with the HTTP cookies.

setCookie

setCookie key, value command sets a cookie named key with value

Sessions

revSpark provides minimal session handling. All sessions are stored in cookie variables so your session should not exceed 4k and since there's some encoding involved, the limit is below 4k actually.

session()

session(key) function will return a value for the given key.

session

command session key, value will set a session variable named key with a value value.

So what is the advantage of sessions over cookies? Well, sessions accept and return revTalk arrays if needed, so you can assemble your huge-but-below-4k multidimensional array and set it to a session.

Example:
include "revspark.inc"

if match_get("/hello/:name") then
session "name", para(name)
put "Hello," && para(name)
quit
end if

if match_get("/hello") then
if session("name") is not empty then
put "Hello," && session("name") && ", I remember you"
else
put "Hello World!"
end if
quit
end if

Redirect

You can redirect to new pages and websites with the redirect command. It works like: redirect [optional status code], destination.

Example:
include "revspark.inc"

if match_get("/yahoo") then
redirect "http://yahoo.com"
end if

if match_get("/google") then
redirect "http://google.com"
end if

Content Type

Just as a convenience, revSpark provides setContentType mimeType command to make it easier to set the Content-Type HTTP header.

Static Files & not_found()

If you se the .htaccess file to redirect all call to your .irev file, then, how will you serve static files? No problem, upon inclusion, revSpark checks if you're actually trying to access a live real file with that url, if so, it will output the file instead of executing the code.

You can circumvent this with better .htaccess code however, which is best anyway. This is provided as a convenience.

The functions not_found() with return true or false depending on the fact that the file on the REQUEST_URI is real or not, you can use that to make your own 404 errors.

Example:
include "revspark.inc"

if not_found() then
halt 404, "not found."
end if

Mime Types

You can query any mime type for a given file with function mime(filepath). Be aware that this function uses shell() so, sanitize your input before trying.

Mail

revSpark comes with a mail function in the form of: mail (author of function: Michael McCreary)

Emails the given message to the recipients specified. Each address passed can have a name attached in the form "name <address>". Addresses can be passed as comma separated lists. Attachements can be added by passing an array (interger indexed or otherwise). with each attachment itself being an array.

  • pTo - The addresses to send the message to
  • pSub - The message subject
  • pMsg - The message body
  • pFrom - The address of the message sender
  • pCc - Any cc addresses
  • pBcc - Any Bcc addresses
  • pHtml - Boolean, if the message is to be sent as html
    • pAtts - Array of all attachments to send, each attachment of the form:
    • name: the name of the attachment
    • path: the absolute path to the attachment
    • type: the mime type of the attachment, defaults to application/octet-stream

revSpark & revIgniter

The objective of revSpark is not to replace revIgniter which IMHO is the best library ever! revIgniter is like Rails where revSpark is like Sinatra. Where with revIgniter you have loads of features and organization, with revSpark you have a minimal set and freedom (to screw up).

revIgniter is more suitable for big projects. If you're building a big web service, revIgniter will suit you better, if you're just building a quick tool, then revSpark might just be what you need. For example, if you're going to build a Forum, you should consider revIgniter, now, if you just want to build a tool to track your own ToDo list, revSpark might be good for you.

revSpark doesn't provide form validators, views, controllers, models, database connections, templating system, error reporting... for all those needs, check out revIgniter because if you go and try to bolt all bells and whistles in revSpark you will end up duplicating Ralfs work anyway.

revIgniter home page: http://revigniter.com

License

revSpark is distributed under the terms of BSD License and is FREE for use for both commercial and personal use. Modifications and ReWorks are welcome as long as you don't sue me for any reason, I cannot be held liable for anything and this library is provided as is yada yada yada! (Hate licenses and software politics, this is free, no guarantee, don't sue!)

Donations

If you feel like contributing, my PayPal account is agarzia@mac.com (Thanks!)

Have fun!

Download: RevSpark is offered thru BitBucket Mercurial repositories. Use the link in the side menu to go to the repository or click here to download an up to date copy.