RubyGems - utopia - Versions diffs - 2.2.0 → 2.3.0 - Mend

utopia 2.2.0 → 2.3.0

Files changed (290) hide show

data/docs/wiki/middleware/controller.html ADDED Viewed

@@ -0,0 +1,104 @@
+<!DOCTYPE html>
+<html>
+	<head>
+			<title>Controller - Utopia</title>
+		<meta charset="UTF-8"/>
+		<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-wvfXpqpZZVQGK6TAh5PVlGOfQNHSoD2xbE+QkPxCAFlNEevoEH3Sl0sibVcOQVnN" crossorigin="anonymous"/>
+		<link rel="icon" type="image/png" href="../../_static/icon.png"/>
+		<link rel="stylesheet" href="../../_static/site.css" type="text/css" media="screen"/>
+		<script src="../../_components/jquery/jquery.min.js"></script>
+		<script src="../../_components/jquery-syntax/jquery.syntax.min.js"></script>
+		<script type="text/javascript">
+		//<![CDATA[
+			jQuery(function($) {
+				$.syntax();
+			});
+		//]]>
+		</script>
+	</head>
+	<body class="">
+		<header>
+			<img src="../../_static/utopia.svg"/>
+		</header>
+		<div id="page">
+	<nav>
+	 › <a href="../../wiki.html">Wiki</a> › <span>Middleware</span> › <a href="controller.html">Controller</a></nav>
+	<h1 id="controller">Controller</h1>
+<p>A simple recursive controller layer which works in isolation from the view rendering middleware.</p>
+<pre><code class="language-ruby">use Utopia::Controller,
+	# The root directory where `controller.rb` files can be found.
+	root: 'path/to/root',
+	# The base class to use for all controllers:
+	base: Utopia::Controller::Base,
+	# Whether or not to cache controller classes:
+	cache_controllers: (RACK_ENV == :production)
+</code></pre>
+<p>A controller is a file within the root directory (or subdirectory) with the name <code>controller.rb</code>. This code is dynamically loaded into an anonymous class and executed. The default controller has only a single function:</p>
+<pre><code class="language-ruby">def passthrough(request, path)
+	# Call one of:
+	# This will cause the middleware to generate a response.
+	# def respond!(response)
+	# This will cause the controller to skip the request.
+	# def ignore!
+	# Request relative redirect. Respond with a redirect to the given target.
+	# def redirect! (target, status = 302)
+	# Controller relative redirect.
+	# def goto!(target, status = 302)
+	# Respond with an error which indiciates some kind of failure.
+	# def fail!(error = 400, message = nil)
+	# Succeed the request and immediately respond.
+	# def succeed!(status: 200, headers: {}, **options)
+	# options may include content: string or body: Enumerable (as per Rack specifications
+end
+</code></pre>
+<p>The controller layer can do more complex operations by prepending modules into it.</p>
+<pre><code class="language-ruby">prepend Rewrite, Actions
+# Extracts an Integer
+rewrite.extract_prefix id: Integer do
+	@user = User.find_by_id(@id)
+end
+on 'edit' do |request, path|
+	if request.post?
+		@user.update_attributes(request[:user])
+	end
+end
+otherwise do |request, path|
+	# Executed if no specific named actions were executed.
+	succeed!
+end
+</code></pre>
+	<footer>
+		Last Modified: 2016-12-13 12:38:35 +1300 —
+	</footer>
+		</div>
+	</body>
+</html>

data/docs/wiki/middleware/controller/actions.html ADDED Viewed

