Skip to content
This repository
Browse code

Restructured 3.0 changelog

Moved some more important stuff up the page,
rewritten upgrading overview to be more task focused,
reduced excessive use of paragraphs to make the text more scannable.
  • Loading branch information...
commit de73db9ef78958b87459093e43dc6f38fa15a9f5 1 parent 2b5214b
Ingo Schommer authored

Showing 1 changed file with 123 additions and 136 deletions. Show diff stats Hide diff stats

  1. 259  docs/en/changelogs/3.0.0.md
259  docs/en/changelogs/3.0.0.md
Source Rendered
@@ -2,43 +2,89 @@
2 2
 
3 3
 ## Overview ##
4 4
 
5  
- * New template engine
6  
- * New CMS interface design
7  
-  * Image/Link insertion moved into a modal dialog instead of a sidebar
  5
+### CMS
  6
+
  7
+ * New CMS interface design more geared towards complex content solutions
  8
+  * List view for pages (sortable and filterable)
  9
+  * More powerful media and link insertion (including auto-embedding of external sources)
8 10
   * Batch actions on site tree moved to an "Edit Tree" view
9  
-  * "Add pages" dropdown now an "Add new" button which goes to a more descriptive page
10  
- * Renaming of sapphire to SilverStripe framework
11  
- * FormField classes now have their own HTML templates
12  
- * Allow usage of SilverStripe framework without the "cms" module
  11
