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](https://github.com/hafriedlander/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](/reference/templates-upgrading-guide) and the
[template reference](/reference/templates) 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](/reference/templates-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](https://github.com/hafriedlander/jquery.entwine) 
based JavaScript logic. Have a look at the new ["Extending the CMS" guide](../howto/extending-the-cms),
["CSS" guide](../topics/css) and ["JavaScript" guide](../topics/javascript) to get you started.

### New tree library ###

The page tree moved from a bespoke tree library to [JSTree](http://jstree.com),
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](http://silverstripe.org/compass-module), which uses
the ["Compass" framework](http://compass-style.org/) and the ["SCSS" language](http://sass-lang.com/).
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()]`.

### 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](http://api.jquery.com/jQuery.noConflict/#example-1) 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](https://github.com/silverstripe-labs/silverstripe-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](http://en.wikipedia.org/wiki/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](https://github.com/silverstripe-labs/silverstripe-geoip)
 * `NZGovtPasswordValidator`: Moved to ["securityextras" module](https://github.com/silverstripe-labs/silverstripe-securityextras)
* `MemberTableField`: Use GridField with GridFieldConfig_RelationEditor instead