@@ -0,0 +1,117 @@
+<!DOCTYPE html>
+<html>
+	<head>
+			<title>Actions - Utopia</title>
+		<meta charset="UTF-8"/>
+		<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-wvfXpqpZZVQGK6TAh5PVlGOfQNHSoD2xbE+QkPxCAFlNEevoEH3Sl0sibVcOQVnN" crossorigin="anonymous"/>
+		<link rel="icon" type="image/png" href="../../../_static/icon.png"/>
+		<link rel="stylesheet" href="../../../_static/site.css" type="text/css" media="screen"/>
+		<script src="../../../_components/jquery/jquery.min.js"></script>
+		<script src="../../../_components/jquery-syntax/jquery.syntax.min.js"></script>
+		<script type="text/javascript">
+		//<![CDATA[
+			jQuery(function($) {
+				$.syntax();
+			});
+		//]]>
+		</script>
+	</head>
+	<body class="">
+		<header>
+			<img src="../../../_static/utopia.svg"/>
+		</header>
+		<div id="page">
+	<nav>
+	 › <a href="../../../wiki.html">Wiki</a> › <span>Middleware</span> › <a href="../controller.html">Controller</a> › <a href="actions.html">Actions</a></nav>
+	<h1 id="controlleractions">Controller::Actions</h1>
+<p>Actions let you match path patterns in your controller and execute code. In your <code>controller.rb</code> simply add:</p>
+<pre><code class="language-ruby">prepend Actions
+</code></pre>
+<p>If you are adding multiple things, like rewriting, they should come earlier in the chain, e.g:</p>
+<pre><code class="language-ruby">prepend Rewrite, Actions
+</code></pre>
+<p>A simple CRUD controller might look like:</p>
+<pre><code class="language-ruby">prepend Actions
+on 'index' do
+	@users = User.all
+end
+on 'new' do |request|
+	@user = User.new
+	if request.post?
+		@user.update_attributes(request.params['user'])
+		redirect! "index"
+	end
+end
+on 'edit' do |request|
+	@user = User.find(request.params['id'])
+	if request.post?
+		@user.update_attributes(request.params['user'])
+		redirect! "index"
+	end
+end
+on 'delete' do |request|
+	User.find(request.params['id']).destroy
+	redirect! "index"
+end
+</code></pre>
+<h2 id="path-matching">Path Matching</h2>
+<p>Path matching works from right to left, and ‘**’ is a greedy operator. Controllers are invoked with a path relative to the controller’s <code>URI_PATH</code>, so all lookups are relative to the controller.</p>
+<dl>
+	<dt><code class="language-ruby">"*"</code></dt>
+	<dd>Match a single path element</dd>
+	<dt><code class="language-ruby">"**"</code></dt>
+	<dd>Match all remaining path elements</dd>
+	<dt><code class="language-ruby">String</code></dt>
+	<dd>Match a named path component, e.g. <code class="language-ruby">"edit"</code>.</dd>
+	<dt><code class="language-ruby">Symbol</code></dt>
+	<dd>Equivalent to <code class="language-ruby">["**", symbol.to_s]</code>, e.g. <code class="language-ruby">:logout</code>.</dd>
+</dl>
+<h2 id="otherwise-matching">Otherwise Matching</h2>
+<p>If no action was matched, it is sometimes useful to perform some specific behaviour. You can specify this by using the otherwise handler:</p>
+<pre><code class="language-ruby">otherwise do |request, path|
+	fail! :teapot
+end
+</code></pre>
+<p>If you are doing this to perform some kind of rewriting, it may be preferable to use the <a href="actions/rewrite/index.html">Rewrite</a> controller layer.</p>
+	<footer>
+		Last Modified: 2017-05-03 14:21:19 +1200 —
+	</footer>
+		</div>
+	</body>
+</html>

data/docs/wiki/middleware/controller/actions/index.html ADDED Viewed

