utopia 2.13.4 → 2.16.1

data/documentation/pages/wiki/content.md

@@ -1,35 +0,0 @@
-# Utopia Documentation Wiki
-
-This wiki includes documentation and examples showing how to use Utopia. You can also browse the [code documentation](/code/index.html) for more detail. Feel free to [edit](edit) any part of this documentation and submit a PR.
-
-## Introduction Guide
-
-Reading these pages in order will give you an overview of the design of Utopia, how to set it up for local development and how to deploy it.
-
-- [Development Environment Setup](development-environment-setup/)
-- [Server Setup](server-setup/)
-- [Your First Page](your-first-page/)
-  - [What is `.xnode`?](faq/what-is-xnode/)
-- [Installing JavaScript Libraries](javascript/)
-- [Website Tests](testing/)
-- [Updating Your Site](updating-utopia/)
-
-## Middleware
-
-The following are Rack Middleware which provide the core of Utopia.
-
-- [Static](middleware/static/) — Serve static files efficiently.
-- [Redirection](middleware/redirection/) — Redirect URL patterns and status codes.
-- [Localization](middleware/localization/) — Non-intrusive localization of resources.
-- [Controller](middleware/controller/) — Flexible nested controllers with efficient behaviour. 
-  - [Controller Actions](middleware/controller/actions/) — Invoke named actions.
-  - [Controller Rewrite](middleware/controller/rewrite/) — Pattern match requests.
-- [Content](middleware/content/) — XML-style template engine with dynamic markup.
-- [Session](middleware/session/) — Session storage using encrypted client-side cookies.
-
-## Examples
-
-Here are some open-source sites built on Utopia.
-
-- [www.codeotaku.com](http://www.codeotaku.com) ([source](https://github.com/ioquatix/www.codeotaku.com)) — Personal website, blog.
-- Financier ([source](https://github.com/ioquatix/financier)) — Small business management platform, invoicing.

data/documentation/pages/wiki/controller.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-prepend Actions
-
-on '**' do |request, path|
-	@full_path = URI_PATH + path
-	@page_path = path.components[0..-2]
-	
-	@page_file = File.join(BASE_PATH, @page_path, "content.md")
-	
-	if last_path_component = @page_path.last
-		@title = Trenni::Strings::to_title(last_path_component)
-	else
-		@title = "Wiki"
-	end
-end
-
-def read_contents
-	if File.exist? @page_file
-		File.read(@page_file)
-	else
-		"\# #{@title}\n\n" +
-		"This page is empty."
-	end
-end
-
-on '**/edit' do |request, path|
-	if request.post?
-		FileUtils.mkdir_p File.dirname(@page_file)
-		
-		# Get the content and normalize newlines:
-		content = request.params['content'].gsub /\r\n?/, "\n"
-		File.write(@page_file, content)
-		
-		# Redirect relative to controller.
-		goto! @page_path
-	else
-		@content = read_contents
-	end
-	
-	path.components = ["edit"]
-end
-
-on '**/index' do |request, path|
-	@content = read_contents
-	
-	path.components = ["show"]
-end

data/documentation/pages/wiki/development-environment-setup/content.md

@@ -1,16 +0,0 @@
-# Development Environment Setup
-
-Utopia is built on Ruby and Rack. Therefore, Ruby (suggested 2.0+) should be installed and working. Then, simply run:
-
-```bash
-$ gem install utopia
-```
-
-To install all required dependencies.
-
-Utopia and it's dependencies are built on Linux and Mac by default, and therefore compatibility with Windows is not guaranteed.
-
-## Atom Integration
-
-Utopia uses [Trenni](https://github.com/ioquatix/trenni) for templates and it has a syntax slightly different from ERB. However, there is a [package for Atom](https://atom.io/packages/language-trenni) which provides accurate syntax highlighting.
-

data/documentation/pages/wiki/edit.xnode

@@ -1,10 +0,0 @@
-<content:editor>
-	<form action="#" method="post">
-		<div class="header">
-			<div>Editing #{attributes[:title].inspect}</div>
-			<input type="submit" />
-		</div>
-		
-		<textarea name="content">#{self[:content]}</textarea>
-	</form>
-</content:editor>

data/documentation/pages/wiki/faq/what-is-xnode/content.md

@@ -1,37 +0,0 @@
-# What Is `.xnode`?
-
-Xnodes are the files on disk which are used as part of Utopia's content/view layer. Xnode templates are designed to maximise the ratio of content to markup. They improve separation of concerns and semantic organisation because repeated markup can be reused easily.
-
-Here is a example of a blog post:
-
-```xml
-<content:entry title="My day as a fish">
-	<p>It was not very exciting</p>
-</content:entry>
-```
-
-The `Utopia::Content` middleware is built on top of the [Trenni](https://github.com/ioquatix/trenni) template language which uses two-phase evaluation.
-
-## Phase 1: Evaluation
-
-Trenni processes the view content by evaluation `#{expressions}` and `<?r statements ?>`. This generates an output buffer. The output buffer should contain valid markup (i.e. balanced tags, no invalid characters).
-
-## Phase 2: Markup
-
-Once the template is evaluated to text, it is parsed again into an event stream which is used to generate the final output. The event stream contains things like "open tag", "attribute", "close tag", and so on, and these are fed into the `Utopia::Content` middleware which generates the actual content. Tags without namespaces are output verbatim, while tags with namespaces invoke the tag lookup machinery. This uses the tag name to invoke further behaviour, e.g. inserting more content. Here is a simple example of a basic page:
-
-```xml
-<content:page>
-	<content:heading>Welcome to my page</content:heading>
-
-	<p>This page is so awesome</p>
-</content:page>
-```
-
-In order to render this, you will need two additional files, `_page.xnode` and `_heading.xnode`. As a short example, `_heading.xnode` might look like this:
-
-```xml
-<h1><utopia:content/></h1>
-```
-
-When the parser encounters `<content:heading>...` in the main page, it would evaluate the above template. `<utopia:content/>` is a special tag that evaluates to the content that the parent tag provided, so in this case: `"Welcome to my page"`.  Thus, the final output is `<h1>Welcome to my page</h1>`.

data/documentation/pages/wiki/javascript/content.md

@@ -1,75 +0,0 @@
-# Yarn Integration
-
-Utopia integrates with Yarn and provides a rake task to simplify deployment packages distributed using `yarn` that implement the `dist` sub-directory convention.
-
-By default, utopia includes a `.yarnrc` file which installs modules into `lib/components`. This code can then be copied into `public/_components` using `rake yarn:update`.
-
-## Installing Yarn
-
-If you don't already have yarn installed, make sure you have npm installed and then run the following command:
-
-	$ sudo npm install -g yarn
-
-## Installing jQuery
-
-Firstly, ensure your project has a `package.json` file:
-
-	$ yarn init
-
-Then install jquery using `yarn`:
-
-	$ bower install jquery
-
-Copy the distribution scripts to `public/_components`:
-
-	$ rake yarn:update
-
-Then add the appropriate `<script>` tags to `pages/_page.xnode`:
-
-```html
-<script type="text/javascript" src="/_components/jquery/jquery.min.js"></script>
-```
-
-### What does `rake yarn:update` do?
-
-This task copies only the contents of the `dist` directory. This ensures that you only get files intended for distribution. If the bower package doesn't have a `dist` directory, the entire contents is copied.
-
-<content:listing rel="site" src="tasks/yarn.rake" brush="ruby" />
-
-## Using JavaScript
-
-You can use JavaScript by embedding it directly into your HTML, or by creating a JavaScript source file and referencing that.
-
-### Embedding Code
-
-In your HTML view:
-
-```trenni
-<html>
-  <body>
-    <script type="text/javascript">
-      //<![CDATA[
-      console.log("Hello World")
-      //]]>
-    </script>
-  </body>
-</html>
-```
-
-### External Script
-
-In `script.js`:
-
-```javascript
-console.log("Hello World")
-```
-
-In your HTML view:
-
-```trenni
-<html>
-  <body>
-    <script type="text/javascript" src="script.js"></script>
-  </body>
-</html>
-```

data/documentation/pages/wiki/links.yaml

@@ -1,6 +0,0 @@
-index:
-  title: Wiki
-faq:
-  title: FAQ
-javascript:
-  title: "JavaScript"

data/documentation/pages/wiki/middleware/content/content.md

@@ -1,21 +0,0 @@
-# Content
-A tag based content generation system which integrates nicely with HTML5. Supports structures which separate generic page templates from dynamically generated content in an easy and consistent way.
-
-```ruby
-use Utopia::Content,
-	cache_templates: (RACK_ENV == :production)
-```
-
-A basic template `create.xnode` looks something like:
-
-```trenni
-<content:page>
-	<content:heading>Create User</content:heading>
-	<form action="#">
-		<input name="name" />
-		<input type="submit" />
-	</form>
-</content:page>
-```
-
-This template would typically be designed with supporting `_page.xnode` and `_heading.xnode` in the same directory or, more typically, somewhere further up the directory hierarchy.

data/documentation/pages/wiki/middleware/controller/actions/content.md

@@ -1,76 +0,0 @@
-# Controller::Actions
-
-Actions let you match path patterns in your controller and execute code. In your `controller.rb` simply add:
-
-```ruby
-prepend Actions
-```
-
-If you are adding multiple things, like rewriting, they should come earlier in the chain, e.g:
-
-```ruby
-prepend Rewrite, Actions
-```
-
-A simple CRUD controller might look like:
-
-```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
-```
-	
-## Path Matching
-
-Path matching works from right to left, and '**' is a greedy operator. Controllers are invoked with a path relative to the controller's `URI_PATH`, so all lookups are relative to the controller.
-
-<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>
-
-## Otherwise Matching
-
-If no action was matched, it is sometimes useful to perform some specific behaviour. You can specify this by using the otherwise handler:
-
-```ruby
-otherwise do |request, path|
-	fail! :teapot
-end
-```
-
-If you are doing this to perform some kind of rewriting, it may be preferable to use the [Rewrite](rewrite/) controller layer.

data/documentation/pages/wiki/middleware/controller/content.md

@@ -1,62 +0,0 @@
-# Controller
-
-A simple recursive controller layer which works in isolation from the view rendering middleware.
-
-```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)
-```
-
-A controller is a file within the root directory (or subdirectory) with the name `controller.rb`. This code is dynamically loaded into an anonymous class and executed. The default controller has only a single function:
-
-```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
-```
-
-The controller layer can do more complex operations by prepending modules into it.
-
-```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
-```

data/documentation/pages/wiki/middleware/controller/links.yaml

@@ -1,4 +0,0 @@
-actions:
-  order: 1
-rewrite:
-  order: 2

data/documentation/pages/wiki/middleware/controller/rewrite/content.md

@@ -1,69 +0,0 @@
-# Controller::Rewrite
-
-The <code class="language-ruby">Controller::Rewrite</code> layer can match and rewrite requests before they processed. This allows you to handle URLs like `/post/15/view` or `/blog/123-pictures-of-my-cat` easily. The basic rewrite operation is to extract some part of the path and optionally executes a block. That means that the path is modified before being passed on to the next layer in the controller, and controller instance variables may be set.
-
-## Regular Expressions
-
-In your `controller.rb`:
-
-```ruby
-prepend Rewrite, Actions
-
-rewrite.extract_prefix permalink: /(?<id>\d+)-(?<title>.*)/ do |request, path, match|
-	# The rewrite matched, but there was no valid post, so we fail:
-	fail! unless @post = Post.find(@permalink[:id])
-	
-	# If the path matched, but there was no suffix, we make it default to the post action:
-	if match.post_match.empty?
-		match.post_match.components << "post"
-	end
-end
-
-on 'post' do
-	# You can do further processing here.
-	fail! unless @post.published?
-	
-	@comments = @post.comments.first(5)
-end
-
-on 'edit' do
-	# You can do further processing here.
-	fail! unless @current_user&.editor?
-end
-```
-
-In your `post.xnode`, as an example:
-
-```trenni
-<content:page>
-	<content:heading>Post #{attributes[:permalink][:id]} about #{attributes[:permalink][:title]}</content:heading>
-	
-	<p>#{attributes[:post].content}</p>
-</content:page>
-```
-
-Keep in mind, that URLs like `/123-pictures-of-my-cat/edit` will work as expected, and hit the `edit` action of the controller.
-
-## Restful Resources
-
-Similar to the above, if we were solely interested in IDs, we could do the following:
-
-```ruby
-prepend Rewrite, Actions
-
-rewrite.extract_prefix post_id: Integer do |request, path, match|
-	# The rewrite matched, but there was no valid post, so we fail:
-	fail! unless @post = Post.find(@post_id)
-	
-	# If the path matched, but there was no suffix, we make it default to the post action:
-	if match.post_match.empty?
-		match.post_match.components << "post"
-	end
-end
-```
-
-This will only match complete integers. Assuming this code is in `/blog/controller.rb`, it would match something like `/blog/123/view` and assign <code class="language-ruby">Integer("123")</code> to <code class="language-ruby">@post_id</code>.
-
-### Matching.. other things
-
-It's possible to match using <code class="language-ruby">Integer</code>, <code class="language-ruby">Float</code>, <code class="language-ruby">String</code>, and you can provide your own class which will be instantiated. If it doesn't match, raise an exception and the rewrite rule will fail.