Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

MINOR: update core controller template with more help information.

Updated controller and director documentation to reflect the new YAML configuration for route path definition.
  • Loading branch information...
commit 9cfbe9b84f2d5bfcafe2c1eb363ed02bf147c3a2 1 parent 976f1f5
@wilr wilr authored
View
88 docs/en/reference/director.md
@@ -2,58 +2,80 @@
## Introduction
-`[api:Director]` is the first step in the "execution pipeline". It parses the URL, matching it to one of a number of patterns,
-and determines the controller, action and any argument to be used. It then runs the controller, which will finally run
-the viewer and/or perform processing steps.
-
-## Best Practices
-
-* Checking for an Ajax-Request: Use Director::is_ajax() instead of checking for $_REQUEST['ajax'].
-
+`[api:Director]` is the first step in the "execution pipeline". It parses the
+URL, matching it to one of a number of patterns, and determines the controller,
+action and any argument to be used. It then runs the controller, which will
+finally run the viewer and/or perform processing steps.
## Request processing
-The `[api:Director]` is the entry point in Silverstring Framework for processing a request. You can read through
-the execution steps in `[api:Director]``::direct()`, but in short
+The `[api:Director]` is the entry point in Silverstring Framework for processing
+a request. You can read through the execution steps in `[api:Director]``::direct()`,
+but in short
-* File uploads are first analysed to remove potentially harmful uploads (this will likely change!)
+* File uploads are first analysed to remove potentially harmful uploads (this
+will likely change!)
* The `[api:SS_HTTPRequest]` object is created
* The session object is created
-* The `[api:Injector]` is first referenced, and asks the registered `[api:RequestProcessor]` to pre-process
- the request object. This allows for analysis of the current request, and allow filtering of parameters
- etc before any of the core of the application executes
+* The `[api:Injector]` is first referenced, and asks the registered `[api:RequestProcessor]`
+to pre-process the request object. This allows for analysis of the current
+request, and allow filtering of parameters etc before any of the core of the
+application executes.
* The request is handled and response checked
-* The `[api:RequestProcessor]` is called to post-process the request to allow further filtering before
- content is sent to the end user.
+* The `[api:RequestProcessor]` is called to post-process the request to allow
+further filtering before content is sent to the end user
* The response is output
-The framework provides the ability to hook into the request both before and after it is handled to allow
-developers to bind in their own custom pre- or post- request logic; see the `[api:RequestFilter]` to see how
-this can be used to authenticate the request before the request is handled.
+The framework provides the ability to hook into the request both before and
+after it is handled to allow developers to bind in their own custom pre- or
+post- request logic; see the `[api:RequestFilter]` to see how this can be used
+to authenticate the request before the request is handled.
+
+## Routing
-## Custom Rewrite Rules
+You can influence the way URLs are resolved in the following ways
-You can influence the way URLs are resolved one of 2 ways
+1. Adding rules to `[api:Director]` in `<yourproject>/_config/routes.yml`
+2. Adding rules to `[api:Director]` in `<yourproject>/_config.php (deprecated)
+3. Adding rules in your extended `[api:Controller]` class via the *$url_handlers*
+static variable
-1. Adding rules to `[api:Director]` in `<yourproject>/_config.php` (See Default Rewrite Rules below for examples)
-2. Adding rules in your extended `[api:Controller]` class via the *$url_handlers* static variable
+See [controller](/topics/controller) for examples and explanations on how the
+rules get processed for those methods.
-See [controller](/topics/controller) for examples and explanations on how the rules get processed for both 1 and 2 above.
-* Static redirect for specific URL
+### Routing Rules
- :::php
- Director::addRules(100, array(
- 'myPermanentRedirect' => 'redirect:http://www.mysite.com'
- ));
+SilverStripe comes with certain rules which map a URI to a `[api:Controller]`
+class (e.g. *dev/* -> DevelopmentAdmin). These routes are either stored in
+a routes.yml configuration file located a `_config` directory or inside a
+`_config.php` file (deprecated).
+To add your own custom routes for your application create a routes.yml file
+in `<yourproject>/_config/routes.yml` with the following format:
-## Default Rewrite Rules
+ :::yaml
+ ---
+ Name: customroutes
+ After: framework/routes#coreroutes
+ ---
+ Director:
+ rules:
+ 'subscriptions/$Action' : 'SubscriptionController'
-SilverStripe comes with certain rewrite rules (e.g. for *admin/assets*).
+The [Controller](/topics/controller) documentation has a wide range of examples
+and explanations on how the rules get processed for those methods.
+
+See:
+
+* [framework/_config/routes.yml](https://github.com/silverstripe/sapphire/blob/master/_config/routes.yml)
+* [cms/_config/routes.yml](https://github.com/silverstripe/silverstripe-cms/blob/master/_config/routes.yml)
+
+
+## Best Practices
-* [framework/_config.php](https://github.com/silverstripe/sapphire/blob/master/_config.php)
-* [cms/_config.php](https://github.com/silverstripe/silverstripe-cms/blob/master/_config.php)
+* Checking for an Ajax-Request: Use Director::is_ajax() instead of checking
+for $_REQUEST['ajax'].
## Links
View
55 docs/en/topics/controller.md
@@ -1,11 +1,14 @@
# Controller
-Base controller class. You will extend this to take granular control over the actions and url handling of aspects of
-your SilverStripe site.
-
+Base controller class. You will extend this to take granular control over the
+actions and url handling of aspects of your SilverStripe site.
## Example
+The following example is for a simple `[api:Controller]` class. If you're using
+the cms module and looking at Page_Controller instances you won't need to setup
+your own routes since the cms module handles these routes.
+
`mysite/code/Controllers/FastFood.php`
:::php
@@ -16,18 +19,22 @@ your SilverStripe site.
print_r($arguments);
}
}
-
- ?>
-
-`mysite/_config.php`
+`mysite/_config/routes.yml`
- :::php
- Director::addRules(50, array('fastfood/$Action/$ID/$Name' => 'FastFood_Controller'));
+ :::yaml
+ ---
+ Name: myroutes
+ After: framework/routes#coreroutes
+ ---
+ Director:
+ rules:
+ 'fastfood/$Action/$ID/$Name': 'FastFood_Controller'
-Request for `/fastfood/order/24/cheesefries` would result in the following to the $arguments above. If needed, use
-`?flush=1` on the end of request after making any code changes to your controller.
+Request for `/fastfood/order/24/cheesefries` would result in the following to
+the $arguments above. If needed, use `?flush=1` on the end of request after
+making any code changes to your controller.
:::ss
Array
@@ -40,28 +47,31 @@ Request for `/fastfood/order/24/cheesefries` would result in the following to th
## URL Handling
-In the above example the URLs were configured using the `[api:Director]` rules in the **_config.php** file.
-Alternatively you can specify these in your Controller class via the **$url_handlers** static array (which gets
-processed by the `[api:RequestHandler]`).
+In the above example the URLs were configured using the `[api:Director]` rules
+in the **routes.yml** file. Alternatively you can specify these in your
+Controller class via the **$url_handlers** static array (which gets processed
+by the `[api:RequestHandler]`).
-This is useful when you want to subvert the fixed action mapping of `fastfood/order/*` to the function **order**. In
-the case below we also want any orders coming through `/fastfood/drivethrough/` to use the same order function.
+This is useful when you want to subvert the fixed action mapping of `fastfood/order/*`
+to the function **order**. In the case below we also want any orders coming
+through `/fastfood/drivethrough/` to use the same order function.
`mysite/code/Controllers/FastFood.php`
:::php
class FastFood_Controller extends Controller {
+
public static $url_handlers = array(
- 'drivethrough/$Action/$ID/$Name' => 'order'
- );
-
-
+ 'drivethrough/$Action/$ID/$Name' => 'order'
+ );
## URL Patterns
-The `[api:RequestHandler]` class will parse all rules you specify against the following patterns.
+The `[api:RequestHandler]` class will parse all rules you specify against the
+following patterns.
-**A rule must always start with alphabetical ([A-Za-z]) characters or a $Variable declaration**
+**A rule must always start with alphabetical ([A-Za-z]) characters or a $Variable
+declaration**
| Pattern | Description |
| ----------- | --------------- |
@@ -91,6 +101,7 @@ You can use the `debug_request=1` switch from the [urlvariabletools](/reference/
## Redirection
Controllers facilitate HTTP redirection.
+
Note: These methods have been formerly located on the `[api:Director]` class.
* `redirect("action-name")`: If there's no slash in the URL passed to redirect, then it is assumed that you want to go to a different action on the current controller.
View
43 templates/Controller.ss
@@ -1,22 +1,43 @@
<!DOCTYPE html>
<html lang="en">
-
<head>
<meta charset="utf-8">
<% base_tag %>
$MetaTags
+
+ <% require css('framework/css/debug.css') %>
</head>
<body>
- <h1><% if $Title %>$Title<% else %>Welcome to SilverStripe<% end_if %></h1>
- <% if $Content %>$Content<% else %>
- <p>To get started with the SilverStripe framework:</p>
- <ol>
- <li>Create a <code>Controller</code> subclass (<a href="http://doc.silverstripe.org/sapphire/en/topics/controller">doc.silverstripe.org/sapphire/en/topics/controller</a>)</li>
- <li>Setup the routes to your <code>Controller</code>.</li>
- <li>Create a template for your <code>Controller</code> (<a href="http://doc.silverstripe.org/sapphire/en/trunk/reference/templates">doc.silverstripe.org/sapphire/en/trunk/reference/templates</a>)</li>
- </ol>
- <% end_if %>
- <p><em>Generated with the default Controller.ss template.</em></p>
+ <div class="info">
+ <h1><% if $Title %>$Title<% else %>Welcome to SilverStripe<% end_if %></h1>
+ <h3>Generated with the default Controller.ss template</h3>
+ </div>
+
+ <div class="options">
+ <% if $Content %>$Content<% else %>
+ <h3>Getting Started</h3>
+
+ <p>To get started with the SilverStripe framework:</p>
+ <ol>
+ <li>Create a <code>Controller</code> subclass (<a href="http://doc.silverstripe.org/sapphire/en/topics/controller">doc.silverstripe.org/sapphire/en/topics/controller</a>)</li>
+ <li>Setup the routes.yml f to your <code>Controller</code> (<a href="http://doc.silverstripe.org/framework/en/reference/director#routing">doc.silverstripe.org/framework/en/reference/director#routing</a>).</li>
+ <li>Create a template for your <code>Controller</code> (<a href="http://doc.silverstripe.org/sapphire/en/reference/templates">doc.silverstripe.org/sapphire/en/reference/templates</a>)</li>
+ </ol>
+ <% end_if %>
+
+ <h3>Community resources</h3>
+
+ <ul>
+ <li>
+ <p><a href="http://silverstripe.org/forum">silverstripe.org/forum</a> Discussion forums for the development community.</p>
+ </li>
+ <li><p><a href="http://silverstripe.org/irc">silverstripe.org/irc</a> IRC channel for realtime support and discussions.</p></li>
+
+ <li><p><a href="http://doc.silverstripe.org">doc.silverstripe.org</a> Searchable developer documentation, how-tos, tutorials, and reference.</p></li>
+
+ <li><p><a href="http://api.silverstripe.org">api.silverstripe.org</a> API documentation for PHP classes, methods and properties.</p></li>
+ <ul>
+ </div>
</body>
</html>
Please sign in to comment.
Something went wrong with that request. Please try again.