@@ -0,0 +1,117 @@
+<!DOCTYPE html>
+<html>
+	<head>
+			<title>Actions - Utopia</title>
+		<meta charset="UTF-8"/>
+		<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-wvfXpqpZZVQGK6TAh5PVlGOfQNHSoD2xbE+QkPxCAFlNEevoEH3Sl0sibVcOQVnN" crossorigin="anonymous"/>
+		<link rel="icon" type="image/png" href="../../../../_static/icon.png"/>
+		<link rel="stylesheet" href="../../../../_static/site.css" type="text/css" media="screen"/>
+		<script src="../../../../_components/jquery/jquery.min.js"></script>
+		<script src="../../../../_components/jquery-syntax/jquery.syntax.min.js"></script>
+		<script type="text/javascript">
+		//<![CDATA[
+			jQuery(function($) {
+				$.syntax();
+			});
+		//]]>
+		</script>
+	</head>
+	<body class="">
+		<header>
+			<img src="../../../../_static/utopia.svg"/>
+		</header>
+		<div id="page">
+	<nav>
+	 › <a href="../../../../wiki.html">Wiki</a> › <span>Middleware</span> › <a href="../../controller.html">Controller</a> › <a href="../actions.html">Actions</a></nav>
+	<h1 id="controlleractions">Controller::Actions</h1>
+<p>Actions let you match path patterns in your controller and execute code. In your <code>controller.rb</code> simply add:</p>
+<pre><code class="language-ruby">prepend Actions
+</code></pre>
+<p>If you are adding multiple things, like rewriting, they should come earlier in the chain, e.g:</p>
+<pre><code class="language-ruby">prepend Rewrite, Actions
+</code></pre>
+<p>A simple CRUD controller might look like:</p>
+<pre><code class="language-ruby">prepend Actions
+on 'index' do
+	@users = User.all
+end
+on 'new' do |request|
+	@user = User.new
+	if request.post?
+		@user.update_attributes(request.params['user'])
+		redirect! "index"
+	end
+end
+on 'edit' do |request|
+	@user = User.find(request.params['id'])
+	if request.post?
+		@user.update_attributes(request.params['user'])
+		redirect! "index"
+	end
+end
+on 'delete' do |request|
+	User.find(request.params['id']).destroy
+	redirect! "index"
+end
+</code></pre>
+<h2 id="path-matching">Path Matching</h2>
+<p>Path matching works from right to left, and ‘**’ is a greedy operator. Controllers are invoked with a path relative to the controller’s <code>URI_PATH</code>, so all lookups are relative to the controller.</p>
+<dl>
+	<dt><code class="language-ruby">"*"</code></dt>
+	<dd>Match a single path element</dd>
+	<dt><code class="language-ruby">"**"</code></dt>
+	<dd>Match all remaining path elements</dd>
+	<dt><code class="language-ruby">String</code></dt>
+	<dd>Match a named path component, e.g. <code class="language-ruby">"edit"</code>.</dd>
+	<dt><code class="language-ruby">Symbol</code></dt>
+	<dd>Equivalent to <code class="language-ruby">["**", symbol.to_s]</code>, e.g. <code class="language-ruby">:logout</code>.</dd>
+</dl>
+<h2 id="otherwise-matching">Otherwise Matching</h2>
+<p>If no action was matched, it is sometimes useful to perform some specific behaviour. You can specify this by using the otherwise handler:</p>
+<pre><code class="language-ruby">otherwise do |request, path|
+	fail! :teapot
+end
+</code></pre>
+<p>If you are doing this to perform some kind of rewriting, it may be preferable to use the <a href="rewrite/index.html">Rewrite</a> controller layer.</p>
+	<footer>
+		Last Modified: 2017-05-03 14:21:19 +1200 —
+	</footer>
+		</div>
+	</body>
+</html>

data/docs/wiki/middleware/controller/actions/rewrite/index.html ADDED Viewed

@@ -0,0 +1,48 @@
+<!DOCTYPE html>
+<html>
+	<head>
+			<title>Rewrite - Utopia</title>
+		<meta charset="UTF-8"/>
+		<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-wvfXpqpZZVQGK6TAh5PVlGOfQNHSoD2xbE+QkPxCAFlNEevoEH3Sl0sibVcOQVnN" crossorigin="anonymous"/>
+		<link rel="icon" type="image/png" href="../../../../../_static/icon.png"/>
+		<link rel="stylesheet" href="../../../../../_static/site.css" type="text/css" media="screen"/>
+		<script src="../../../../../_components/jquery/jquery.min.js"></script>
+		<script src="../../../../../_components/jquery-syntax/jquery.syntax.min.js"></script>
+		<script type="text/javascript">
+		//<![CDATA[
+			jQuery(function($) {
+				$.syntax();
+			});
+		//]]>
+		</script>
+	</head>
+	<body class="">
+		<header>
+			<img src="../../../../../_static/utopia.svg"/>
+		</header>
+		<div id="page">
+	<nav>
+	 › <a href="../../../../../wiki.html">Wiki</a> › <span>Middleware</span> › <a href="../../../controller.html">Controller</a> › <a href="../../actions.html">Actions</a></nav>
+	<h1 id="rewrite">Rewrite</h1>
+<p>This page is empty.</p>
+	<footer>
+		Last Modified: N/A —
+	</footer>
+		</div>
+	</body>
+</html>

