From 9cfbe9b84f2d5bfcafe2c1eb363ed02bf147c3a2 Mon Sep 17 00:00:00 2001 From: Will Rossiter Date: Sat, 30 Jun 2012 15:19:36 +1200 Subject: [PATCH] MINOR: update core controller template with more help information. Updated controller and director documentation to reflect the new YAML configuration for route path definition. --- docs/en/reference/director.md | 92 ++++++++++++++++++++++------------- docs/en/topics/controller.md | 59 +++++++++++++--------- templates/Controller.ss | 43 +++++++++++----- 3 files changed, 124 insertions(+), 70 deletions(-) diff --git a/docs/en/reference/director.md b/docs/en/reference/director.md index 7cc954224..87303e13c 100644 --- a/docs/en/reference/director.md +++ b/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. -## 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 `/_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 `/_config/routes.yml` +2. Adding rules to `[api:Director]` in `/_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 `/_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 diff --git a/docs/en/topics/controller.md b/docs/en/topics/controller.md index 1b1edf45f..633a14216 100644 --- a/docs/en/topics/controller.md +++ b/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/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. diff --git a/templates/Controller.ss b/templates/Controller.ss index 3d787bea1..1dbe67c53 100644 --- a/templates/Controller.ss +++ b/templates/Controller.ss @@ -1,22 +1,43 @@ - <% base_tag %> $MetaTags + + <% require css('framework/css/debug.css') %> -

<% if $Title %>$Title<% else %>Welcome to SilverStripe<% end_if %>

- <% if $Content %>$Content<% else %> -

To get started with the SilverStripe framework:

-
    -
  1. Create a Controller subclass (doc.silverstripe.org/sapphire/en/topics/controller)
    2. -
  2. Setup the routes to your Controller.
    3. -
  3. Create a template for your Controller (doc.silverstripe.org/sapphire/en/trunk/reference/templates)
    4. -
- <% end_if %> -

Generated with the default Controller.ss template.

+
+

<% if $Title %>$Title<% else %>Welcome to SilverStripe<% end_if %>

+

Generated with the default Controller.ss template

+
+ +
+ <% if $Content %>$Content<% else %> +

Getting Started

+ +

To get started with the SilverStripe framework:

+
    +
  1. Create a Controller subclass (doc.silverstripe.org/sapphire/en/topics/controller)
    2. +
  2. Setup the routes.yml f to your Controller (doc.silverstripe.org/framework/en/reference/director#routing).
    3. +
  3. Create a template for your Controller (doc.silverstripe.org/sapphire/en/reference/templates)
    4. +
+ <% end_if %> + +

Community resources

+ +