diff --git a/docs/en/04_Changelogs/4.0.0.md b/docs/en/04_Changelogs/4.0.0.md index dc815af9d..831ec9b56 100644 --- a/docs/en/04_Changelogs/4.0.0.md +++ b/docs/en/04_Changelogs/4.0.0.md @@ -25,7 +25,7 @@ guide developers in preparing existing 3.x code for compatibility with 4.0 [deprecation documentation](/contributing/release_process) for information on code deprecation. * All SilverStripe classes are now namespaced, and some have been renamed. This has major implications for arrangement of templates, as well as other references to classes via string literals or configuration. - Automatic upgrading tools have been developed to cope with the bulk of these changes (see + Automatic upgrading tools have been developed to cope with the bulk of these changes (see [upgrading notes](#upgrading)). * Asset storage has been abstracted, and a new concept of `DBFile` references via database column references now exists in addition to references via the existing `File` dataobject. File security and protected files @@ -34,7 +34,7 @@ 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 API has been developed to allow back-end PHP constructed forms to scaffold themselves within ReactJS powered sections. -* CMS CSS has been re-developed using bootstrap 4 as a base +* CMS CSS has been re-developed using bootstrap 4 as a base ([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 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. @@ -51,7 +51,7 @@ guide developers in preparing existing 3.x code for compatibility with 4.0 The below sections describe how to go about updating an existing site to be prepared for upgrade to 4.0. Most of these upgrading tasks will involve manual code review, although in some cases there are -some automated processes that users can run to +some automated processes that users can run to ### Standard Upgrade @@ -62,7 +62,7 @@ as a standard first point of upgrade. Nearly all core PHP classes have been namespaced. For example, `DataObject` is now called `SilverStripe\ORM\DataObject`. We have developed an [upgrader tool](https://github.com/silverstripe/silverstripe-upgrader/) to (semi-)automatically update your 3.x code to the new naming. Here's an example how to upgrade your `mysite` folder: - + composer global require silverstripe/upgrader cd ~/Project/Root ~/.composer/vendor/bin/upgrade-code upgrade ./mysite --write @@ -86,7 +86,7 @@ folder and have it be found. Case is now also checked on case-sensitive filesyst Either include the folder in the template name (`renderWith('MyEmail.ss')` => `renderWith('emails/MyEmail.ss')`), move the template into the correct directory, or both. This also affects `<% include %>` statements in templates. -When using `<% include %>` template tag you should continue to leave out the `Includes` folder. +When using `<% include %>` template tag you should continue to leave out the `Includes` folder. `<% include Sidebar %>` will match only match `Includes/Sidebar.ss`, not `Sidebar.ss`. Please refer to our [template syntax](/developer_guides/templates/syntax) for details. @@ -156,23 +156,23 @@ of these files, please consider packaging your own versions in your projects and For CMS modules, you can also use many library globals which the core bundles already expose (see [Build Tooling](/contributing/build_tooling)). -One commonly linked thirdparty dependency is `jquery.js` bundled with SilverStripe: +One commonly linked thirdparty dependency is `jquery.js` bundled with SilverStripe: ``` framework/thirdparty/jquery/jquery.js => framework/admin/thirdparty/jquery/jquery.js ``` #### Explicit text casting is now enforced on all template variables - + Now whenever a `$Variable` is used in a template, regardless of whether any casts or methods are suffixed to the reference, it will be cast to either an explicit DBField for that field, or the value declared by the `default_cast` on the parent object. - + The default value of `default_cast` is `Text`, meaning that now many cases where a field was left un-uncoded, this will now be safely encoded via `Convert::raw2xml`. In cases where un-cast fields were used to place raw HTML into templates, this will now encode this until explicitly cast for that field. - + You can resolve this in your model by adding an explicit cast to HTML for those fields. @@ -196,7 +196,7 @@ After: private static $casting = [ 'SomeHTML' => 'HTMLText' ]; - + public function getSomeHTML { $title = Convert::raw2xml($this->Title); return "

{$title}

"; @@ -259,7 +259,7 @@ are incompatible with core file security. #### Upgrade code which acts on `Image` -As all image-specific manipulations has been refactored from `Image` into an `ImageManipulations` trait, which +As all image-specific manipulations has been refactored from `Image` into an `ImageManipulations` trait, which is applied to both `File` and `DBFile`. These both implement a common interface `AssetContainer`, which has the `getIsImage()` method. In some cases, it may be preferable to invoke this method to detect if the asset is an image or not, rather than checking the subclass, as the asset may also be a `DBFile` with @@ -459,7 +459,7 @@ If user code requires the list of fields excluding base fields, then use custom_ make sure to call `unset($fields['ID']);` if this field should be excluded. `DataObject:db()` will return all logical fields, including foreign key ids and composite DB Fields, alongside -any child fields of these composites. This method can now take a second parameter $includesTable, which +any child fields of these composites. This method can now take a second parameter $includesTable, which when set to true (with a field name as the first parameter), will also include the table prefix in `Table.ClassName(args)` format. @@ -515,7 +515,7 @@ Before: $locale = Translatable::get_current_locale(); if(!preg_match('/("|\'|`)Locale("|\'|`)/', implode(' ', $query->getWhere()))) { $qry = sprintf('"Locale" = \'%s\'', Convert::raw2sql($locale)); - $query->addWhere($qry); + $query->addWhere($qry); } } @@ -606,7 +606,7 @@ of items to disable. Please see the [tinymce upgrading guide](http://archive.tinymce.com/wiki.php/Tutorial:Migration_guide_from_3.x) to assist with upgrades to customisations to tinymce 3. - + In Framework 4.0 the user interface for TinyMCE has been trimmed down considerably, with certain toolbar buttons removed from the default cms configuration. These include: * Strikethrough @@ -617,13 +617,13 @@ of items to disable. * Cut / Paste as word * Select all * Fullscreen - + However, these function may be enabled on a case by case basis through modifification of the default tinymce config, or by creating custom configurations. The optional `ss_macron` plugin for inserting Māori diacritical marks has been removed from core. You can configure the built-in `charmap` plugin instead: - + :::php $editor = HtmlEditorConfig::get('cms'); $editor->enablePlugins('charmap'); @@ -631,16 +631,16 @@ has been removed from core. You can configure the built-in `charmap` plugin inst $editor->setOption('charmap_append', [ ['256','A - macron'], ['274','E - macron'], - ['298','I - macron'], - ['332','O - macron'], - ['362','U - macron'], - ['257','a - macron'], - ['275','e - macron'], - ['299','i - macron'], - ['333','o - macron'], + ['298','I - macron'], + ['332','O - macron'], + ['362','U - macron'], + ['257','a - macron'], + ['275','e - macron'], + ['299','i - macron'], + ['333','o - macron'], ['363','u - macron'] ]); - + For more information on available options and plugins please refer to the [tinymce documentation](https://www.tinymce.com/docs/configure/) @@ -663,7 +663,7 @@ if it only has versioning without staging. "Versioned('StagedVersioned')" ); } - + /** * This model has versioning only, and will not has a draft or live stage, nor be affected by the current stage. */ @@ -679,7 +679,7 @@ Additionally, the following api methods have been added: * `Versioned::publishRecursive` Publishes this object, and all owned objects * `Versioned::publishSingle` Publishes this object, but not owned objects * `Versioned::copyVersionToStage` Replaces the old `publish` method. - + These methods are deprecated: * `Versioned::publish` Replaced by `Versioned::copyVersionToStage` @@ -708,7 +708,7 @@ Images inserted into `HTMLText` fields (through a WYSIWYG editor) need to be tra Instead of `` tags, the field will insert `[image]` shortcodes which point to the database identifier of the `Image` record rather than its path on the filesystem. The shortcode will be automatically replaced when the field is rendered. Newly inserted images will automatically receive the shortcode and ownership tracking, -and existing `` will continue to work. +and existing `` will continue to work. #### Upgrading references to DBField and subclasses @@ -767,15 +767,15 @@ In case you want to keep using RestfulService, you can use `Firesphere/silverstr #### 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. #### Admin URL can now be configured via custom Director routing rule -The default `admin/` URL to access the CMS interface can now be changed via a custom Director routing rule for -`AdminRootController`. If your website or module has hard coded `admin` URLs in PHP, templates or JavaScript, make sure -to update those with the appropriate function or config call. See -[CMS architecture](/developer_guides/customising_the_admin_interface/cms-architecture#the-admin-url) for language +The default `admin/` URL to access the CMS interface can now be changed via a custom Director routing rule for +`AdminRootController`. If your website or module has hard coded `admin` URLs in PHP, templates or JavaScript, make sure +to update those with the appropriate function or config call. See +[CMS architecture](/developer_guides/customising_the_admin_interface/cms-architecture#the-admin-url) for language specific functions. ## API Changes @@ -786,8 +786,8 @@ specific functions. * Minimum PHP version raised to 5.5.0 * Minimum CMS browser requirement raised from Internet Explorer 8 to Internet Explorer 10 -* Updated PHPUnit from 3.7 to 4.8 ([upgrade notes](https://github.com/sebastianbergmann/phpunit/wiki/Release-Announcement-for-PHPUnit-4.0.0#backwards-compatibility-issues)). - Please remove any PHPUnit related `require_once()` calls (e.g. in `FeatureContext` +* Updated PHPUnit from 3.7 to 4.8 ([upgrade notes](https://github.com/sebastianbergmann/phpunit/wiki/Release-Announcement-for-PHPUnit-4.0.0#backwards-compatibility-issues)). + Please remove any PHPUnit related `require_once()` calls (e.g. in `FeatureContext` definitions of the [behat-extension](https://github.com/silverstripe-labs/silverstripe-behat-extension) module). Run `composer require --dev 'phpunit/phpunit:~4.8'` on existing projects to pull in the new dependency. * Admin URL can now be configured via custom Director routing rule @@ -843,7 +843,7 @@ specific functions. [oscarotero/Embed](https://github.com/oscarotero/Embed) as a dependency. * Removed TextParser and BBCodeParser. These are available in an archived module, [silverstripe-archive/bbcodeparser](https://github.com/silverstripe-archive/silverstripe-bbcodeparser) - + #### General and Core Deprecated API A very small number of methods were chosen for deprecation, and will be removed in 5.0 rather than 4.0 @@ -892,7 +892,7 @@ A very small number of methods were chosen for deprecation, and will be removed * `$versionableExtensions` is now `private static` instead of `protected static` * `hasStages` is addded to check if an object has a given stage. * `stageTable` is added to get the table for a given class and stage. - * Any extension declared via `versionableExtensions` config on Versioned dataobject must now + * Any extension declared via `versionableExtensions` config on Versioned dataobject must now `VersionableExtension` interface at a minimum. `Translatable` has been removed from default `versionableExtensions` * The default CMS delete behaviour for versioned dataobjects is now to delete from both draft @@ -917,7 +917,7 @@ A very small number of methods were chosen for deprecation, and will be removed * `ChangeSet` and `ChangeSetItem` have been added for batch publishing of versioned dataobjects. * `DataObject.table_name` config can now be used to customise the database table for any record. * `DataObjectSchema` class added to assist with mapping between classes and tables. - + #### ORM Removed API * `DataObject::db` removed and replaced with `DataObjectSchema::fieldSpec` and `DataObjectSchema::fieldSpecs` @@ -951,7 +951,7 @@ A very small number of methods were chosen for deprecation, and will be removed * `DataObject::validateModelDefinitions()` has been removed. Validation and parsing of config is now handled within `DataObjectSchema`. * `CMSBatchAction_Delete` removed. Use `CMSBatchAction_Archive` instead. - + ### Filesystem API #### Filesystem API Additions / Changes @@ -1087,7 +1087,7 @@ New methods on `Requirements` are added to access these: * `set_minify_combined_js_files` * `get_force_js_to_bottom` * `get_write_js_to_body` - + Some methods on `Requirements` have had their method signatures changed: * `includeInHTML` has had the first parameter $template removed as it was previously deprecated.