utopia 2.15.1 → 2.16.0

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

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

data/wiki/pages/middleware/controller/rewrite/index.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.

data/wiki/pages/middleware/localization/index.md

@@ -1,16 +0,0 @@
-# Localization
-
-The localization middleware uses the `Accept-Language` header to guess the preferred locale out of the given options. If a request path maps to a resource, that resource is returned. Otherwise, a localized request is made.
-
-```ruby
-use Utopia::Localization,
-	:default_locale => 'en',
-	:locales => ['en', 'de', 'ja', 'zh']
-```
-
-Somewhere further down the chain, you can localize a resource:
-
-```ruby
-localization = Utopia::Localization[request]
-show_welcome(localization.current_locale)
-```

data/wiki/pages/middleware/redirection/index.md

@@ -1,17 +0,0 @@
-# Redirection
-
-A set of flexible URI rewriting middleware which includes support for string mappings, regular expressions and status codes (e.g. 404 errors).
-
-```ruby
-# String (fast hash lookup) rewriting:
-use Utopia::Redirection::Rewrite,
-	'/' => '/welcome/index'
-
-# Redirect directories (e.g. /) to an index file (e.g. /index):
-use Utopia::Redirection::DirectoryIndex,
-	index: 'index.html'
-
-# Redirect (error) status codes to actual pages:
-use Utopia::Redirection::Errors,
-	404 => '/errors/file-not-found'
-```

data/wiki/pages/middleware/session/index.md

@@ -1,29 +0,0 @@
-# Session
-
-The session management uses symmetric private key encryption to store data on the client and avoid tampering.
-
-```ruby
-use Utopia::Session,
-	:expires_after => 3600,
-	:secret => '40 or more random characters for your secret key'
-```
-
-All session data is stored on the client, but it's encrypted with a salt and the secret key. It would be hard for the client to decrypt the data without the secret.
-
-## Using `environment.yaml`
-
-The session secret should not be shared or ideally, not stored in source code. This can be easily achieved using an environment variable, stored in `environment.yaml` on the production server:
-
-```ruby
-use Utopia::Session,
-	:expires_after => 3600,
-	:secret => ENV['UTOPIA_SESSION_SECRET']
-```
-
-In development, the secret would be reset every time the server is restarted. To set a fixed secret on production, run the following:
-
-```bash
-$ utopia server environment UTOPIA_SESSION_SECRET=$(head /dev/urandom | shasum | base64 | head -c 40)
-```
-
-This is done by default when using `utopia server create` and `utopia server update`.

data/wiki/pages/middleware/static/index.md

@@ -1,13 +0,0 @@
-# Static
-
-This middleware serves static files using the `mime-types` library. By default, it works with `Rack::Sendfile` and supports `ETag` based caching. Normally, you'd prefer to put static files into `public/_static` but it's also acceptable to put static content into `pages/` if it makes sense.
-
-```ruby
-use Utopia::Static,
-	# The root path to serve files from:
-	root: "path/to/root",
-	# The mime-types to recognize/serve:
-	types: [:default, :xiph],
-	# Cache-Control header for files:
-	cache_control: 'public, max-age=7200'
-```

data/wiki/pages/server-setup/index.md

