Skip to content
This repository
Browse code

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
Will Rossiter authored June 30, 2012
88  docs/en/reference/director.md
Source Rendered
@@ -2,58 +2,80 @@
2 2
 
3 3
 ## Introduction
4 4
 
5  
-`[api:Director]` is the first step in the "execution pipeline". It parses the URL, matching it to one of a number of patterns,
6  
-and determines the controller, action and any argument to be used. It then runs the controller, which will finally run
7  
-the viewer and/or perform processing steps.
8  
-
9  
-## Best Practices
10  
-
11  
-*  Checking for an Ajax-Request: Use Director::is_ajax() instead of checking for $_REQUEST['ajax'].
12  
-
  5
+`[api:Director]` is the first step in the "execution pipeline". It parses the 
  6
+URL, matching it to one of a number of patterns, and determines the controller, 
  7
+action and any argument to be used. It then runs the controller, which will 
  8
+finally run the viewer and/or perform processing steps.
13 9
 
14 10
 ## Request processing
15 11
 
16  
-The `[api:Director]` is the entry point in Silverstring Framework for processing a request. You can read through
17  
-the execution steps in `[api:Director]``::direct()`, but in short
  12
+The `[api:Director]` is the entry point in Silverstring Framework for processing 
  13
+a request. You can read through the execution steps in `[api:Director]``::direct()`, 
  14
+but in short
18 15
 
19  
-* File uploads are first analysed to remove potentially harmful uploads (this will likely change!)
  16
+* File uploads are first analysed to remove potentially harmful uploads (this 
  17
+will likely change!)
20 18
 * The `[api:SS_HTTPRequest]` object is created
21 19
 * The session object is created
22  
-* The `[api:Injector]` is first referenced, and asks the registered `[api:RequestProcessor]` to pre-process
23  
-  the request object. This allows for analysis of the current request, and allow filtering of parameters
24  
-  etc before any of the core of the application executes
  20
+* The `[api:Injector]` is first referenced, and asks the registered `[api:RequestProcessor]` 
  21
+to pre-process the request object. This allows for analysis of the current 
  22
+request, and allow filtering of parameters etc before any of the core of the 
  23
+application executes.
25 24
 * The request is handled and response checked
26  
-* The `[api:RequestProcessor]` is called to post-process the request to allow further filtering before
27  
-  content is sent to the end user. 
  25
+* The `[api:RequestProcessor]` is called to post-process the request to allow 
  26
+further filtering before content is sent to the end user
28 27
 * The response is output
29 28
 
30  
-The framework provides the ability to hook into the request both before and after it is handled to allow
31  
-developers to bind in their own custom pre- or post- request logic; see the `[api:RequestFilter]` to see how
32  
-this can be used to authenticate the request before the request is handled. 
  29
+The framework provides the ability to hook into the request both before and 
  30
+after it is handled to allow developers to bind in their own custom pre- or 
  31
+post- request logic; see the `[api:RequestFilter]` to see how this can be used 
  32
+to authenticate the request before the request is handled. 
  33
+
  34
+## Routing
33 35
 
34  
-## Custom Rewrite Rules
  36
+You can influence the way URLs are resolved in the following ways
35 37
 
36  
-You can influence the way URLs are resolved one of 2 ways
  38
+1. Adding rules to `[api:Director]` in `<yourproject>/_config/routes.yml` 
  39
