silverstripe-framework/docs/en/changelogs/3.0.0.md

3.0.0 (unreleased)

Overview

• New template engine
• New CMS interface design
• "Page Content" and "Page Settings" are split into two interfaces
• Image/Link insertion moved into a modal dialog instead of a sidebar
• "Add pages" dropdown moved to a more descriptive modal dialog
• Allow usage of "sapphire" framework without the "cms" module
• CMS JavaScript moved to jQuery.entwine
• CMS stylesheets are generated by SCSS to provide more flexible and robust styling

Upgrading

New template engine

The template engine has been completely rewritten, and although it is generally backward compatible, there are new features and some features have been deprecated. See the template upgrading guide and the template reference for more information.

Removed view-specific accessors from ViewableData

Several methods in ViewableData that were originally added to expose values to the template language were moved, in order to stop polluting the namespace. These were sometimes called by project-specific PHP code too, and that code will need re-working.

See the template upgrading guide for a list of methods and their replacements.

New user interface for CMS

Most aspects of the interface have been redesigned, which necessitated a substantial redevelopment of the underlying logic and presentation. If you have customized the admin interface in any way, please review the detailed changelog for this release. Many interface components have changed completely, unfortunately there is no clear upgrade path for every interface detail. As a starting point, have a look at the new templates in cms/templates and sapphire/admin/templates, as well as the new jQuery.entwine based JavaScript logic. Have a look at the new "Extending the CMS" guide, "CSS" guide and "JavaScript" guide to get you started.

New tree library

The page tree moved from a bespoke tree library to JSTree, which required changes to markup of the tree and its JavaScript architecture. This includes changes to TreeDropdownField and TreeMultiSelectField.

Settings-related fields move from SiteTree->getCMSFields() to new SiteTree->getSettingsFields()

The fields and tabs are now split into two separate forms, which required a structural change to the underlying class logic. In case you have added or removed fields in the "Behaviour" or "Access" tab, please move these customizations to a new getSettingsFields() method. In case of SiteTree extension through updateCMSFields() and a decorator/extension, please use the new updateSettingsFields() instead.

New SiteTree::$description field to describe purpose of a page type

Please use this static property to describe the purpose of your page types, which will help users understand the new "Add page" dialog. For example, a TeamPage type could be described as "Lists all team members, linking to their profiles". Note: This property is optional (defaults to an empty string), but its usage is highly encouraged.

Stylesheet preprocessing via SCSS and the "compass" module

CSS files in the cms and sapphire/admin modules are now generated through the "compass" SilverStripe module, which uses the "Compass" framework and the "SCSS" language. This allows us to build more flexible and expressive stylesheets as a foundation for any extensions to the CMS interface.

The "compass" module is only required if core stylesheets are modified, not when simply using the CMS or developing other CMS functionality. If you want to extend the CMS stylesheets for your own projects without SCSS, please create a new CSS file and link it into the CMS via [api:LeftAndMain::require_css()].

Built-in Javascript validation removed

Built-in client-side form validation using behaviour.js has been removed, and is no longer supported.

Server-side validation remains. Developers are encouraged to use custom Javascript validation on their forms if requiring client-side validation.

These classes/files have been removed:

Validator.js
CustomRequiredFields.php

These functions are now deprecated and will throw a notice if used:

Validator::set_javascript_validation_handler()
Validator::get_javascript_validator_handler()
Validator::setJavascriptValidationHandler()

These functions have been removed:

Validator::javascript() (abstract function)
Validator::includeJavascriptValidation()
FormField::jsValidation()
AjaxUniqueTextField::jsValidation()
ConfirmedPasswordField::jsValidation()
CreditCardField::jsValidation()
CurrencyField::jsValidation()
CustomRequiredFields::javascript()
DateField::jsValidation()
DatetimeField::jsValidation()
EmailField::jsValidation()
FieldGroup::jsValidation()
FormField::jsValidation()
NumericField::jsValidation()
PhoneNumberField::jsValidation()
RequiredFields::javascript()
TableField::jsValidation()
TimeField::jsValidation()

FormField consistently adds classes to HTML elements

The [api:FormField] API has been refactored to use SilverStripe templates for constructing the field HTML, as well as new accessors for HTML attributes. This change makes the HTML a bit more predictable, but it also means that you need to check any code (CSS, JavaScript, etc) relying on the old inconsistencies. Particularly, CSS class names applied through [api:FormField->addExtraClass()] and the "type" class are now consistently added to the container <div> as well as the HTML form element itself.

:::html
Before (abbreviated):
<div class="field checkbox extraClass"...>
	<input type="checkbox".../>
</div>

