Greg Slepak  committed c3a55de

more doc updates

  • Participants
  • Parent commits 5bb1232
  • Branches default

Comments (0)

Files changed (4)

File api-docs/dragonfly.lsp.html

 <br/><br/><center>- &sect; -</center><br/>
 <a name="Dragonfly_web-root"></a><h3><font color=#CC0000>Dragonfly:web-root</font></h3>
-<b>syntax: (<font color=#CC0000>Dragonfly:web-root</font> <em>str-path</em>)</b><br/>
+<b>syntax: (<font color=#CC0000>Dragonfly:web-root</font> <em>str-path</em> <em>bool-question-mark</em>)</b><br/>
 <b>parameter: </b><em>str-path</em> - Path relative to the folder containing <tt>index.cgi</tt>.<br/>
+<b>parameter: </b><em>bool-question-mark</em> - Whether to return a URL with /? prepended.<br/>
  <p>This function is quite handy for making working links when your <tt>index.cgi</tt> file
  is not in <tt>DOCUMENT_ROOT</tt> but a subfolder of it.</p>
 <b>example:</b><blockquote><pre> ; index.cgi is located in /home/user/
  ; Users visit
  (web-root "about") =&gt; "/example-site/about"
- (web-root "/foo") =&gt; "/example-site/foo"</pre></blockquote>
+ (web-root "/foo" true) =&gt; "/example-site/?foo"</pre></blockquote>
 <br/><br/><center>- &sect; -</center><br/>
 <a name="Dragonfly_view-path"></a><h3><font color=#CC0000>Dragonfly:view-path</font></h3>
 <b>syntax: (<font color=#CC0000>Dragonfly:view-path</font> <em>str-view-name</em>)</b><br/>

File example-site/dragonfly-framework/dragonfly.lsp

-;; @syntax (Dragonfly:web-root <str-path>)
+;; @syntax (Dragonfly:web-root <str-path> <bool-question-mark>)
 ;; @param <str-path> Path relative to the folder containing 'index.cgi'.
+;; @param <bool-question-mark> Whether to return a URL with /? prepended.
 ;; <p>This function is quite handy for making working links when your 'index.cgi' file
 ;; is not in 'DOCUMENT_ROOT' but a subfolder of it.</p>
 ;; @example
 ;; ; index.cgi is located in /home/user/
 ;; ; Users visit
 ;; (web-root "about") => "/example-site/about"
-;; (web-root "/foo") => "/example-site/foo"
-(define (web-root path)
+;; (web-root "/foo" true) => "/example-site/?foo"
+(define (web-root path question-mark)
 	; WEB_ROOT should have a "/" on the end
 	(if (starts-with path "/") (pop path))
-	(string WEB_ROOT path)
+	(string WEB_ROOT (if question-mark "?" "") path)
 ;; @syntax (Dragonfly:view-path <str-view-name>)

File example-site/views/dragonfly_routes.html

 		<p class="extract">
 			Dragonfly's routes are written in pure newLISP code and have no arbitrary constraints placed on them. They can be as simple or complex as you need them to be. In fact, Dragonfly's routes are so flexible that the defaults will often be all you'll need.
+		<p>
+			Dragonfly's routes are represented as <a href="">FOOP objects</a> and use
+			the convention of prepending "Route." to their name to avoid namespace conflicts.
+		</p>
+		<p>
+			This document describes Dragonfly's two default routes: <span class="code">Route.Static</span> and <span class="code">Route.Resource</span>.
+		</p>
 		<h2>Static Routes</h2>
-		<p>
-			<span class="code">Route.Static</span> is one of the two default routes that Dragonfly comes with. The other route is <span class="code">Route.Resource</span> (<a href="#restful">described below</a>).
-		</p>
-		<p><span class="code">Route.Static</span> offers a flexible method of serving template files to allow for a PHP-like development pattern (except PHP is replaced with newLISP code).
+		<p><span class="code">Route.Static</span> offers a flexible method for serving template files to allows for a PHP-like development pattern, but without the PHP.
 			It handles requests such as the following:
-			This route is very flexible, and there are only three configuration parameters that may want to adjust in <b>config.lsp</b>:
+			This route is very flexible, and there are only three configuration parameters associated with it in <b>config.lsp</b>:
 		<h3 class="param">ENABLE_STATIC_TEMPLATES</h3>
 		<p>Default value: <span class="code"><b>true</b></span></p>
 => "/home/www/"
-			Go ahead and <% (link_to "try it!" "foo") %>
+			Go ahead and <% (link_to "give it a try!" "foo") %>
+		</p>
+		<p>
+			The page you're currently on was matched by the third transformation:
+		</p>
+<pre class="code">
+(begin (set 'viewname _)
+       (string VIEWS_PATH "/" _ VIEW_EXTENSION))
+		<p>
+			The winning transformation is evaluated twice: the first time to
+			check for a file, and once again if the file exists. This allows
+			you to use transformations for more than just path testing. For example,
+			the third transformation also sets <span class="code">DF:viewname</span>
+			to the name of the view.
 		<a name="restful"></a>
 		<h2>RESTful Routes</h2>
-		<p class="extract">Dragonfly supports RESTful resources. This way it's flexible against any kind of request to Your application.</p>
-		<p>When your Dragonfly application receives an incoming HTTP request, say
+		<p class="extract">
+			Dragonfly supports the creation of powerful web applications through
+			the use of clean RESTful routes.
+		</p>
+		<p><span class="code">Route.Resource</span> handles URLs that refer to RESTful resources, also represented as FOOP objects derived from the Resource context. The configuration parameter <span class="code">RESOURCES_PATH</span> specifies the folder containing the resources as .lsp files, one per resource.</p>
+		<p>The URL scheme works in a similar manner to twitter's RESTful API:</p>
+		<pre class="code"><b>resource</b>[/<b>action</b>][/<b>id</b>][.<b>format</b>][?get params..]</pre>
-		<p class="code">GET /wings/show</p>
-		the <b>LISTENER</b> within Dragonfly is the piece of code that dispatches the request to the appropriate spot in your application. In this case, the application would most likely end up running the <b>SHOW</b> action within the <b>WINGS</b> resource, displaying the WINGS.</p>
-		<p class="info">The resource <b>WINGS</b> has to be available in Your resource directory</p>
-		<h3 class="code">Example of wings.lsp in /resources</h3>
+			<span class="code"><b>resource</b></span> - maps to a context name in a special way:</p>
+		<ol><li><span class="code">Resource.</span> is prepended to the name</li>
+			<li>Any underscores are removed</li>
+			<li>The name is written in title case</li>
+		</ol>
+		<p>The resource may only have the letters A-Z (lowercase or uppercase), 0-9, the underscore, and it must begin with a letter. For example:
+		</p>
+		<p>
+			<span class="code">my_resource => Resource.MyResource</span>
+		</p>
+		<p>
+			The name also maps to a real file located in <span class="code">RESOURCES_PATH</span> by appending ".lsp" to the name:
+		</p>
+		<p>
+			<span class="code"> my_resource => load file: RESOURCES_PATH/my_resource.lsp</span>
+		</p>
+		<p>
+			<span class="code"><b>action</b></span> (optional) - specifies the function to be called on the resource. Like resource, <span class="code">action</span> may only contain letters, numbers, and the underscore. If no action is specified, then the resource's <a href="" target="_blank">default function</a> is called instead. Whichever function gets called, the <span class="code">id</span> and <span class="code">format</span> are passed in as parameters (in that order).
+		</p>
+		<p>
+			<span class="code"><b>id</b></span> (optional) - may only contain numbers and can be used to specify a specific object out of a collection.
+		</p>
+		<p>
+			<span class="code"><b>format</b></span> (optional) - may only contain letters and can be used to specify the response format. (i.e. xml, json, etc.)
+		</p>
+		<h3 class="code">Example resource in resources/wings.lsp:</h3>
 		<pre class="code">
 (DF:activate-plugin "artfulcode/json")
 (context MAIN)</pre>
-		<p class="config"><b>CONFIGURATION</b><br/>You may enable or disable RESTful handling by setting the constant ENABLE_RESTFUL_HANDLER in config.lsp. Default is set to "true".</p>
-		<p class="config"><b>CONFIGURATION</b><br/>Set Your resource directory to whatever You want by changing the constant RESOURCES_PATH in config.lsp. Default is set to "/resources".</p>	
+		<p>Try it out:</p>
+		<div style="margin-top:10px">
+			<div id="wings_resp" style="width:300px; height:40px; border:1px solid gray; padding:4px">
+				&nbsp;
+			</div>
+			<form id="wings_form" action="<%=(web-root "wings" true)%>">
+				<p>
+					<select id="response_format">
+					<option value="">format: default (text)</option>
+					<option value=".json">format: json</option>
+					</select>
+					<input type="submit" value="Submit">
+				</p>
+			</form>
+		</div>
+		<script type="text/javascript" charset="utf-8">
+			var form = $('#wings_form');
+			form.find("input[type='submit']").click(function() {
+				var req_url = form.attr('action') + $('#response_format').val();
+				$.post(req_url, {blah:''}, function (data, status) {
+					$('#wings_resp').html(data);
+				});
+				return false;
+			});
+		</script>
 		<p class="continue"><% (link_to "CONTINUE &raquo;" "dragonfly_views") %></p>
 		<div class="clear"></div>
 		<div class="line-dotted"></div>

File example-site/views/partials/navigation.html

 				<dd><% (link_to  "Default routes" "dragonfly_routes") %></dd>
+				<dd><% (link_to  "Creating your own" "dragonfly_routes") %></dd>
 				<dd><% (link_to  "Creating templates" "dragonfly_views") %></dd>