+  * "Add pages" shows a dedicated interface with more info about the page type
13 12
  * CMS JavaScript moved to [jQuery.entwine](https://github.com/hafriedlander/jquery.entwine)
14 13
  * CMS stylesheets are generated by SCSS to provide more flexible and robust styling
15 14
 
16  
-## Upgrading ##
  15
+### Framework
17 16
 
18  
-### Overview
  17
+ * Renaming of "sapphire" to SilverStripe "framework"
  18
+ * Allow usage of SilverStripe framework without the "cms" module
  19
+ * New template engine with more powerful syntax
  20
+ * New ORM layer with expressive and fluent syntax
  21
+ * New GridField component to replace ComplexTableField
  22
+ * FormField classes now have their own HTML templates
  23
+ * Moved functionality to modules: Widget, RestfulServer, SapphireSoapServer, Translatable, IPRestrictions, PageComment, HomepageForDomain
19 24
 
20  
- * Folders: `sapphire/` moved to `framework/`, replace with `FRAMEWORK_DIR` (in PHP) or `$ModulePath(framework)` (in templates). Be sure to update `.htaccess` or `web.config` ([more](#sapphire-rename))
21  
- * Templates: `<% control %>` replaced by `<% loop %>` and `<% with %>` ([more](/reference/templates-upgrading-guide#control))
22  
- * `DataObjectSet` is replaced by `DataList`; beware that `DataList->remove()` will delete an entry from the database ([more](#deprecated-classes))
23  
- * `ComplexTableField` is replaced by `GridField`, which is similar to the `DataObjectManager` extension.
24  
- * `Director::redirect()` and `Director::redirectBack()` deprecated ([more] (#director-static-functions-deprecated-director-redirect-and-director-redirectback-in-particular)
25  
- * Changes in ORM, DataObject::get() deprecated ([more](#new-orm-datalist))
26  
- * `DataObjectDecorator::extraStatics` deprecated ([more](#extensions))
27  
- * Backend tab paths are shortened: `Root.Content.Main` becomes `Root.Main` ([more](#tab-paths))
  25
+## Upgrading ##
28 26
 
29  
-### sapphire renamed to framework {#sapphire-rename}
  27
+### Common Upgrade Tasks
30 28
 
31  
-`sapphire` has been renamed to `framework`.
  29
+ * Rename foder from `sapphire/`to `framework/`, replace own paths with `FRAMEWORK_DIR` (in PHP) or `$ModulePath(framework)` (in templates). Update paths in `.htaccess` or `web.config` ([more](#sapphire-rename))
  30
+ * Replace `<% control %>` in your templates with `<% loop %>` and `<% with %>` ([more](/reference/templates-upgrading-guide#control))
  31
+ * Replace `DataObjectSet` with `DataList` or `ArrayList` ([more](#deprecated-classes))
  32
+ * Rewrite `ComplexTableField` and `DataObjectManager` instances to `GridField`
  33
+ * Rewrite `Director::redirect()` and `Director::redirectBack()` calls ([more] (#director-static-functions-deprecated-director-redirect-and-director-redirectback-in-particular)
  34
+ * Use `<MyModel>::get()` rather than `DataObject::get()` ([more](#new-orm-datalist))
  35
+ * Use new syntax for `DataObjectDecorator::extraStatics` ([more](#extensions))
  36
+ * Change CMS tab paths from `Root.Content.Main` to `Root.Main`, move some field changes to new `SiteTree->getSettingsFields()` method ([more](#tab-paths))
  37
+ * Add new modules if using specific core features like Widget, RestfulServer, PageComment or Translatable
32 38
 
33  
-Please ensure the framework now resides in the new folder when upgrading.
  39
+### sapphire renamed to framework {#sapphire-rename}
34 40
 
35  
-Here's a list of steps to check:
  41
+The `sapphire` module has been renamed to `framework`. Please ensure the framework now resides in the new folder when upgrading. Here's a list of steps to check:
36 42
 
37 43
  * Remove your existing `sapphire` directory, and replace with `framework` from the new SilverStripe 3.0 package
38 44
  * Rename references of `sapphire` to `framework` in `.htaccess`, `web.config` and `/usr/bin/sake` (the last is only necessary if you use `sake`)
39 45
  * Find and replace any references to `sapphire` in your custom code to `framework`. In your PHP code, you can use the constant `FRAMEWORK_DIR`,
40 46
 which points to the framework directory, and in the templates you can use `$ModulePath(framework)`
41 47
 
  48
+### GridField: Replacement for TableListField and ComplexTableField [gridfield]###
  49
+
  50
+We have a new component for managing lists of objects: The `[GridField](/topics/grid-field)`.
  51
+It's a substantial rewrite of the features previously captured by `TableListField`,
  52
+`ComplexTableField`, `HasManyComplexTableField` and `ManyManyComplexTableField`.
  53
+
  54
+The legacy fields remain operational for now, although a switch to `GridField` is strongly encouraged,
  55
+for stability, interface and performance reasons. The `HasManyComplexTableField` and `ManyManyComplexTableField`
  56
+are no longer maintained, for those you do have to make the switch.
  57
+The `TableField` class will be deprecated soon, but we don't have an adequate replacement for it yet.
  58
+
  59
+Upgrade example: Record listing
  60
+
  61
+	:::php
  62
+	// before
  63
+	$field = new TableListField('Companies', 'Company');
  64
+	$field->setPageSize(20);
  65
+	// after
  66
+	$field = new GridField('Companies', null, Company::get());
  67
+	$field->getConfig()->getComponentByType('GridFieldPaginator')->setItemsPerPage(20);
  68
+
  69
+Upgrade example: Record listing with view/edit interface
  70
+
  71
+	:::php
  72
+	// before
  73
+	$field = new ComplexTableField($myController, 'Companies', 'Company');
  74
+	// after
  75
+	$field = new GridField('Companies', null, Company::get(), GridFieldConfig_RecordEditor::create());
  76
+
  77
+
  78
+Upgrade example: Relationship editing
  79
+
  80
+	:::php
  81
+	// before
  82
+	$field = new HasManyComplexTableField($myController, 'MyRelation', 'MyRelationObject');
  83
+	// after
  84
+	$field = new GridField('MyRelation', null, $myRecord->MyRelation(), GridFieldConfig_RelationEditor::create());
  85
+
  86
+More information is available in the [GridField documentation](/topics/grid-field).
  87
+
42 88
 ### Object static functions replaced with new Config class {#new-config}
43 89
 Static functions for getting a static variable on the `Object` class have been deprecated,
44 90
 in favour of using the new `Config` class instead.
@@ -63,21 +109,17 @@ Note the different options for the third parameter of `get()`:
63 109
 If you don't set an option, it will get all the values for the static, including inherited ones.
64 110
 This was previously known as `Object::combined_static()`.
65 111
 
66  
-### Director static functions deprecated, Director::redirect() and Director::redirectBack() in particular
  112
+### Director static functions deprecated (e.g. redirect() and redirectBack())
67 113
 
68  
-`Director::redirect()` and `Director::redirectBack()` are now marked as deprecated.
  114
+`Director::redirect()` and `Director::redirectBack()` are now marked as deprecated. If you have a `Controller` instance and need to redirect, call `redirect()` or `redirectBack()` on the instance
  115
+instead, e.g. `$controller->redirect()` or `$controller->redirectBack()`. Most of the time, form action handler methods on a controller need only call `$this->redirect()` or `$this->redirectBack()`.
69 116
 
70  
-If you have a `Controller` instance and need to redirect, call `redirect()` or `redirectBack()` on the instance
71  
-instead, e.g. `$controller->redirect()` or `$controller->redirectBack()`. Most of the time, form action handler
72  
-methods on a controller need only call `$this->redirect()` or `$this->redirectBack()`.
73  
-
74  
-Use `Controller::curr()->redirect()` and `Controller::curr()->redirectBack()` if you need to redirect in contexts
75  
-where a controller might not be immediately available.
  117
+Use `Controller::curr()->redirect()` and `Controller::curr()->redirectBack()` if you need to redirect in contexts where a controller might not be immediately available.
76 118
 
77 119
 ### DataExtension and deprecated extraStatics on extension classes {#extensions}
78 120
 
79  
-`DataObjectDecorator` has been renamed to `DataExtension`. Any classes that extend `DataObjectDecorator`
80  
-should now extend `DataExtension` instead.
  121
+`DataObjectDecorator` has been renamed to `DataExtension`. Please extend this class in case you
  122
+have written your own extensions.
81 123
 
82 124
 `extraStatics()` on extensions is now deprecated.
83 125
 
@@ -86,41 +128,36 @@ Instead of using `extraStatics()`, you can simply define static variables on you
86 128
 If you need custom logic, e.g. checking for a class before applying the statics on the extension,
87 129
 you can use `add_to_class()` as a replacement to `extraStatics()`.
88 130
 
89  
-Given the original `extraStatics` function:
90  
-
91  
-	<?php
92  
-	//...
93  
-	function extraStatics($class, $extensionClass) {
94  
-		if($class == 'MyClass') {
95  
-			return array(
96  
-				'db' => array(
97  
-					'Title' => 'Varchar'
  131
+	:::php
  132
+	class MyExtension extends Extension {
  133
+		
  134
+		// before
  135
+		function extraStatics($class, $extensionClass) {
  136
+			if($class == 'MyClass') {
  137
+				return array(
  138
+					'db' => array(
  139
+						'Title' => 'Varchar'
  140
+					);
98 141
 				);
99  
-			);
  142
+			}
100 143
 		}
101  
-	}
102 144
 
103  
-This would now become a static function `add_to_class`, and calls `update()` with an array
104  
-instead of returning it. It also needs to call `parent::add_to_class()`:
  145
+		// after
  146
+		static $db = array(
  147
+			'Title' => 'Varchar'
  148
+		);
105 149
 
106  
-	<?php
107  
-	//...
108  
-	static function add_to_class($class, $extensionClass, $args = null) {
109  
-		if($class == 'MyClass') {
110  
-			Config::inst()->update($class, 'db', array(
111  
-				'Title' => 'Varchar'
112  
-			));
113  
-		}
114  
-		parent::add_to_class($class, $extensionClass, $args);
  150
+		// advanced syntax
  151
+		static function add_to_class($class, $extensionClass, $args = null) {
  152
+			if($class == 'MyClass') {
  153
+				Config::inst()->update($class, 'db', array(
  154
+					'Title' => 'Varchar'
  155
+				));
  156
+			}
  157
+			parent::add_to_class($class, $extensionClass, $args);
  158
+		}	
115 159
 	}
116 160
 
117  
-Alternatively, you can define statics on the extension directly, like this:
118  
-
119  
-	<?php
120  
-	//...
121  
-	static $db = array(
122  
-		'Title' => 'Varchar'
123  
-	);
124 161
 
125 162
 ### New ORM: More flexible and expressive querying via `DataList` {#new-orm-datalist}
126 163
 
@@ -163,6 +200,7 @@ for the presence of records, please call the count() method on the `DataList`:
163 200
 	// after
164 201
 	if(!DataObject::get('SiteTree', '"ParentID" = 5')->count()) echo "Page 5 has no children";
165 202
 
  203
+Beware that `DataList->remove()` will delete an entry from the database.
166 204
 See the ["datamodel" documentation](../../topics/datamodel) for more details.
167 205
 
168 206
 ### New ORM: Changes to manipulation of SQL queries {#new-orm-sql-queries}
@@ -204,23 +242,10 @@ The abstract `RelationList` class and its implementations `ManyManyList` and `Ha
204 242
 are replacing the `ComponentSet` API, which is only relevant if you have instanciated these manually.
205 243
 Relations are retrieved through the same way (e.g. `$myMember->Groups()`).
206 244
 
207  
-### Aggregate changes for partial caching in templates ###
208  
-
209  
-`DataObject::Aggregate()` and `DataObject::RelationshipAggregate()` are now deprecated. To replace your deprecated aggregate calls
210  
-in PHP code, you should query with something like `Member::get()->max('LastEdited')`, that is, calling the aggregate on the `DataList` directly.
211  
-The same concept applies for replacing `RelationshipAggregate()`, just call the aggregate method on the relationship instead,
212  
-so something like `Member::get()->Groups()->max('LastEdited')`.
213  
-
214  
-For partial caching in templates, the syntax `<% cached Aggregate(Page).Max(LastEdited) %>` has been deprecated. The new syntax is similar,
215  
-except you use `List()` instead of `Aggregate()`, and the aggregate call `Max()` is now lowercase, as in `max()`.
216  
-An example of the new syntax is `<% cached List(Page).max(LastEdited) %>`. Check `DataList` class for more aggregate methods to use.
217  
-
218 245
 ### `SQLQuery` changes ###
219 246
 
220 247
 `SQLQuery` has been changed so direct access to internal properties `$from`, `$select`, `$orderby` is
221  
-now deprecated.
222  
-
223  
-Instead, there are now methods you can call which allow you to get and set SQL clauses instead.
  248
+now deprecated. Instead, there are now methods you can call which allow you to get and set SQL clauses instead.
224 249
 
225 250
  * `$from` getter is `getFrom()` and setters `setFrom()` and `addFrom()`
226 251
  * `$select` getter is `getSelect()` and setters `setSelect()` and `addSelect()`
@@ -232,23 +257,19 @@ Instead, there are now methods you can call which allow you to get and set SQL c
232 257
  * `$distinct` getter is `getDistinct()` and setter `setDistinct()`
233 258
  * `$delete` getter is `getDelete()` and setter `setDelete()`
234 259
  * `$connective` getter is `getConnective()` and settter `setConnective()`
235  
-
236 260
  * `innerJoin()` has been renamed to `addInnerJoin()`
237 261
  * `leftJoin()` has been renamed to `addLeftJoin()`
238 262
 
239  
-### TinyMCE upgraded to 3.5 ###
240  
-
241  
-TinyMCE has been upgraded to version 3.5.
242  
-
243  
-This change should be transparent to most people upgrading, but if you're using custom plugins for TinyMCE,
244  
-please ensure they are still working correctly with the new version.
  263
+### Aggregate changes for partial caching in templates ###
245 264
 
246  
-If you're upgrading from an SS 3.0 beta, TinyMCE HTML source editor and other popups might be blank.
247  
-This is caused by the TinyMCE compressor leaving stale cache files in the system temp folder from an earlier
248  
-version.
  265
+`DataObject::Aggregate()` and `DataObject::RelationshipAggregate()` are now deprecated. To replace your deprecated aggregate calls
  266
+in PHP code, you should query with something like `Member::get()->max('LastEdited')`, that is, calling the aggregate on the `DataList` directly.
  267
+The same concept applies for replacing `RelationshipAggregate()`, just call the aggregate method on the relationship instead,
  268
+so something like `Member::get()->Groups()->max('LastEdited')`.
249 269
 
250  
-To resolve this problem, simply delete the `{hash}.gz` files within your temp location (defined by `sys_get_temp_dir()` in PHP.)
251  
-These cache files will be regenerated next time the CMS is opened.
  270
+For partial caching in templates, the syntax `<% cached Aggregate(Page).Max(LastEdited) %>` has been deprecated. The new syntax is similar,
  271
+except you use `List()` instead of `Aggregate()`, and the aggregate call `Max()` is now lowercase, as in `max()`.
  272
+An example of the new syntax is `<% cached List(Page).max(LastEdited) %>`. Check `DataList` class for more aggregate methods to use.
252 273
 
253 274
 ### InnoDB driver for existing and new tables on MySQL (instead of MyISAM) [innodb]###
254 275
 
@@ -270,12 +291,9 @@ Note: MySQL has made InnoDB the default engine in its [5.5 release](http://dev.m
270 291
 
271 292
 ### Convert::json2array() changes [raw2json]###
272 293
 
273  
-Convert JSON functions have been changed to use built-in json PHP functions `json_decode()` and `json_encode()`
274  
-
  294
+Convert JSON functions have been changed to use built-in json PHP functions `json_decode()` and `json_encode()`.
275 295
 Because `json_decode()` will convert nested JSON structures to arrays as well, this has changed the way it worked,
276  
-as before nested structures would be converted to an object instead.
277  
-
278  
-So, given the following JSON input to `Convert::json2array()`:
  296
+as before nested structures would be converted to an object instead. So, given the following JSON input to `Convert::json2array()`:
279 297
 
280 298
 	{"Joe":"Bloggs","Tom":"Jones","My":{"Complicated":"Structure"}}
281 299
 
@@ -299,47 +317,6 @@ Now in SilverStripe 3.x, nested structures are arrays:
299 317
 		)
300 318
 	)
301 319
 
302  
-
303  
-### GridField: Replacement for TableListField and ComplexTableField [gridfield]###
304  
-
305  
-We have a new component for managing lists of objects: The `[GridField](/topics/grid-field)`.
306  
-It's a substantial rewrite of the features previously captured by `TableListField`,
307  
-`ComplexTableField`, `HasManyComplexTableField` and `ManyManyComplexTableField`.
308  
-
309  
-The legacy fields remain operational for now, although a switch to `GridField` is strongly encouraged,
310  
-for stability, interface and performance reasons. The `HasManyComplexTableField` and `ManyManyComplexTableField`
311  
-are no longer maintained, for those you do have to make the switch.
312  
-The `TableField` class will be deprecated soon, but we don't have an adequate replacement for it yet.
313  
-
314  
-Upgrade example: Record listing
315  
-
316  
-	:::php
317  
-	// before
318  
-	$field = new TableListField('Companies', 'Company');
319  
-	$field->setPageSize(20);
320  
-	// after
321  
-	$field = new GridField('Companies', null, Company::get());
322  
-	$field->getConfig()->getComponentByType('GridFieldPaginator')->setItemsPerPage(20);
323  
-
324  
-Upgrade example: Record listing with view/edit interface
325  
-
326  
-	:::php
327  
-	// before
328  
-	$field = new ComplexTableField($myController, 'Companies', 'Company');
329  
-	// after
330  
-	$field = new GridField('Companies', null, Company::get(), GridFieldConfig_RecordEditor::create());
331  
-
332  
-
333  
-Upgrade example: Relationship editing
334  
-
335  
-	:::php
336  
-	// before
337  
-	$field = new HasManyComplexTableField($myController, 'MyRelation', 'MyRelationObject');
338  
-	// after
339  
-	$field = new GridField('MyRelation', null, $myRecord->MyRelation(), GridFieldConfig_RelationEditor::create());
340  
-
341  
-More information is available in the [GridField documentation](/topics/grid-field).
342  
-
343 320
 ### New template engine [templates]###
344 321
 
345 322
 The template engine has been completely rewritten, and although it is generally backward compatible, there are new features
@@ -373,6 +350,18 @@ The page tree moved from a bespoke tree library to [JSTree](http://jstree.com),
373 350
 which required changes to markup of the tree and its JavaScript architecture.
374 351
 This includes changes to `TreeDropdownField` and `TreeMultiSelectField`.
375 352
 
  353
+### TinyMCE upgraded to 3.5 ###
  354
+
  355
+TinyMCE has been upgraded to version 3.5.
  356
+
  357
+This change should be transparent to most people upgrading, but if you're using custom plugins for TinyMCE,
  358
+please ensure they are still working correctly with the new version.
  359
+
  360
+If you're upgrading from an SS 3.0 beta, TinyMCE HTML source editor and other popups might be blank.
  361
+This is caused by the TinyMCE compressor leaving stale cache files in the system temp folder from an earlier
  362
+version. To resolve this problem, simply delete the `{hash}.gz` files within your temp location (defined by `sys_get_temp_dir()` in PHP.)
  363
+These cache files will be regenerated next time the CMS is opened.
  364
+
376 365
 ### Settings-related fields move from SiteTree->getCMSFields() to new SiteTree->getSettingsFields() [getcmsfields]###
377 366
 
378 367
 The fields and tabs are now split into two separate forms, which required a structural
@@ -491,10 +480,9 @@ Please use the appropriate setters on the form field instance instead.
491 480
 ### EmailField now uses type "email" instead of type "text" {#email-form-field}
492 481
 
493 482
 EmailField now uses "email" for the `type` attribute, which integrates better with HTML5 features like
494  
-form validation in the browser.
495  
-
496  
-If you want to change this back to "text", use `setAttribute()` when constructing the field:
  483
+form validation in the browser. If you want to change this back to "text", use `setAttribute()` when constructing the field:
497 484
 
  485
+	:::php
498 486
 	$field = new EmailField('Email');
499 487
 	$field->setAttribute('type', 'text');
500 488
 
@@ -502,7 +490,6 @@ If you want to change this back to "text", use `setAttribute()` when constructin
502 490
 
503 491
 In order to make the SilverStripe framework useable without the `cms` module,
504 492
 we've moved some files around. 
505  
-
506 493
 CMS base functionality which is not directly related to content pages (`SiteTree`) 
507 494
 has been moved from the `cms` module into a new "sub-module" located in `framework/admin`. 
508 495
 This includes generic management interfaces like "Files & Images" (`AssetAdmin`),

0 notes on commit de73db9

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