mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-10-22 14:05:37 +02:00
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
parent
976f1f5da0
commit
9cfbe9b84f
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user