Skip to content

Commit

Permalink
MINOR: update core controller template with more help information.
Browse files Browse the repository at this point in the history 
Updated controller and director documentation to reflect the new YAML configuration for route path definition.
  • Loading branch information
@wilr
wilr committed Jun 30, 2012
1 parent 976f1f5 commit 9cfbe9b
Show file tree
Hide file tree
Showing 3 changed files with 120 additions and 66 deletions.
88 changes: 55 additions & 33 deletions docs/en/reference/director.md
View file
Expand Up @@ -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
Expand Down
55 changes: 33 additions & 22 deletions docs/en/topics/controller.md
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
Expand All @@ -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
Expand All @@ -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 |
| ----------- | --------------- |
Expand Down Expand Up @@ -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.
Expand Down
43 changes: 32 additions & 11 deletions templates/Controller.ss
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>

0 comments on commit 9cfbe9b

Please sign in to comment.