@@ -7,7 +7,7 @@ (define version "0.61") (define release-notes - '((p "Updated to work with PLT 4.1.5."))) + '((p "Updated to work with PLT 4.1.5.; improved body-as-url and corresponding documentation."))) (define primary-file "leftparen.scm") info.ss @@ -1,4 +1,4 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html><head><meta http-equiv="content-type" content="text-html; charset=utf-8" /><title>LeftParen 0.6 Documentation</title><link rel="stylesheet" type="text/css" href="scribble.css" title="default" /><script type="text/javascript" src="scribble-common.js"></script></head><body id="scribble-plt-scheme-org"><div class="tocset"><div class="tocview"><div class="tocviewlist" style="margin-bottom: 1em;"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">►</a></td><td></td><td><a href="/" class="tocviewselflink">Left Paren 0.6 Documentation</a></td></tr></table></div><div class="tocviewsublistonly" style="display: none;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="/#(part._.Installing_.Left.Paren)" class="tocviewlink">Installing Left Paren</a></td></tr><tr><td align="right">2 </td><td><a href="/#(part._tutorials)" class="tocviewlink">Tutorials</a></td></tr><tr><td align="right">3 </td><td><a href="/#(part._.Reference)" class="tocviewlink">Reference</a></td></tr><tr><td align="right">4 </td><td><a href="/#(part._.About_.Acknowledgements)" class="tocviewlink">About/ Acknowledgements</a></td></tr></table></div></div></div><div class="tocsub"><table class="tocsublist" cellspacing="0"><tr><td>1<tt> </tt><a href="#(part._.Installing_.Left.Paren)" class="tocsubseclink">Installing Left Paren</a></td></tr><tr><td>2<tt> </tt><a href="#(part._tutorials)" class="tocsubseclink">Tutorials</a></td></tr><tr><td>2.1<tt> </tt><a href="#(part._.Hello__.World)" class="tocsubseclink">Hello, World</a></td></tr><tr><td>2.2<tt> </tt><a href="#(part._.Blogerton_the_.Blog)" class="tocsubseclink">Blogerton the Blog</a></td></tr><tr><td>2.2.1<tt> </tt><a href="#(part._.Changes_to_app_scm)" class="tocsubseclink">Changes to app.scm</a></td></tr><tr><td>2.2.2<tt> </tt><a href="#(part._.Changes_to_main_scm)" class="tocsubseclink">Changes to main.scm</a></td></tr><tr><td>2.2.3<tt> </tt><a href="#(part._.Launch_.Blogerton)" class="tocsubseclink">Launch Blogerton</a></td></tr><tr><td>3<tt> </tt><a href="#(part._.Reference)" class="tocsubseclink">Reference</a></td></tr><tr><td>3.1<tt> </tt><a href="#(part._.Forms)" class="tocsubseclink">Forms</a></td></tr><tr><td>3.1.1<tt> </tt><a href="#(part._.Image_uploads)" class="tocsubseclink">Image uploads</a></td></tr><tr><td>3.2<tt> </tt><a href="#(part._.Sessions)" class="tocsubseclink">Sessions</a></td></tr><tr><td>3.2.1<tt> </tt><a href="#(part._.Creating_sessions)" class="tocsubseclink">Creating sessions</a></td></tr><tr><td>3.2.2<tt> </tt><a href="#(part._.Accessing_sessions)" class="tocsubseclink">Accessing sessions</a></td></tr><tr><td>3.3<tt> </tt><a href="#(part._.Users)" class="tocsubseclink">Users</a></td></tr><tr><td>3.4<tt> </tt><a href="#(part._.Feeds)" class="tocsubseclink">Feeds</a></td></tr><tr><td>4<tt> </tt><a href="#(part._.About_.Acknowledgements)" class="tocsubseclink">About/ Acknowledgements</a></td></tr><tr><td>4.1<tt> </tt><a href="#(part._.Code_.Contributors)" class="tocsubseclink">Code Contributors</a></td></tr></table></div></div><div class="maincolumn"><div class="main"><div class="versionbox">Version: 4.1.5</div><h2><a name="(part._.Left.Paren_0_6_.Documentation)"></a>LeftParen 0.6 Documentation</h2>Website: <a href="http://leftparen.com">http://leftparen.com</a>LeftParen is a framework for quickly creating web apps. It runs on +<html><head><meta http-equiv="content-type" content="text-html; charset=utf-8" /><title>LeftParen 0.61 Documentation</title><link rel="stylesheet" type="text/css" href="scribble.css" title="default" /><script type="text/javascript" src="scribble-common.js"></script></head><body id="scribble-plt-scheme-org"><div class="tocset"><div class="tocview"><div class="tocviewlist" style="margin-bottom: 1em;"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">►</a></td><td></td><td><a href="/" class="tocviewselflink">Left Paren 0.61 Documentation</a></td></tr></table></div><div class="tocviewsublistonly" style="display: none;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="/#(part._.Installing_.Left.Paren)" class="tocviewlink">Installing Left Paren</a></td></tr><tr><td align="right">2 </td><td><a href="/#(part._tutorials)" class="tocviewlink">Tutorials</a></td></tr><tr><td align="right">3 </td><td><a href="/#(part._.Reference)" class="tocviewlink">Reference</a></td></tr><tr><td align="right">4 </td><td><a href="/#(part._utilities)" class="tocviewlink">Utility Functions</a></td></tr><tr><td align="right">5 </td><td><a href="/#(part._.About_.Acknowledgements)" class="tocviewlink">About/ Acknowledgements</a></td></tr></table></div></div></div><div class="tocsub"><table class="tocsublist" cellspacing="0"><tr><td>1<tt> </tt><a href="#(part._.Installing_.Left.Paren)" class="tocsubseclink">Installing Left Paren</a></td></tr><tr><td>2<tt> </tt><a href="#(part._tutorials)" class="tocsubseclink">Tutorials</a></td></tr><tr><td>2.1<tt> </tt><a href="#(part._.Hello__.World)" class="tocsubseclink">Hello, World</a></td></tr><tr><td>2.2<tt> </tt><a href="#(part._.Blogerton_the_.Blog)" class="tocsubseclink">Blogerton the Blog</a></td></tr><tr><td>2.2.1<tt> </tt><a href="#(part._.Changes_to_app_scm)" class="tocsubseclink">Changes to app.scm</a></td></tr><tr><td>2.2.2<tt> </tt><a href="#(part._.Changes_to_main_scm)" class="tocsubseclink">Changes to main.scm</a></td></tr><tr><td>2.2.3<tt> </tt><a href="#(part._.Launch_.Blogerton)" class="tocsubseclink">Launch Blogerton</a></td></tr><tr><td>3<tt> </tt><a href="#(part._.Reference)" class="tocsubseclink">Reference</a></td></tr><tr><td>3.1<tt> </tt><a href="#(part._.Forms)" class="tocsubseclink">Forms</a></td></tr><tr><td>3.1.1<tt> </tt><a href="#(part._.Image_uploads)" class="tocsubseclink">Image uploads</a></td></tr><tr><td>3.2<tt> </tt><a href="#(part._.Sessions)" class="tocsubseclink">Sessions</a></td></tr><tr><td>3.2.1<tt> </tt><a href="#(part._.Creating_sessions)" class="tocsubseclink">Creating sessions</a></td></tr><tr><td>3.2.2<tt> </tt><a href="#(part._.Accessing_sessions)" class="tocsubseclink">Accessing sessions</a></td></tr><tr><td>3.3<tt> </tt><a href="#(part._.Storing_closures_in_.U.R.Ls)" class="tocsubseclink">Storing closures in URLs</a></td></tr><tr><td>3.4<tt> </tt><a href="#(part._.Users)" class="tocsubseclink">Users</a></td></tr><tr><td>3.5<tt> </tt><a href="#(part._.Feeds)" class="tocsubseclink">Feeds</a></td></tr><tr><td>4<tt> </tt><a href="#(part._utilities)" class="tocsubseclink">Utility Functions</a></td></tr><tr><td>5<tt> </tt><a href="#(part._.About_.Acknowledgements)" class="tocsubseclink">About/ Acknowledgements</a></td></tr><tr><td>5.1<tt> </tt><a href="#(part._.Code_.Contributors)" class="tocsubseclink">Code Contributors</a></td></tr></table></div></div><div class="maincolumn"><div class="main"><div class="versionbox">Version: 4.1.5</div><h2><a name="(part._.Left.Paren_0_61_.Documentation)"></a>LeftParen 0.61 Documentation</h2>Website: <a href="http://leftparen.com">http://leftparen.com</a>LeftParen is a framework for quickly creating web apps. It runs on PLT Scheme v4.1.5. LeftParen is released under an <a href="http://github.com/vegashacker/leftparen/tree/master/MIT-LICENSE.txt">MIT License</a>. The source is available on <a href="http://github.com/vegashacker/leftparen/tree/master">github</a>.<h3>1<tt> </tt><a name="(part._.Installing_.Left.Paren)"></a>Installing LeftParen</h3>You’ll need PLT Scheme v4.1.5 installed. More recent versions may work, but they are untested.Make sure that mzscheme is in your path. You should be ready -to go if you can do this:<table cellspacing="0"><tr><td>% mzscheme</td></tr><tr><td>Welcome to MzScheme v4.1.5...</td></tr><tr><td>></td></tr></table>Installing LeftParen is done automatically when you perform various <a href="http://planet.plt-scheme.org/">PLaneT</a> require commands. See <a href="/#(part._tutorials)">Tutorials</a> for examples of this. On my system, starting a LeftParen web app for the first time (with a freshly installed version of PLT Scheme), takes about an hour. (The time is spent downloading and installing a bunch of files into your local PLaneT repository.)At any point, if you see an error like<table cellspacing="0"><tr><td>make-directory: cannot make directory: /home/rob/.plt-scheme/planet/300/4.1.5 (Permission denied; errno=13)</td></tr></table>try re-running the command with sudo (you won’t need to do this everytime–just the once).<h3>2<tt> </tt><a name="(part._tutorials)"></a>Tutorials</h3><h4>2.1<tt> </tt><a name="(part._.Hello__.World)"></a>Hello, World</h4>We’re going to make a project called hello-world. Change to the directory that you’d like to create the project in. Then issue<table cellspacing="0"><tr><td>% mzscheme -e '(require (planet vegashacker/leftparen:5:=0/generate))' hello-world</td></tr></table>This will create a hello-world project directory for you. In this directory you’ll find the script directory, which contains some useful scripts. All paths are relative to this project directory, so when calling scripts, you always want to be at the project root.<table cellspacing="0"><tr><td>% cd hello-world</td></tr></table>We need to make the scripts executable:<table cellspacing="0"><tr><td>% chmod u+x script/server</td></tr></table>LeftParen has automatically generated everything we need to run our web app – we just need to start the server (again, you should be at the project root directory):<table cellspacing="0"><tr><td>% ./script/server</td></tr><tr><td>Populating caches...</td></tr><tr><td>Done populating cache.</td></tr><tr><td>Server is ready at http://localhost:8765/ (ctrl-c to stop it).</td></tr></table>Point your browser to <a href="http://localhost:8765">http://localhost:8765</a> and you should see a familiar greeting:Hello, World!<h4>2.2<tt> </tt><a name="(part._.Blogerton_the_.Blog)"></a>Blogerton the Blog</h4>Now let’s try implementing the true "hello world" of web apps – a blog. First, execute the following commands from the directory in which you want to create your project:<table cellspacing="0"><tr><td>% mzscheme -e '(require (planet vegashacker/leftparen:5:=0/generate))' blogerton</td></tr><tr><td>% cd blogerton</td></tr><tr><td>% chmod u+x script/server</td></tr></table><h5>2.2.1<tt> </tt><a name="(part._.Changes_to_app_scm)"></a>Changes to app.scm</h5>We need to register a couple of pages in our app. The index-page was already set up for you, but you’ll need to add a page to create new posts, and one to view them. Make the define-app call look like this:<table cellspacing="0" class="schemeblock"><tr><td>  (define-app my-app</td></tr><tr><td>    (index-page (url "/"))</td></tr><tr><td>    (create-post-page (url "/post"))</td></tr><tr><td>    (view-post-page (url "/view/" (string-arg))))</td></tr></table><h5>2.2.2<tt> </tt><a name="(part._.Changes_to_main_scm)"></a>Changes to main.scm</h5>Now we need to define those pages that we declared in app.scm.<table cellspacing="0" class="schemeblock"><tr><td>  (define-page (index-page req)</td></tr><tr><td>    (** `(h1 "Blogerton")</td></tr><tr><td>        `(p ,(web-link "Create a new post" (page-url create-post-page)))</td></tr><tr><td>        `(ul ,@(map (lambda (p) `(li ,(paint-blog-post p)))</td></tr><tr><td>                    (load-where '((type . blog-post))</td></tr><tr><td>                                #:sort-by 'created-at #:compare >)))))</td></tr><tr><td>  </td></tr><tr><td>  (define-page (create-post-page req)</td></tr><tr><td>    (form '((title "Title" text) (body "Body" long-text))</td></tr><tr><td>          #:init '((type . blog-post))</td></tr><tr><td>          #:on-done (lambda (post) (redirect-to-page view-post-page (rec-id post)))))</td></tr><tr><td>  </td></tr><tr><td>  (define-page (view-post-page req post-id)</td></tr><tr><td>    (paint-blog-post (load-rec post-id #:ensure '((type . blog-post)))))</td></tr><tr><td>  </td></tr><tr><td>  (define (paint-blog-post post)</td></tr><tr><td>    `(div (h2 ,(rec-prop post 'title))</td></tr><tr><td>          (p ,(rec-prop post 'body))))</td></tr></table><h5>2.2.3<tt> </tt><a name="(part._.Launch_.Blogerton)"></a>Launch Blogerton</h5>You’re ready for launch. Start the server with<table cellspacing="0"><tr><td>% ./script/server</td></tr></table>and you should have a basic blogging app, with persistent data, in 19 lines of code.<h3>3<tt> </tt><a name="(part._.Reference)"></a>Reference</h3><h4>3.1<tt> </tt><a name="(part._.Forms)"></a>Forms</h4>Most web applications make some use of web forms. The form function lets easily you get and process input from your users.<table cellspacing="0" class="boxed"><tr><td>(form field-specs) → xexpr?</td></tr><tr><td>  field-specs : (listof field-spec?)</td></tr></table><table cellspacing="0" class="boxed"><tr><td>field-spec? : (list symbol? string? field-type?)</td></tr></table><table cellspacing="0" class="boxed"><tr><td><table cellspacing="0" class="argcontract"><tr><td>field-type? : </td><td><table cellspacing="0" class="schemeblock"><tr><td>(or/c 'text 'long-text 'number 'password 'image 'checkbox</td></tr><tr><td>      'radio 'drop-down)</td></tr></table></td></tr></table></td></tr></table>You create a form by listing, in order, "field specifications". For example, you might want a title field, followed by a description text box, followed by a photo upload field. Note that the many keyword arguments available to the form function aren’t documented yet.Each field spec is of the form (field-name label field-type). For example, you create a title field, you might use the spec (title "Enter a title" text). The entire example metioned above might look like this:<table cellspacing="0" class="schemeblock"><tr><td>  (form '((title "Title" text)</td></tr><tr><td>          (description "Description" long-text)</td></tr><tr><td>          (photo "Your photo" image)))</td></tr></table><h5>3.1.1<tt> </tt><a name="(part._.Image_uploads)"></a>Image uploads</h5>By default, uploaded images are stored in the uploaded-files directory in your project directory. You can customize this with the *PATH_TO_UPLOADED_FILES* setting. When images are saved, their original filenames are used with a 5-character code pre-pended to make filenames unique.<h4>3.2<tt> </tt><a name="(part._.Sessions)"></a>Sessions</h4>A session is an object that allows you to easily store state about individual visitors to your web app. Sessions are stored on the server as a record with a virtually impossible-to-guess id. A cookie is left in the user’s web browser, which contains a pointer to a particular session id. These cookies expire one month after creation and, currently, this can’t be changed.<h5>3.2.1<tt> </tt><a name="(part._.Creating_sessions)"></a>Creating sessions</h5><table cellspacing="0" class="boxed"><tr><td><table cellspacing="0" class="schemeblock"><tr><td>(define-session-page</td></tr><tr><td>  (page-name request-iden session-iden page-args ...)</td></tr><tr><td>  body ...)</td></tr></table></td></tr></table>This is an alternate to define-page, most commonly used in main.scm. The only difference is that after the request identifier, you must provide a session identifier. For example, to keep a counter (unique to each user), you could write:<table cellspacing="0" class="schemeblock"><tr><td>  (define-session-page (foo-page req sesh)</td></tr><tr><td>    (let ((c (session-get-val sesh 'counter 0)))</td></tr><tr><td>      (session-put-val! sesh 'counter (+ 1 c))</td></tr><tr><td>      (number->string c)))</td></tr></table>When you define a session page, the session is automatically fetched for you (and created if necessary), and bound to the session identifier you provided.<h5>3.2.2<tt> </tt><a name="(part._.Accessing_sessions)"></a>Accessing sessions</h5><table cellspacing="0" class="boxed"><tr><td>(session-get-val session key [missing-val]) → any</td></tr><tr><td>  session : session</td></tr><tr><td>  key : symbol</td></tr><tr><td>  missing-val : any = #f</td></tr></table><table cellspacing="0" class="boxed"><tr><td>(session-put-val! session key val) → session</td></tr><tr><td>  session : session</td></tr><tr><td>  key : symbol</td></tr><tr><td>  val : any</td></tr></table><h4>3.3<tt> </tt><a name="(part._.Users)"></a>Users</h4>LeftParen provides built-in functionality for dealing with users, including registering users, logging users in and out, and storing persistent data about users. To get up-and-running quickly, you can use the high-level welcome-message function:<table cellspacing="0" class="boxed"><tr><td><table cellspacing="0" class="prototype"><tr><td>(welcome-message</td><td> </td><td>session</td><td> </td><td> </td><td> </td><td> </td></tr><tr><td> </td><td> [</td><td>#:on-success success-fn</td><td> </td><td> </td><td> </td><td> </td></tr><tr><td> </td><td> </td><td>#:no-register no-register])</td><td> </td><td>→</td><td> </td><td>xexpr</td></tr></table></td></tr><tr><td>  session : session?</td></tr><tr><td>  success-fn : (or/c (-> user? xexpr?) #f) = #f</td></tr><tr><td>  no-register : boolean? = #f</td></tr></table>The function welcome-message produces a small area of text and links (commonly found in the top-right area of a web app). If the user is not currently logged in, login and register links are presented. If the user is logged in, a message welcoming them is displayed, along with a link to log out.<table cellspacing="0" class="boxed"><tr><td>(current-user session) → (or/c user? #f)</td></tr><tr><td>  session : session?</td></tr></table>The function current-user returns the current user record, or #f if no user is available in the current session.As an example, here is the complete page code for a web app that allows users to register, login and logout, and which prints a secret message if the user is logged in:<table cellspacing="0" class="schemeblock"><tr><td>  (define-session-page (index-page req sesh)</td></tr><tr><td>    (** (welcome-message sesh)</td></tr><tr><td>        (aif (current-user sesh)</td></tr><tr><td>             (format "The secret, ~A, is 42." (rec-prop it 'username))</td></tr><tr><td>             "No secret for you.")))</td></tr></table><h4>3.4<tt> </tt><a name="(part._.Feeds)"></a>Feeds</h4>You can create Atom or RSS feeds in your web app. A feed in LeftParen is just a page crafted in a paricular way. The core functions involved are atom-feed and rss-feed:<table cellspacing="0" class="boxed"><tr><td><table cellspacing="0" class="prototype"><tr><td>(atom-feed</td><td> </td><td>atom-feed-page</td><td> </td></tr><tr><td> </td><td> </td><td>#:feed-title feed-title</td><td> </td></tr><tr><td> </td><td> </td><td>#:feed-updated/epoch-seconds updated-seconds</td><td> </td></tr><tr><td> </td><td> </td><td>#:author-name author-name</td><td> </td></tr><tr><td> </td><td> [</td><td>#:feed-description feed-description</td><td> </td></tr><tr><td> </td><td> </td><td>#:feed-id feed-id</td><td> </td></tr><tr><td> </td><td> </td><td>#:related-content-link related-content-link</td><td> </td></tr><tr><td> </td><td> </td><td>#:items atom-items])</td><td> </td></tr></table></td></tr><tr><td> → response/full?</td></tr><tr><td>  atom-feed-page : page?</td></tr><tr><td>  feed-title : string?</td></tr><tr><td>  updated-seconds : integer?</td></tr><tr><td>  author-name : string?</td></tr><tr><td>  feed-description : (or/c #f string?) = #f</td></tr><tr><td>  feed-id : string? = THE_URL_OF_THE_GIVEN_ATOM_FEED_PAGE</td></tr><tr><td>  related-content-link : string? = THE_LINK_TO_YOUR_WEB_APP</td></tr><tr><td>  atom-items : (list-of atom-item?) = '()</td></tr></table><table cellspacing="0" class="boxed"><tr><td><table cellspacing="0" class="prototype"><tr><td>(rss-feed</td><td> </td><td>rss-feed-page</td><td> </td></tr><tr><td> </td><td> </td><td>#:feed-title feed-title</td><td> </td></tr><tr><td> </td><td> </td><td>#:feed-description feed-description</td><td> </td></tr><tr><td> </td><td> [</td><td>#:related-content-link related-content-link</td><td> </td></tr><tr><td> </td><td> </td><td>#:items rss-items])</td><td> </td></tr></table></td></tr><tr><td> → response/full?</td></tr><tr><td>  rss-feed-page : page?</td></tr><tr><td>  feed-title : string?</td></tr><tr><td>  feed-description : string?</td></tr><tr><td>  related-content-link : string? = THE_LINK_TO_YOUR_WEB_APP</td></tr><tr><td>  rss-items : (list-of rss-item?) = '()</td></tr></table>The #:items argument in each of these functions is a list of items constructed with atom-item and rss-item:<table cellspacing="0" class="boxed"><tr><td><table cellspacing="0" class="prototype"><tr><td>(atom-item</td><td> </td><td>#:title title</td><td> </td></tr><tr><td> </td><td> </td><td>#:url url</td><td> </td></tr><tr><td> </td><td> </td><td>#:updated-epoch-seconds updated-seconds</td><td> </td></tr><tr><td> </td><td> [</td><td>#:content content])</td><td> </td></tr></table></td></tr><tr><td> → atom-item?</td></tr><tr><td>  title : string?</td></tr><tr><td>  url : string?</td></tr><tr><td>  updated-seconds : integer?</td></tr><tr><td>  content : (or/c #f string?) = #f</td></tr></table><table cellspacing="0" class="boxed"><tr><td><table cellspacing="0" class="prototype"><tr><td>(rss-item</td><td> </td><td>#:title title</td><td> </td><td> </td><td> </td><td> </td></tr><tr><td> </td><td> </td><td>#:url url</td><td> </td><td> </td><td> </td><td> </td></tr><tr><td> </td><td> [</td><td>#:content content])</td><td> </td><td>→</td><td> </td><td>rss-item?</td></tr></table></td></tr><tr><td>  title : string?</td></tr><tr><td>  url : string?</td></tr><tr><td>  content : (or/c #f string?) = #f</td></tr></table>Here’s an example Atom feed page:<table cellspacing="0" class="schemeblock"><tr><td>  (define-page (article-feed-page req)</td></tr><tr><td>    #:blank #t</td></tr><tr><td>    (atom-feed article-feed-page</td></tr><tr><td>               #:feed-title "LeftParen blog"</td></tr><tr><td>               #:feed-description "On LeftParen..."</td></tr><tr><td>               #:feed-updated/epoch-seconds (current-seconds)</td></tr><tr><td>               #:author-name "LP staffers"</td></tr><tr><td>               #:items (list</td></tr><tr><td>                        (atom-item #:title "Status update..."</td></tr><tr><td>                                   #:url "http://blog.../50308696"</td></tr><tr><td>                                   #:updated-epoch-seconds</td></tr><tr><td>                                   (current-seconds)</td></tr><tr><td>                                   #:content "I’m nearing a...")</td></tr><tr><td>                        (atom-item #:title "LeftParen 0.3..."</td></tr><tr><td>                                   #:updated-epoch-seconds</td></tr><tr><td>                                   (current-seconds)</td></tr><tr><td>                                   #:url "http://blog.../51814971"</td></tr><tr><td>                                   #:content "Tonight I..."))))</td></tr></table>Note that while using current-seconds for timestamps does satisfy the interface, it’s not really appropriate since these times are supposed to indicated freshness of the data. If basing your feed off of records, you might consider using created-when.<h3>4<tt> </tt><a name="(part._.About_.Acknowledgements)"></a>About/Acknowledgements</h3>LeftParen was initially written by <a href="http://robhunter.org">Rob Hunter</a>. It makes use of <a href="http://planet.plt-scheme.org/display.ss?package=dispatch.plt&owner=untyped">Dispatch</a> by <a href="http://untyped.com/">Untyped</a>, <a href="http://planet.plt-scheme.org/display.ss?package=with-bindings.plt&owner=jaymccarthy">with-bindings</a> by <a href="http://jay-mccarthy.blogspot.com/">Jay McCarthy</a>, and of course, <a href="http://www.plt-scheme.org/">PLT Scheme</a>.LeftParen used to use <a href="http://planet.plt-scheme.org/display.ss?package=web.plt&owner=soegaard">WEB</a> by <a href="http://scheme.dk/blog/">Jens Axel Soegaard</a> and <a href="http://planet.plt-scheme.org/display.ss?package=instaservlet.plt&owner=untyped">Instaservlet</a> (now deprecated) by <a href="http://untyped.com/">Untyped</a>, which were both very helpful in getting the project started.<h4>4.1<tt> </tt><a name="(part._.Code_.Contributors)"></a>Code Contributors</h4><ul><li>Bill Hager</li><li>Joshua Herman</li></ul></div></div></body></html> \ No newline at end of file +to go if you can do this:<table cellspacing="0"><tr><td>% mzscheme</td></tr><tr><td>Welcome to MzScheme v4.1.5...</td></tr><tr><td>></td></tr></table>Installing LeftParen is done automatically when you perform various <a href="http://planet.plt-scheme.org/">PLaneT</a> require commands. See <a href="/#(part._tutorials)">Tutorials</a> for examples of this. On my system, starting a LeftParen web app for the first time (with a freshly installed version of PLT Scheme), takes about an hour. (The time is spent downloading and installing a bunch of files into your local PLaneT repository.)At any point, if you see an error like<table cellspacing="0"><tr><td>make-directory: cannot make directory: /home/rob/.plt-scheme/planet/300/4.1.5 (Permission denied; errno=13)</td></tr></table>try re-running the command with sudo (you won’t need to do this everytime–just the once).<h3>2<tt> </tt><a name="(part._tutorials)"></a>Tutorials</h3><h4>2.1<tt> </tt><a name="(part._.Hello__.World)"></a>Hello, World</h4>We’re going to make a project called hello-world. Change to the directory that you’d like to create the project in. Then issue<table cellspacing="0"><tr><td>% mzscheme -e '(require (planet vegashacker/leftparen:5:=1/generate))' hello-world</td></tr></table>This will create a hello-world project directory for you. In this directory you’ll find the script directory, which contains some useful scripts. All paths are relative to this project directory, so when calling scripts, you always want to be at the project root.<table cellspacing="0"><tr><td>% cd hello-world</td></tr></table>We need to make the scripts executable:<table cellspacing="0"><tr><td>% chmod u+x script/server</td></tr></table>LeftParen has automatically generated everything we need to run our web app – we just need to start the server (again, you should be at the project root directory):<table cellspacing="0"><tr><td>% ./script/server</td></tr><tr><td>Populating caches...</td></tr><tr><td>Done populating cache.</td></tr><tr><td>Server is ready at http://localhost:8765/ (ctrl-c to stop it).</td></tr></table>Point your browser to <a href="http://localhost:8765">http://localhost:8765</a> and you should see a familiar greeting:Hello, World!<h4>2.2<tt> </tt><a name="(part._.Blogerton_the_.Blog)"></a>Blogerton the Blog</h4>Now let’s try implementing the true "hello world" of web apps – a blog. First, execute the following commands from the directory in which you want to create your project:<table cellspacing="0"><tr><td>% mzscheme -e '(require (planet vegashacker/leftparen:5:=1/generate))' blogerton</td></tr><tr><td>% cd blogerton</td></tr><tr><td>% chmod u+x script/server</td></tr></table><h5>2.2.1<tt> </tt><a name="(part._.Changes_to_app_scm)"></a>Changes to app.scm</h5>We need to register a couple of pages in our app. The index-page was already set up for you, but you’ll need to add a page to create new posts, and one to view them. Make the define-app call look like this:<table cellspacing="0" class="schemeblock"><tr><td>  (define-app my-app</td></tr><tr><td>    (index-page (url "/"))</td></tr><tr><td>    (create-post-page (url "/post"))</td></tr><tr><td>    (view-post-page (url "/view/" (string-arg))))</td></tr></table><h5>2.2.2<tt> </tt><a name="(part._.Changes_to_main_scm)"></a>Changes to main.scm</h5>Now we need to define those pages that we declared in app.scm.<table cellspacing="0" class="schemeblock"><tr><td>  (define-page (index-page req)</td></tr><tr><td>    (** `(h1 "Blogerton")</td></tr><tr><td>        `(p ,(web-link "Create a new post" (page-url create-post-page)))</td></tr><tr><td>        `(ul ,@(map (lambda (p) `(li ,(paint-blog-post p)))</td></tr><tr><td>                    (load-where '((type . blog-post))</td></tr><tr><td>                                #:sort-by 'created-at #:compare >)))))</td></tr><tr><td>  </td></tr><tr><td>  (define-page (create-post-page req)</td></tr><tr><td>    (form '((title "Title" text) (body "Body" long-text))</td></tr><tr><td>          #:init '((type . blog-post))</td></tr><tr><td>          #:on-done (lambda (post) (redirect-to-page view-post-page (rec-id post)))))</td></tr><tr><td>  </td></tr><tr><td>  (define-page (view-post-page req post-id)</td></tr><tr><td>    (paint-blog-post (load-rec post-id #:ensure '((type . blog-post)))))</td></tr><tr><td>  </td></tr><tr><td>  (define (paint-blog-post post)</td></tr><tr><td>    `(div (h2 ,(rec-prop post 'title))</td></tr><tr><td>          (p ,(rec-prop post 'body))))</td></tr></table><h5>2.2.3<tt> </tt><a name="(part._.Launch_.Blogerton)"></a>Launch Blogerton</h5>You’re ready for launch. Start the server with<table cellspacing="0"><tr><td>% ./script/server</td></tr></table>and you should have a basic blogging app, with persistent data, in 19 lines of code.<h3>3<tt> </tt><a name="(part._.Reference)"></a>Reference</h3><h4>3.1<tt> </tt><a name="(part._.Forms)"></a>Forms</h4>Most web applications make some use of web forms. The form function lets easily you get and process input from your users.<table cellspacing="0" class="boxed"><tr><td>(form field-specs) → xexpr?</td></tr><tr><td>  field-specs : (listof field-spec?)</td></tr></table><table cellspacing="0" class="boxed"><tr><td>field-spec? : (list symbol? string? field-type?)</td></tr></table><table cellspacing="0" class="boxed"><tr><td><table cellspacing="0" class="argcontract"><tr><td>field-type? : </td><td><table cellspacing="0" class="schemeblock"><tr><td>(or/c 'text 'long-text 'number 'password 'image 'checkbox</td></tr><tr><td>      'radio 'drop-down)</td></tr></table></td></tr></table></td></tr></table>You create a form by listing, in order, "field specifications". For example, you might want a title field, followed by a description text box, followed by a photo upload field. Note that the many keyword arguments available to the form function aren’t documented yet.Each field spec is of the form (field-name label field-type). For example, you create a title field, you might use the spec (title "Enter a title" text). The entire example metioned above might look like this:<table cellspacing="0" class="schemeblock"><tr><td>  (form '((title "Title" text)</td></tr><tr><td>          (description "Description" long-text)</td></tr><tr><td>          (photo "Your photo" image)))</td></tr></table><h5>3.1.1<tt> </tt><a name="(part._.Image_uploads)"></a>Image uploads</h5>By default, uploaded images are stored in the uploaded-files directory in your project directory. You can customize this with the *PATH_TO_UPLOADED_FILES* setting. When images are saved, their original filenames are used with a 5-character code pre-pended to make filenames unique.<h4>3.2<tt> </tt><a name="(part._.Sessions)"></a>Sessions</h4>A session is an object that allows you to easily store state about individual visitors to your web app. Sessions are stored on the server as a record with a virtually impossible-to-guess id. A cookie is left in the user’s web browser, which contains a pointer to a particular session id. These cookies expire one month after creation and, currently, this can’t be changed.<h5>3.2.1<tt> </tt><a name="(part._.Creating_sessions)"></a>Creating sessions</h5><table cellspacing="0" class="boxed"><tr><td><table cellspacing="0" class="schemeblock"><tr><td>(define-session-page</td></tr><tr><td>  (page-name request-iden session-iden page-args ...)</td></tr><tr><td>  body ...)</td></tr></table></td></tr></table>This is an alternate to define-page, most commonly used in main.scm. The only difference is that after the request identifier, you must provide a session identifier. For example, to keep a counter (unique to each user), you could write:<table cellspacing="0" class="schemeblock"><tr><td>  (define-session-page (foo-page req sesh)</td></tr><tr><td>    (let ((c (session-get-val sesh 'counter 0)))</td></tr><tr><td>      (session-put-val! sesh 'counter (+ 1 c))</td></tr><tr><td>      (number->string c)))</td></tr></table>When you define a session page, the session is automatically fetched for you (and created if necessary), and bound to the session identifier you provided.<h5>3.2.2<tt> </tt><a name="(part._.Accessing_sessions)"></a>Accessing sessions</h5><table cellspacing="0" class="boxed"><tr><td>(session-get-val session key [missing-val]) → any</td></tr><tr><td>  session : session</td></tr><tr><td>  key : symbol</td></tr><tr><td>  missing-val : any = #f</td></tr></table><table cellspacing="0" class="boxed"><tr><td>(session-put-val! session key val) → session</td></tr><tr><td>  session : session</td></tr><tr><td>  key : symbol</td></tr><tr><td>  val : any</td></tr></table><h4>3.3<tt> </tt><a name="(part._.Storing_closures_in_.U.R.Ls)"></a>Storing closures in URLs</h4>LeftParen provides a simple way to create closures and attach them to a URL. Using this technique is often much simpler than the more traditional encoding of values in a URL by hand.<table cellspacing="0" class="boxed"><tr><td>(body-as-url (req-iden [key] [#:sticky]) body ...)</td></tr></table>Creates a URL which, when visited, will execute the given body. If key is provided, then it will be used as the id to represent the closure. It’s more common, however, to not pass your own key–in which case, a unique, random one will be chosen for you. req-iden will be bound to the request created when the link is executed and available for use in body. If #:sticky is provided, then the closure will be available for execution until the server is stopped. Otherwise, it is available for execution just once.<table cellspacing="0" class="schemeblock"><tr><td>  (define-page (index-page req)</td></tr><tr><td>    (let ((x 0))</td></tr><tr><td>      (web-link "Click to increment"</td></tr><tr><td>                (body-as-url (req)</td></tr><tr><td>                             (set! x (+ x 1))</td></tr><tr><td>                             (format "x is ~A" x)))))</td></tr></table>This creates a link, which, when clicked, prints x is 1. If you reload the page, however, you’ll see something like Expired or missing function ’q7c5ysd4935xhbhx2xbu’. Changing the first sub-form passed to body-as-url to (req #:sticky) makes it so that successive hits to the link result in increasing values of x.<h4>3.4<tt> </tt><a name="(part._.Users)"></a>Users</h4>LeftParen provides built-in functionality for dealing with users, including registering users, logging users in and out, and storing persistent data about users. To get up-and-running quickly, you can use the high-level welcome-message function:<table cellspacing="0" class="boxed"><tr><td><table cellspacing="0" class="prototype"><tr><td>(welcome-message</td><td> </td><td>session</td><td> </td><td> </td><td> </td><td> </td></tr><tr><td> </td><td> [</td><td>#:on-success success-fn</td><td> </td><td> </td><td> </td><td> </td></tr><tr><td> </td><td> </td><td>#:no-register no-register])</td><td> </td><td>→</td><td> </td><td>xexpr</td></tr></table></td></tr><tr><td>  session : session?</td></tr><tr><td>  success-fn : (or/c (-> user? xexpr?) #f) = #f</td></tr><tr><td>  no-register : boolean? = #f</td></tr></table>The function welcome-message produces a small area of text and links (commonly found in the top-right area of a web app). If the user is not currently logged in, login and register links are presented. If the user is logged in, a message welcoming them is displayed, along with a link to log out.<table cellspacing="0" class="boxed"><tr><td>(current-user session) → (or/c user? #f)</td></tr><tr><td>  session : session?</td></tr></table>The function current-user returns the current user record, or #f if no user is available in the current session.As an example, here is the complete page code for a web app that allows users to register, login and logout, and which prints a secret message if the user is logged in:<table cellspacing="0" class="schemeblock"><tr><td>  (define-session-page (index-page req sesh)</td></tr><tr><td>    (** (welcome-message sesh)</td></tr><tr><td>        (aif (current-user sesh)</td></tr><tr><td>             (format "The secret, ~A, is 42." (rec-prop it 'username))</td></tr><tr><td>             "No secret for you.")))</td></tr></table>Note that aif is available in the <a href="/#(part._utilities)">Utility Functions</a> included with LeftParen.<h4>3.5<tt> </tt><a name="(part._.Feeds)"></a>Feeds</h4>You can create Atom or RSS feeds in your web app. A feed in LeftParen is just a page crafted in a paricular way. The core functions involved are atom-feed and rss-feed:<table cellspacing="0" class="boxed"><tr><td><table cellspacing="0" class="prototype"><tr><td>(atom-feed</td><td> </td><td>atom-feed-page</td><td> </td></tr><tr><td> </td><td> </td><td>#:feed-title feed-title</td><td> </td></tr><tr><td> </td><td> </td><td>#:feed-updated/epoch-seconds updated-seconds</td><td> </td></tr><tr><td> </td><td> </td><td>#:author-name author-name</td><td> </td></tr><tr><td> </td><td> [</td><td>#:feed-description feed-description</td><td> </td></tr><tr><td> </td><td> </td><td>#:feed-id feed-id</td><td> </td></tr><tr><td> </td><td> </td><td>#:related-content-link related-content-link</td><td> </td></tr><tr><td> </td><td> </td><td>#:items atom-items])</td><td> </td></tr></table></td></tr><tr><td> → response/full?</td></tr><tr><td>  atom-feed-page : page?</td></tr><tr><td>  feed-title : string?</td></tr><tr><td>  updated-seconds : integer?</td></tr><tr><td>  author-name : string?</td></tr><tr><td>  feed-description : (or/c #f string?) = #f</td></tr><tr><td>  feed-id : string? = THE_URL_OF_THE_GIVEN_ATOM_FEED_PAGE</td></tr><tr><td>  related-content-link : string? = THE_LINK_TO_YOUR_WEB_APP</td></tr><tr><td>  atom-items : (list-of atom-item?) = '()</td></tr></table><table cellspacing="0" class="boxed"><tr><td><table cellspacing="0" class="prototype"><tr><td>(rss-feed</td><td> </td><td>rss-feed-page</td><td> </td></tr><tr><td> </td><td> </td><td>#:feed-title feed-title</td><td> </td></tr><tr><td> </td><td> </td><td>#:feed-description feed-description</td><td> </td></tr><tr><td> </td><td> [</td><td>#:related-content-link related-content-link</td><td> </td></tr><tr><td> </td><td> </td><td>#:items rss-items])</td><td> </td></tr></table></td></tr><tr><td> → response/full?</td></tr><tr><td>  rss-feed-page : page?</td></tr><tr><td>  feed-title : string?</td></tr><tr><td>  feed-description : string?</td></tr><tr><td>  related-content-link : string? = THE_LINK_TO_YOUR_WEB_APP</td></tr><tr><td>  rss-items : (list-of rss-item?) = '()</td></tr></table>The #:items argument in each of these functions is a list of items constructed with atom-item and rss-item:<table cellspacing="0" class="boxed"><tr><td><table cellspacing="0" class="prototype"><tr><td>(atom-item</td><td> </td><td>#:title title</td><td> </td></tr><tr><td> </td><td> </td><td>#:url url</td><td> </td></tr><tr><td> </td><td> </td><td>#:updated-epoch-seconds updated-seconds</td><td> </td></tr><tr><td> </td><td> [</td><td>#:content content])</td><td> </td></tr></table></td></tr><tr><td> → atom-item?</td></tr><tr><td>  title : string?</td></tr><tr><td>  url : string?</td></tr><tr><td>  updated-seconds : integer?</td></tr><tr><td>  content : (or/c #f string?) = #f</td></tr></table><table cellspacing="0" class="boxed"><tr><td><table cellspacing="0" class="prototype"><tr><td>(rss-item</td><td> </td><td>#:title title</td><td> </td><td> </td><td> </td><td> </td></tr><tr><td> </td><td> </td><td>#:url url</td><td> </td><td> </td><td> </td><td> </td></tr><tr><td> </td><td> [</td><td>#:content content])</td><td> </td><td>→</td><td> </td><td>rss-item?</td></tr></table></td></tr><tr><td>  title : string?</td></tr><tr><td>  url : string?</td></tr><tr><td>  content : (or/c #f string?) = #f</td></tr></table>Here’s an example Atom feed page:<table cellspacing="0" class="schemeblock"><tr><td>  (define-page (article-feed-page req)</td></tr><tr><td>    #:blank #t</td></tr><tr><td>    (atom-feed article-feed-page</td></tr><tr><td>               #:feed-title "LeftParen blog"</td></tr><tr><td>               #:feed-description "On LeftParen..."</td></tr><tr><td>               #:feed-updated/epoch-seconds (current-seconds)</td></tr><tr><td>               #:author-name "LP staffers"</td></tr><tr><td>               #:items (list</td></tr><tr><td>                        (atom-item #:title "Status update..."</td></tr><tr><td>                                   #:url "http://blog.../50308696"</td></tr><tr><td>                                   #:updated-epoch-seconds</td></tr><tr><td>                                   (current-seconds)</td></tr><tr><td>                                   #:content "I’m nearing a...")</td></tr><tr><td>                        (atom-item #:title "LeftParen 0.3..."</td></tr><tr><td>                                   #:updated-epoch-seconds</td></tr><tr><td>                                   (current-seconds)</td></tr><tr><td>                                   #:url "http://blog.../51814971"</td></tr><tr><td>                                   #:content "Tonight I..."))))</td></tr></table>Note that while using current-seconds for timestamps does satisfy the interface, it’s not really appropriate since these times are supposed to indicated freshness of the data. If basing your feed off of records, you might consider using created-when.<h3>4<tt> </tt><a name="(part._utilities)"></a>Utility Functions</h3>Some <a href="http://github.com/vegashacker/leftparen/commits/master/util.scm">miscellaneous utility functions</a> are available along with LeftParen. To be able to use these functions, you’ll need to require util.scm at the top of your module. Something like this is common:<table cellspacing="0" class="schemeblock"><tr><td>  (require (planet "leftparen.scm" ("vegashacker" "leftparen.plt" 5 (= 1)))</td></tr><tr><td>           (planet "util.scm" ("vegashacker" "leftparen.plt" 5 (= 1))))</td></tr></table><h3>5<tt> </tt><a name="(part._.About_.Acknowledgements)"></a>About/Acknowledgements</h3>LeftParen was initially written by <a href="http://robhunter.org">Rob Hunter</a>. It makes use of <a href="http://planet.plt-scheme.org/display.ss?package=dispatch.plt&owner=untyped">Dispatch</a> by <a href="http://untyped.com/">Untyped</a>, <a href="http://planet.plt-scheme.org/display.ss?package=with-bindings.plt&owner=jaymccarthy">with-bindings</a> by <a href="http://jay-mccarthy.blogspot.com/">Jay McCarthy</a>, and of course, <a href="http://www.plt-scheme.org/">PLT Scheme</a>.LeftParen used to use <a href="http://planet.plt-scheme.org/display.ss?package=web.plt&owner=soegaard">WEB</a> by <a href="http://scheme.dk/blog/">Jens Axel Soegaard</a> and <a href="http://planet.plt-scheme.org/display.ss?package=instaservlet.plt&owner=untyped">Instaservlet</a> (now deprecated) by <a href="http://untyped.com/">Untyped</a>, which were both very helpful in getting the project started.<h4>5.1<tt> </tt><a name="(part._.Code_.Contributors)"></a>Code Contributors</h4><ul><li>Bill Hager</li><li>Joshua Herman</li></ul></div></div></body></html> \ No newline at end of file planet-docs/leftparen/index.html 126f8489442bc52f3c990c913813a021fb6d9920 Rob Hunter rob.hunter@gmail.com http://github.com/vegashacker/leftparen/commit/169c896bda989b6a049fe49253a04d6f8b62402b 169c896bda989b6a049fe49253a04d6f8b62402b

2009-05-15T12:05:55-07:00

minor update before deploying to PLaneT e45a3c761d844eefdabb60dbc4d7cb6831dfb7fb Rob Hunter rob.hunter@gmail.com