MINOR: update core controller template with more help information.

Updated controller and director documentation to reflect the new YAML configuration for route path definition.
This commit is contained in:
Will Rossiter 2012-06-30 15:19:36 +12:00
parent 976f1f5da0
commit 9cfbe9b84f
3 changed files with 124 additions and 70 deletions

View File

@ -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.
## Custom Rewrite Rules
## Routing
You can influence the way URLs are resolved one of 2 ways
You can influence the way URLs are resolved in the following ways
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
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
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
:::php
Director::addRules(100, array(
'myPermanentRedirect' => 'redirect:http://www.mysite.com'
));
See [controller](/topics/controller) for examples and explanations on how the
rules get processed for those methods.
## Default Rewrite Rules
### Routing Rules
SilverStripe comes with certain rewrite rules (e.g. for *admin/assets*).
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).
* [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)
To add your own custom routes for your application create a routes.yml file
in `<yourproject>/_config/routes.yml` with the following format:
:::yaml
---
Name: customroutes
After: framework/routes#coreroutes
---
Director:
rules:
'subscriptions/$Action' : 'SubscriptionController'
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
* Checking for an Ajax-Request: Use Director::is_ajax() instead of checking
for $_REQUEST['ajax'].
## Links

View File

@ -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/routes.yml`
:::yaml
---
Name: myroutes
After: framework/routes#coreroutes
---
Director:
rules:
'fastfood/$Action/$ID/$Name': 'FastFood_Controller'
`mysite/_config.php`
:::php
Director::addRules(50, array('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 File

@ -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>