After (abbreviated):
<div class="field checkbox extraClass"...>
	<input type="checkbox" class="checkbox extraClass".../>
</div>

FormField constructor argument changes

In order to enforce a consistent parameter order in core [api:FormField] subclasses, its no longer possible to set the following optional attributes via constructor arguments: $form, $maxLength, $rightTitle, $rows/$cols (for TextareaField and HtmlEditorField) and $folderName (for FileField and SimpleImageField). Please use the appropriate setters on the form field instance instead.

Restructured files and folders

In order to make the sapphire framework useable without the cms module, we've moved some files around.

CMS base functionality which is not directly related to content pages (SiteTree) has been moved from the cms module into a new "sub-module" located in sapphire/admin. This includes generic management interfaces like "Files & Images" (AssetAdmin), "Security" (SecurityAdmin) and the ModelAdmin class. On the other hand, SiteTree related features were moved from sapphire to the cms module.

Due to the built-in PHP class autoloader, this usually won't have any effect on your own code (unless you're including direct file paths). For any other files (CSS files, templates, images, JavaScript) which might be referenced by their path, please doublecheck that their path is still valid.

Removed prototype.js and and behaviour.js dependencies from most core components

This will only affect you if you used either of those libraries, or by extension on the globals set in prototype_improvements.js and jquery_improvements.js. The $$() shorthand for document.getElementsBySelector() is no longer globally bound, but rather just defined when used through other components. The $() shorthand had two meanings, based on context: Either document.getElementsById() through prototype.js, or as an alias for the jQuery() method. In general, we recommend not to rely on the $() global in SilverStripe, as we unset it via [jQuery.noConflict()](http://api.jquery.com/jQuery.noConflict/). Use a custom alias via function scope if possible.

Moved Translatable extension into new 'translatable' module

If you are translating your SiteTree or DataObject classes with the Translatable extension, please install the new module from http://silverstripe.org/translatable-module. The following settings can be removed from your own _config.php, as they're automatically included through translatable/_config.php:

Object::add_extension('SiteTree', 'Translatable');
Object::add_extension('SiteConfig', 'Translatable');

Moved Group->IPRestrictions into a new 'securityextras' module

IP restrictions for group memberships in the "Security" section were a rarely used feature, and cluttered up the interface. We've decided to move it to a separate module called securityextras. To continue using these restrictions, just install the module - no data migration required.

Removed "auto-merging" of member records from Member->onBeforeWrite()

Due to security reasons. Please use DataObject->merge() explicitly if this is desired behaviour.

Unit tests require definition of used DataObject and Extension classes

This change was necessary in order to improve performance of the test framework, and avoid rebuilding the database where no database access is required. It also won't build any DataObject subclasses implementing the TestOnly interface, unless these are explicitly noted.

• SapphireTest->extraDataObjects: List all TestOnly classes relevant to your test class here.
• SapphireTest->requiredExtensions: Maps DataObject classes to an array of required extensions. Example: array("MyTreeDataObject" => array("Versioned", "Hierarchy"))
• SapphireTest->illegalExtensions: Does the reverse of requiredExtensions: Removes already applied extensions.

Alternatively, you can enforce database usage by setting SapphireTest->usesDatabase to TRUE in your test class.

Breadcrumbs

Breadcrumbs have been altered to be their own template. In the process of this, the common static SiteTree::$breadcrumbs_delimiter has been removed. To customise breadcrumbs now, create a template BreadcrumbsTemplate.ss from cms/template to your theme or application.

Deprecated Classes

• FileIframeField: Use UploadField
• ImageField: Use UploadField with $myField->allowedExtensions = array('jpg', 'gif', 'png')

Renamed Classes

• DataObjectDecorator: Use DataExtension instead (the class doesn't implement the GOF "Decorator" pattern)
• MySQLFulltextSearchable: Use FulltextSearchable instead
• CMSMainMarkingFilter: Use CMSSiteTreeFilter_Search instead *

Removed Classes

• QueuedEmail, QueuedEmailDispatchTask: If you make use of these, copy the classes from 2.4 into your project.
• RestrictedTextField, UniqueTextField, UniqueRestrictedTextField, AutocompleteTextField, ConfirmedFormAction: Use custom fields instead
• TreeSelectorField: Use TreeDropdownField instead.
• Notifications: If you make use of this, copy the classes from 2.4 into your project.
• Archive, TarballArchive: If you make use of these, copy the classes from 2.4 into your project.
• XML: Use PHP's built-in SimpleXML instead
• DataObjectLog: There is no replacement for this.
• GeoIP: Moved to separate "geoip" module
• NZGovtPasswordValidator: Moved to "securityextras" module
• MemberTableField: Use GridField with GridFieldConfig_RelationEditor instead