+2. Adding rules to `[api:Director]` in `<yourproject>/_config.php (deprecated)
  40
+3. Adding rules in your extended `[api:Controller]` class via the *$url_handlers* 
  41
+static variable 
37 42
 
38  
-1.  Adding rules to `[api:Director]` in `<yourproject>/_config.php` (See Default Rewrite Rules below for examples)
39  
-2.  Adding rules in your extended `[api:Controller]` class via the *$url_handlers* static variable 
  43
+See [controller](/topics/controller) for examples and explanations on how the 
  44
+rules get processed for those methods.
40 45
 
41  
-See [controller](/topics/controller) for examples and explanations on how the rules get processed for both 1 and 2 above. 
42 46
 
43  
-*  Static redirect for specific URL
  47
+### Routing Rules
44 48
 
45  
-	:::php
46  
-	Director::addRules(100, array(
47  
-	'myPermanentRedirect' => 'redirect:http://www.mysite.com'
48  
-	));
  49
+SilverStripe comes with certain rules which map a URI to a `[api:Controller]`
  50
+class (e.g. *dev/* -> DevelopmentAdmin). These routes are either stored in 
  51
+a routes.yml configuration file located a `_config` directory or inside a 
  52
+`_config.php` file (deprecated). 
49 53
 
  54
+To add your own custom routes for your application create a routes.yml file 
  55
+in `<yourproject>/_config/routes.yml` with the following format:
50 56
 
51  
-## Default Rewrite Rules
  57
+	:::yaml
  58
+	---
  59
+	Name: customroutes
  60
+	After: framework/routes#coreroutes
  61
+	---
  62
+	Director:
  63
+  		rules:
  64
+    		'subscriptions/$Action' : 'SubscriptionController'
52 65
 
53  
-SilverStripe comes with certain rewrite rules (e.g. for *admin/assets*).
  66
+The [Controller](/topics/controller) documentation has a wide range of examples 
  67
+and explanations on how the rules get processed for those methods.
  68
+
  69
+See:
  70
+
  71
+*  [framework/_config/routes.yml](https://github.com/silverstripe/sapphire/blob/master/_config/routes.yml)
  72
+*  [cms/_config/routes.yml](https://github.com/silverstripe/silverstripe-cms/blob/master/_config/routes.yml)
  73
+
  74
+
  75
+## Best Practices
54 76
 
55  
-*  [framework/_config.php](https://github.com/silverstripe/sapphire/blob/master/_config.php)
56  
-*  [cms/_config.php](https://github.com/silverstripe/silverstripe-cms/blob/master/_config.php)
  77
+*  Checking for an Ajax-Request: Use Director::is_ajax() instead of checking 
  78
+for $_REQUEST['ajax'].
57 79
 
58 80
 
59 81
 ## Links
55  docs/en/topics/controller.md
Source Rendered
... ...
@@ -1,11 +1,14 @@
1 1
 # Controller
2 2
 
3  
-Base controller class.  You will extend this to take granular control over the actions and url handling of aspects of
4  
-your SilverStripe site.
5  
-
  3
+Base controller class.  You will extend this to take granular control over the 
  4
+actions and url handling of aspects of your SilverStripe site.
6 5
 
7 6
 ## Example
8 7
 
  8
+The following example is for a simple `[api:Controller]` class. If you're using
  9
+the cms module and looking at Page_Controller instances you won't need to setup
  10
+your own routes since the cms module handles these routes.
  11
+
9 12
 `mysite/code/Controllers/FastFood.php`
10 13
 
11 14
 	:::php
@@ -16,18 +19,22 @@ your SilverStripe site.
16 19
 	        print_r($arguments);
17 20
 	    }
18 21
 	}
19  
-	
20  
-	?>
21  
-
22 22
 
23  
-`mysite/_config.php`
  23
+`mysite/_config/routes.yml`
24 24
 
25  
-	:::php
26  
-	Director::addRules(50, array('fastfood/$Action/$ID/$Name' => 'FastFood_Controller'));
  25
+	:::yaml
  26
+	---
  27
+	Name: myroutes
  28
+	After: framework/routes#coreroutes
  29
+	---
  30
+	Director:
  31
+  		rules:
  32
+    		'fastfood/$Action/$ID/$Name': 'FastFood_Controller'
27 33
 
28 34
 
29  
-Request for `/fastfood/order/24/cheesefries` would result in the following to the $arguments above. If needed, use
30  
-`?flush=1` on the end of request after making any code changes to your controller.
  35
+Request for `/fastfood/order/24/cheesefries` would result in the following to 
  36
+the $arguments above. If needed, use `?flush=1` on the end of request after 
  37
+making any code changes to your controller.
31 38
 
32 39
 	:::ss
33 40
 	Array
@@ -40,28 +47,31 @@ Request for `/fastfood/order/24/cheesefries` would result in the following to th
40 47
 
41 48
 ## URL Handling
42 49
 
43  
-In the above example the URLs were configured using the `[api:Director]` rules in the **_config.php** file. 
44  
-Alternatively you can specify these in your Controller class via the **$url_handlers** static array (which gets
45  
-processed by the `[api:RequestHandler]`).  
  50
+In the above example the URLs were configured using the `[api:Director]` rules 
  51
+in the **routes.yml** file. Alternatively you can specify these in your 
  52
+Controller class via the **$url_handlers** static array (which gets processed 
  53
+by the `[api:RequestHandler]`).  
46 54
 
47  
-This is useful when you want to subvert the fixed action mapping of `fastfood/order/*` to the function **order**.  In
48  
-the case below we also want any orders coming through `/fastfood/drivethrough/` to use the same order function.
  55
+This is useful when you want to subvert the fixed action mapping of `fastfood/order/*` 
  56
+to the function **order**. In the case below we also want any orders coming 
  57
+through `/fastfood/drivethrough/` to use the same order function.
49 58
 
50 59
 `mysite/code/Controllers/FastFood.php`
51 60
 
52 61
 	:::php
53 62
 	class FastFood_Controller extends Controller {
  63
+	    
54 64
 	    public static $url_handlers = array(
55  
-	            'drivethrough/$Action/$ID/$Name' => 'order'
56  
-	            );
57  
-
58  
-
  65
+	        'drivethrough/$Action/$ID/$Name' => 'order'
  66
+	    );
59 67
 
60 68
 ## URL Patterns
61 69
 
62  
-The `[api:RequestHandler]` class will parse all rules you specify against the following patterns.
  70
+The `[api:RequestHandler]` class will parse all rules you specify against the 
  71
+following patterns.
63 72
 
64  
-**A rule must always start with alphabetical ([A-Za-z]) characters or a $Variable declaration**
  73
+**A rule must always start with alphabetical ([A-Za-z]) characters or a $Variable 
  74
+declaration**
65 75
 
66 76
  | Pattern     | Description | 
67 77
  | ----------- | --------------- | 
@@ -91,6 +101,7 @@ You can use the `debug_request=1` switch from the [urlvariabletools](/reference/
91 101
 ## Redirection
92 102
 
93 103
 Controllers facilitate HTTP redirection.
  104
+
94 105
 Note: These methods have been formerly located on the `[api:Director]` class.
95 106
 
96 107
 *  `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.
43  templates/Controller.ss
... ...
@@ -1,22 +1,43 @@
1 1
 <!DOCTYPE html>
2 2
 <html lang="en">
3  
-
4 3
 	<head>
5 4
 		<meta charset="utf-8">
6 5
 		<% base_tag %>
7 6
 
8 7
 		$MetaTags
  8
+
  9
+		<% require css('framework/css/debug.css') %>
9 10
 	</head>
10 11
 	<body>
11  
-		<h1><% if $Title %>$Title<% else %>Welcome to SilverStripe<% end_if %></h1>
12  
-		<% if $Content %>$Content<% else %>
13  
-		<p>To get started with the SilverStripe framework:</p>
14  
-		<ol>
15  
-			<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>
16  
-			<li>Setup the routes to your <code>Controller</code>.</li>
17  
-			<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>
18  
-		</ol>
19  
-		<% end_if %>
20  
-		<p><em>Generated with the default Controller.ss template.</em></p>
  12
+		<div class="info">
  13
+			<h1><% if $Title %>$Title<% else %>Welcome to SilverStripe<% end_if %></h1>
  14
+			<h3>Generated with the default Controller.ss template</h3>
  15
+		</div>
  16
+
  17
+		<div class="options">
  18
+			<% if $Content %>$Content<% else %>
  19
+			<h3>Getting Started</h3>
  20
+
  21
+			<p>To get started with the SilverStripe framework:</p>
  22
+			<ol>
  23
+				<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>
  24
+				<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>
  25
+				<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>
  26
+			</ol>
  27
+			<% end_if %>
  28
+
  29
+			<h3>Community resources</h3>
  30
+
  31
+			<ul>
  32
+				<li>
  33
+					<p><a href="http://silverstripe.org/forum">silverstripe.org/forum</a> Discussion forums for the development community.</p>
  34
+				</li>
  35
+				<li><p><a href="http://silverstripe.org/irc">silverstripe.org/irc</a> IRC channel for realtime support and discussions.</p></li>
  36
+
  37
+				<li><p><a href="http://doc.silverstripe.org">doc.silverstripe.org</a> Searchable developer documentation, how-tos, tutorials, and reference.</p></li>
  38
+
  39
+				<li><p><a href="http://api.silverstripe.org">api.silverstripe.org</a> API documentation for PHP classes, methods and properties.</p></li>
  40
+			<ul>
  41
+		</div>
21 42
 	</body>
22 43
 </html>

0 notes on commit 9cfbe9b

Please sign in to comment.
Something went wrong with that request. Please try again.