tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-07-04 02:19:32 +02:00
Code Issues Projects Releases Wiki Activity

Less verbosity in upgrading guide

Browse Source
This commit is contained in:
Ingo Schommer 2016-09-09 13:33:52 +12:00 committed by GitHub
parent fe5925726e
commit 97c2baedeb
1 changed files with 13 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
docs/en/04_Changelogs/4.0.0.md
View File

@ -34,15 +34,14 @@ guide developers in preparing existing 3.x code for compatibility with 4.0
prominently featuring ReactJS to develop highly functional CMS content areas. A new standard form schema prominently featuring ReactJS to develop highly functional CMS content areas. A new standard form schema
API has been developed to allow back-end PHP constructed forms to scaffold themselves within ReactJS API has been developed to allow back-end PHP constructed forms to scaffold themselves within ReactJS
powered sections. powered sections.
* CMS CSS has been re-developed using bootstrap 4 as a base. See the * CMS CSS has been re-developed using bootstrap 4 as a base
[silverstripe blog post](https://www.silverstripe.org/blog/a-frameworks-framework-why-silverstripe-4-will-use-bootstrap/). ([blog post](https://www.silverstripe.org/blog/a-frameworks-framework-why-silverstripe-4-will-use-bootstrap/))
* Asset admin has been replaced with a purely ReactJS powered upgrade, and split out * Asset admin has been replaced with a purely ReactJS powered upgrade, and split out
[into a new module](https://github.com/silverstripe/silverstripe-asset-admin/) module called [asset-admin](https://github.com/silverstripe/silverstripe-asset-admin/). You'll need to add this to your `composer.json` to retain file management capabilities for your CMS authors.
* Versioning is now a much more powerful feature, with the addition of campaigns to allow batches of related * Versioning is now a much more powerful feature, with the addition of campaigns to allow batches of related
or inter-dependent objects to be published as a single act. Dependencies between versioned objects can be or inter-dependent objects to be published as a single act. Dependencies between versioned objects can be
declared using the new ownership API, so that developers can ensure that relational consistency is declared using the new ownership API, so that developers can ensure that relational consistency is
maintained during publishing. This new system can be managed via the new "Campaigns" CMS section. maintained during publishing. This new system can be managed via the new "Campaigns" CMS section ([blog post](https://www.silverstripe.org/blog/campaigns-in-silverstripe-4/))
See the [silverstripe blog post](https://www.silverstripe.org/blog/campaigns-in-silverstripe-4/).
* Template variable casting (e.g. `<h1>$Title</h1>`) is enforced by default, which will ensure safe HTML encode * Template variable casting (e.g. `<h1>$Title</h1>`) is enforced by default, which will ensure safe HTML encode
unless explicitly opted out. unless explicitly opted out.
* Themes are now configured to cascade, where you can specify a list of themes, and have the template engine * Themes are now configured to cascade, where you can specify a list of themes, and have the template engine
@ -187,15 +186,11 @@ After:
If you need to encode a field (such as HTMLText) for use in html attributes, use `.ATT` If you need to encode a field (such as HTMLText) for use in html attributes, use `.ATT`
instead, or if used in an actual XML file use `.CDATA`. instead, or if used in an actual XML file use `.CDATA` (see [template casting](/developer_guides/templates/casting)).
See the [Template casting](/developer_guides/templates/casting) section for specific details.
#### Upgrade code that uses SQLQuery #### Upgrade code that uses SQLQuery
Where your code once used SQLQuery you should now use SQLSelect in all cases, as this has been removed. Where your code once used SQLQuery you should now use SQLSelect in all cases, as this has been removed (check the [3.2.0](3.2.0) upgrading notes).
See the [3.2.0](3.2.0) upgrading notes for details on how existing code should be upgraded.
#### New asset storage mechanism #### New asset storage mechanism
@ -215,7 +210,7 @@ Note that this will not allow you to utilise certain file versioning features in
legacy_paths: true legacy_paths: true
See [/developer_guides/files/file_management] for more information on how the new system works. See our ["File Management" guide](/developer_guides/files/file_management) for more information.
#### Migrating File DataObject from 3.x to 4.0 #### Migrating File DataObject from 3.x to 4.0
@ -301,7 +296,6 @@ existed in the assets folder, and that the Filename of the DataObject was set to
Since the storage of physical files is no longer a standard location, it's necessary to delegate the writing of such Since the storage of physical files is no longer a standard location, it's necessary to delegate the writing of such
files to the asset persistence layer. As a wrapper for an individual file, you can use any of the `setFrom*` files to the asset persistence layer. As a wrapper for an individual file, you can use any of the `setFrom*`
methods to assign content from a local (e.g. temporary) file, a stream, or a string of content. methods to assign content from a local (e.g. temporary) file, a stream, or a string of content.
You would need to upgrade your code as below. You would need to upgrade your code as below.
Before: Before:
@ -357,7 +351,6 @@ which are used to generate what are now called "variants" of assets, is now a ge
and `DBFile` classes through this trait. and `DBFile` classes through this trait.
Custom manipulations, applied via extensions, must be modified to use the new API. Custom manipulations, applied via extensions, must be modified to use the new API.
For instance, code which sizes images to a fixed width should be updated as below: For instance, code which sizes images to a fixed width should be updated as below:
Before: Before:
@ -378,9 +371,7 @@ Before:
Image::add_extension('MyImageExtension'); Image::add_extension('MyImageExtension');
Now image manipulations are implemented with a single method via a callback generator. Now image manipulations are implemented with a single method via a callback generator:
After:
:::php :::php
@ -444,8 +435,7 @@ These methods have been updated to include base fields (such as ID, ClassName, C
well as composite DB fields. well as composite DB fields.
`DataObject::database_fields` does not have a second parameter anymore, and can be called directly on an object `DataObject::database_fields` does not have a second parameter anymore, and can be called directly on an object
or class. E.g. `Member::database_fields()` or class. E.g. `Member::database_fields()`.
If user code requires the list of fields excluding base fields, then use custom_database_fields instead, or If user code requires the list of fields excluding base fields, then use custom_database_fields instead, or
make sure to call `unset($fields['ID']);` if this field should be excluded. make sure to call `unset($fields['ID']);` if this field should be excluded.
@ -481,7 +471,7 @@ the `table_name` config can be applied to any DataObject class.
In order to ensure you are using the correct table for any class a new [api:DataObjectSchema] service In order to ensure you are using the correct table for any class a new [api:DataObjectSchema] service
is available to manage these mappings. is available to manage these mappings (see [versioned documentation](/developer_guides/model/data_model_and_orm)).
:::php :::php
@ -494,15 +484,11 @@ is available to manage these mappings.
} }
See [versioned documentation](/developer_guides/model/data_model_and_orm) for more information.
#### Upgrade implementations of augmentSQL #### Upgrade implementations of augmentSQL
Since this method now takes a `SQLSelect` as a first parameter, existing code referencing the deprecated `SQLQuery` Since this method now takes a `SQLSelect` as a first parameter, existing code referencing the deprecated `SQLQuery`
type will raise a PHP error. type will raise a PHP error.
E.g.
Before: Before:
:::php :::php
@ -547,8 +533,6 @@ In case that user code must customise this filename, such as for extensions whic
for any error page, the extension point `updateErrorFilename` can be used. This extension point should for any error page, the extension point `updateErrorFilename` can be used. This extension point should
also be used to replace any `alternateFilepathForErrorcode` used. also be used to replace any `alternateFilepathForErrorcode` used.
E.g.
:::php :::php
class MyErrorPageExtension extends SiteTreeExtension { class MyErrorPageExtension extends SiteTreeExtension {
@ -583,7 +567,7 @@ configuration customisation is done via overriding these templates.
If upgrading from an existing installation, make sure to invoke `?flush=all` at least once. If upgrading from an existing installation, make sure to invoke `?flush=all` at least once.
See [/developer_guides/files/file_security] for more information. See our ["File Security" guide](/developer_guides/files/file_security) for more information.
#### `ListboxField` is now multiple-only #### `ListboxField` is now multiple-only
@ -650,8 +634,6 @@ Rather than declaring the list of stages a model has, the constructor for `Versi
parameter, which declares whether or not the model is versioned and has a draft and live stage, or alternatively parameter, which declares whether or not the model is versioned and has a draft and live stage, or alternatively
if it only has versioning without staging. if it only has versioning without staging.
For instance:
:::php :::php
/** /**
@ -696,7 +678,6 @@ By default all versioned dataobjects will automatically publish objects that the
ChangeSet objects have been added, which allow groups of objects to be published in ChangeSet objects have been added, which allow groups of objects to be published in
a single atomic transaction. a single atomic transaction.
This API will utilise the ownership API to ensure that changes to any object include This API will utilise the ownership API to ensure that changes to any object include
all necessary changes to owners or owned entities within the same changeset. all necessary changes to owners or owned entities within the same changeset.
@ -718,7 +699,7 @@ This means that for the most part, code that worked in 3.0 won't need to be chan
An exception to this is any classes which once had the `SS_` prefix, which will now be instead prefixed with `DB`, and have an un-aliased prefix. For example `SS_Datetime` is now `DBDateTime`, and has the alias `DateTime` which may be used in config. An exception to this is any classes which once had the `SS_` prefix, which will now be instead prefixed with `DB`, and have an un-aliased prefix. For example `SS_Datetime` is now `DBDateTime`, and has the alias `DateTime` which may be used in config.
For example: Before:
class MyObject extends DataObject { class MyObject extends DataObject {
private static $db = array( private static $db = array(
@ -735,7 +716,7 @@ For example:
} }
} }
Will become: After:
use SilverStripe\ORM\FieldType\DBVarchar; use SilverStripe\ORM\FieldType\DBVarchar;
@ -768,7 +749,6 @@ In case you want to keep using RestfulService, you can use `Firesphere/silverstr
#### Upgrading from deprecated Oembed #### Upgrading from deprecated Oembed
Instead of Oembed, the framework now relies on [oscarotero/Embed](https://github.com/oscarotero/Embed) to handle getting the shortcode-data for embedding. Instead of Oembed, the framework now relies on [oscarotero/Embed](https://github.com/oscarotero/Embed) to handle getting the shortcode-data for embedding.
If you have custom embedding-code relying on Oembed, please refer to the documentation provided by oscarotero. If you have custom embedding-code relying on Oembed, please refer to the documentation provided by oscarotero.
#### Admin URL can now be configured via custom Director routing rule #### Admin URL can now be configured via custom Director routing rule