data/docs/wiki/middleware/controller/index.html ADDED Viewed

@@ -0,0 +1,104 @@
+<!DOCTYPE html>
+<html>
+	<head>
+			<title>Controller - Utopia</title>
+		<meta charset="UTF-8"/>
+		<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-wvfXpqpZZVQGK6TAh5PVlGOfQNHSoD2xbE+QkPxCAFlNEevoEH3Sl0sibVcOQVnN" crossorigin="anonymous"/>
+		<link rel="icon" type="image/png" href="../../../_static/icon.png"/>
+		<link rel="stylesheet" href="../../../_static/site.css" type="text/css" media="screen"/>
+		<script src="../../../_components/jquery/jquery.min.js"></script>
+		<script src="../../../_components/jquery-syntax/jquery.syntax.min.js"></script>
+		<script type="text/javascript">
+		//<![CDATA[
+			jQuery(function($) {
+				$.syntax();
+			});
+		//]]>
+		</script>
+	</head>
+	<body class="">
+		<header>
+			<img src="../../../_static/utopia.svg"/>
+		</header>
+		<div id="page">
+	<nav>
+	 › <a href="../../../wiki.html">Wiki</a> › <span>Middleware</span> › <a href="../controller.html">Controller</a></nav>
+	<h1 id="controller">Controller</h1>
+<p>A simple recursive controller layer which works in isolation from the view rendering middleware.</p>
+<pre><code class="language-ruby">use Utopia::Controller,
+	# The root directory where `controller.rb` files can be found.
+	root: 'path/to/root',
+	# The base class to use for all controllers:
+	base: Utopia::Controller::Base,
+	# Whether or not to cache controller classes:
+	cache_controllers: (RACK_ENV == :production)
+</code></pre>
+<p>A controller is a file within the root directory (or subdirectory) with the name <code>controller.rb</code>. This code is dynamically loaded into an anonymous class and executed. The default controller has only a single function:</p>
+<pre><code class="language-ruby">def passthrough(request, path)
+	# Call one of:
+	# This will cause the middleware to generate a response.
+	# def respond!(response)
+	# This will cause the controller to skip the request.
+	# def ignore!
+	# Request relative redirect. Respond with a redirect to the given target.
+	# def redirect! (target, status = 302)
+	# Controller relative redirect.
+	# def goto!(target, status = 302)
+	# Respond with an error which indiciates some kind of failure.
+	# def fail!(error = 400, message = nil)
+	# Succeed the request and immediately respond.
+	# def succeed!(status: 200, headers: {}, **options)
+	# options may include content: string or body: Enumerable (as per Rack specifications
+end
+</code></pre>
+<p>The controller layer can do more complex operations by prepending modules into it.</p>
+<pre><code class="language-ruby">prepend Rewrite, Actions
+# Extracts an Integer
+rewrite.extract_prefix id: Integer do
+	@user = User.find_by_id(@id)
+end
+on 'edit' do |request, path|
+	if request.post?
+		@user.update_attributes(request[:user])
+	end
+end
+otherwise do |request, path|
+	# Executed if no specific named actions were executed.
+	succeed!
+end
+</code></pre>
+	<footer>
+		Last Modified: 2016-12-13 12:38:35 +1300 —
+	</footer>
+		</div>
+	</body>
+</html>