@@ -1,52 +0,0 @@
-# Server Setup
-
-Utopia is designed to make deployment to remote servers easy.
-
-## Deployment
-
-The preferred method of deployment to a production server is via git. The `utopia` command assists with setup of a remote git repository on the server. It will setup a `git` `post-update` hook which will deploy the site correctly and restart the application server for that site.
-
-To setup a server for deployment:
-
-```bash
-$ mkdir /srv/http/www.example.com
-$ cd /srv/http/www.example.com
-$ sudo -u http utopia server create
-```
-
-On your development machine, you should setup the git remote:
-
-```bash
-$ git remote add production ssh://remote/srv/http/www.example.com
-$ git push --set-upstream production master
-```
-
-### Default Environment
-
-Utopia will load `config/environment.yaml` and update `ENV` before executing any code. You can set default environment values using the `utopia` command:
-
-```bash
-$ sudo -u http utopia environment RACK_ENV=production DATABASE_ENV=production_cluster_primary
-ENV["RACK_ENV"] will default to "production" unless otherwise specified.
-ENV["DATABASE_ENV"] will default to "production_cluster_primary" unless otherwise specified.
-```
-
-To set a value, write `KEY=VALUE`. To unset a key, write `KEY`.
-
-When you run `rake` tasks or spawn a server, the values in `config/environment.yaml` will be the defaults. You can override them by manually specifying them, e.g. `DATABASE_ENV=development rake db:info`.
-
-## Platform
-
-The best deployment platform for Utopia is Linux, using [falcon](https://github.com/socketry/falcon).
-
-### Sudo Setup
-
-Create a file `/etc/sudoers.d/http` with the following contents:
-
-```sudoers
-# Allow user samuel to check out code as user http using git:
-%wheel ALL=(http) NOPASSWD: ALL
-```
-
-This allows the deploy task to correctly checkout code as user `http`.
-

data/wiki/pages/testing/index.md

@@ -1,15 +0,0 @@
-# Testing
-
-Utopia websites include a default set of tests, and associated `rake test` tasks. These specs can test against the actual running website. By default, [covered](https://github.com/socketry/covered) is included for coverage testing.
-
-```bash
-$ rake coverage test
-
-my website
-	should have an accessible front page
-
-Finished in 0.44849 seconds (files took 0.15547 seconds to load)
-1 example, 0 failures
-
-Coverage report generated for RSpec. 5 / 5 LOC (100.0%) covered.
-```

data/wiki/pages/updating-utopia/index.md

@@ -1,63 +0,0 @@
-# Updating Utopia
-
-Utopia provides a model for both local development (`utopia site create`) and deployment (`utopia server create`). In addition, Utopia provides a basic upgrade path for existing sites when things within the framework change. These are not always automatic, so below are some recipes for how to update your site.
-
-## Site Update
-
-Utopia as a framework introduces changes and versions change according to semantic versioning. 
-
-### Controller Update 1.9.x to 2.x
-
-The controller layer no longer automatically prepends the `Actions` layer. The following program does a best effort attempt to update existing controllers:
-
-```ruby
-#!/usr/bin/env ruby
-
-paths = Dir.glob("**/controller.rb")
-
-paths.each do |path|
-	lines = File.readlines(path)
-	
-	prepend_line_index = lines.first(5).find_index{|line| line =~ /prepend/}
-	
-	unless prepend_line_index
-		puts "Updating #{path}.."
-		File.open(path, "w") do |file|
-			file.puts "\nprepend Actions"
-			file.write lines.join
-		end
-	else
-		prepend_line = lines[prepend_line_index]
-		
-		unless prepend_line =~ /Actions/
-			if lines.any?{|line| line =~ /on/}
-				lines[prepend_line_index] = "#{prepend_line.chomp}, Actions\n"
-				
-				puts "Updating #{path}.."
-				File.open(path, "w") do |file|
-					file.write lines.join
-				end
-			end
-		end
-	end
-end
-```
-
-### View Update 1.9.x to 2.x
-
-Dynamic tags in 2.x require namespaces. This affects all `.xnode` files, in particular the following 3 cases:
-
-1. Rewrite `<(/?)(NAME)(\W)` to `<$1content:$2$3` where NAME is a tag which would expand using a `_NAME.xnode` file.
-2. Rewrite `<content/>` to `<utopia:content/>`. This affects `<node>`, `<deferred>`, `<environment>` tags.
-3. Rewrite `partial 'NAME'` to be `partial 'content:NAME'`.
-
-## Server Update
-
-The utopia server git hooks are updated occasionally to improve the deployment process or to handle changes in the underlying process.
-
-You can run the update process on the server to bring the git hooks up to the latest version.
-
-```bash
-$ cd /srv/http/website
-$ utopia server update
-```

data/wiki/pages/your-first-page/index.md

@@ -1,38 +0,0 @@
-# Your First Page
-
-To setup the default site, simply create a directory and use the `utopia` command:
-
-```bash
-$ mkdir www.example.com
-$ cd www.example.com
-$ utopia site create
-$ rake server
-```
-
-You will now have a basic template site running on `https://localhost:9292`.
-
-## Welcome Page
-
-Utopia includes a redirection middleware to redirect all root-level requests to a given URI. The default being `/welcome/index`:
-
-```ruby
-# in config.ru
-
-use Utopia::Redirection::Rewrite,
-	'/' => '/welcome/index'
-```
-
-This page includes a basic overview of Utopia. Most of it's standard HTML, except for the outer `<content:page>` tag. Utopia uses the name `page` to lookup the file-system hierarchy. First, it looks for `/welcome/_page.xnode`, and then it looks for `/_page.xnode` which it finds. This page template includes a tag `<utopia:content/>` which is replaced with the inner body of the `<content:page>` tag. This recursive lookup is the heart of Utopia.
-
-## Links
-
-Utopia is a content-centric web application platform. It leverages the file-system to provide a mapping between logical resources and files on disk. The primary mode of mapping incoming requests to specific nodes (content) is done using the `links.yaml` file.
-
-The links file associates metadata with node names for a given directory. This can include things like redirects, titles, descriptions, etc. You can add any metadata you like, to support your specific use-case. The primary use of the links files is to provide site structure, e.g. menus. In addition, they can function as a rudimentary data-store for static information, e.g. a list of applications (each with it's own page), a list of features, etc.
-
-You'll notice that there is a file `/links.yaml`. This file contains important metadata relating to the `errors` subdirectory. As we don't want these nodes showing up in a top level menu, we mark them as `display: false`
-
-```yaml
-errors:
-  display: false 
-```