mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-10-22 14:05:37 +02:00
Merge pull request #10003 from Michael-HEIW/Silverstripe-dev-guides-part-3
DOC Update SilverStripe to Silverstripe CMS
This commit is contained in:
commit
ec6b010085
@ -58,20 +58,20 @@ see `MySQLDatabase::$sql_mode` for more details.) This setting is only available
|
||||
|
||||
### Overview
|
||||
|
||||
Silverstripe needs to handle a variety of HTTP requests, and relies on the hosting environment to be configured securely
|
||||
Silverstripe CMS needs to handle a variety of HTTP requests, and relies on the hosting environment to be configured securely
|
||||
to enforce restrictions. There are secure defaults in place for Apache, but you should be aware of the configuration
|
||||
regardless of your webserver setup.
|
||||
|
||||
### Public webroot
|
||||
|
||||
The webroot of your webserver should be configured to the `public/` subfolder. Projects created prior to Silverstripe
|
||||
The webroot of your webserver should be configured to the `public/` subfolder. Projects created prior to Silverstripe CMS
|
||||
4.1 might be using the main project folder as the webroot. In this case, you are responsible for ensuring access to
|
||||
system files such as configuration in `*.yml` is protected from public access. We strongly recommend switching to more
|
||||
secure hosting via the `public/`. See [4.1.0 upgrading guide](/changelogs/4.1.0).
|
||||
|
||||
### Filesystem permissions
|
||||
|
||||
During runtime, Silverstripe needs read access for the webserver user to your base path (including your webroot). It
|
||||
During runtime, Silverstripe CMS needs read access for the webserver user to your base path (including your webroot). It
|
||||
also needs write access for the webserver user to the following locations:
|
||||
|
||||
* `public/assets/`: Used by the CMS and other logic to [store uploads](/developer_guides/files/file_storage)
|
||||
@ -81,20 +81,20 @@ also needs write access for the webserver user to the following locations:
|
||||
See [Environment Management](/getting_started/environment_management).
|
||||
|
||||
If you aren't explicitly [packaging](#building-packaging-deployment)
|
||||
your Silverstripe project during your deployment process, additional write access may be required to generate supporting
|
||||
your Silverstripe CMS project during your deployment process, additional write access may be required to generate supporting
|
||||
files on the fly. This is not recommended, because it can lead to extended execution times as well as cause
|
||||
inconsistencies between multiple server environments when manifest and cache storage isn't shared between servers.
|
||||
|
||||
### Assets
|
||||
|
||||
Silverstripe allows CMS authors to upload files into the `public/assets/` folder, which should be served by your
|
||||
Silverstripe CMS allows CMS authors to upload files into the `public/assets/` folder, which should be served by your
|
||||
webserver. **No PHP execution should be allowed in this folder**. This is configured for Apache by default
|
||||
via `public/assets/.htaccess`. The file is generated dynamically during the `dev/build` stage.
|
||||
|
||||
Additionally, access is whitelisted by file extension through a dynamically generated whitelist based on
|
||||
the `File.allowed_extensions` setting
|
||||
(see [File Security](/developer_guides/files/file_security#file-types)). This whitelist uses the same defaults
|
||||
configured through file upload through Silverstripe, so is considered a second line of defence.
|
||||
configured through file upload through Silverstripe CMS, so is considered a second line of defence.
|
||||
|
||||
### Secure Assets {#secure-assets}
|
||||
|
||||
@ -134,9 +134,9 @@ Don't forget to include this additional folder in any syncing and backup process
|
||||
|
||||
### Building, Packaging and Deployment {#building-packaging-deployment}
|
||||
|
||||
It is common to build a Silverstripe application into a package on one environment (e.g. a CI server), and then deploy
|
||||
It is common to build a Silverstripe CMS application into a package on one environment (e.g. a CI server), and then deploy
|
||||
the package to a (separate) webserver environment(s). This approach relies on all auto-generated files required by
|
||||
Silverstripe to be included in the package, or generated on the fly on each webserver environment.
|
||||
Silverstripe CMS to be included in the package, or generated on the fly on each webserver environment.
|
||||
|
||||
The easiest way to ensure this is to commit auto generated files to source control. If those changes are considered too
|
||||
noisy, here's some pointers for auto-generated files to trigger and include in a deployment package:
|
||||
@ -154,14 +154,14 @@ noisy, here's some pointers for auto-generated files to trigger and include in a
|
||||
|
||||
### Web Worker Concurrency
|
||||
|
||||
It's generally a good idea to run multiple workers to serve multiple HTTP requests to Silverstripe concurrently. The
|
||||
It's generally a good idea to run multiple workers to serve multiple HTTP requests to Silverstripe CMS concurrently. The
|
||||
exact number depends on your website needs. The CMS attempts to request multiple views concurrently. It also
|
||||
routes [protected and draft files](/developer_guides/files/file_security)
|
||||
through Silverstripe. This can increase your concurrency requirements, e.g. when authors batch upload and view dozens of
|
||||
through Silverstripe CMS. This can increase your concurrency requirements, e.g. when authors batch upload and view dozens of
|
||||
draft files in the CMS.
|
||||
|
||||
When allowing upload of large files through the CMS (through PHP settings), these files might be used
|
||||
as [protected and draft files](/developer_guides/files/file_security). Files in this state get served by Silverstripe
|
||||
as [protected and draft files](/developer_guides/files/file_security). Files in this state get served by Silverstripe CMS
|
||||
rather than your webserver. Since the framework uses [PHP streams](https://www.php.net/manual/en/ref.stream.php), this
|
||||
allows serving of files larger than your PHP memory limit. Please be aware that streaming operations don't count towards
|
||||
PHP's [max_execution_time](https://www.php.net/manual/en/function.set-time-limit.php), which can risk exhaustion of web
|
||||
@ -169,34 +169,34 @@ worker pools for long-running downloads.
|
||||
|
||||
### URL Rewriting
|
||||
|
||||
Silverstripe expects URL paths to be rewritten to `public/index.php`. For Apache, this is preconfigured
|
||||
Silverstripe CMS expects URL paths to be rewritten to `public/index.php`. For Apache, this is preconfigured
|
||||
through `.htaccess` files, and expects using the `mod_rewrite` module. By default, these files are located
|
||||
in `public/.htaccess` and `public/assets/.htaccess`.
|
||||
|
||||
### HTTP Headers
|
||||
|
||||
Silverstripe can add HTTP headers to responses it handles directly. These headers are often sensitive, for example
|
||||
Silverstripe CMS can add HTTP headers to responses it handles directly. These headers are often sensitive, for example
|
||||
preventing HTTP caching for responses displaying data based on user sessions, or when serving protected assets. You need
|
||||
to ensure those headers are kept in place in your webserver. For example, Apache allows this
|
||||
through `Header setifempty` (see [docs](https://httpd.apache.org/docs/current/mod/mod_headers.html#header)).
|
||||
See [Developer Guide: Performance](/developer_guides/performance/)
|
||||
and [Developer Guides: File Security](/developer_guides/files/file_security) for more details.
|
||||
|
||||
Silverstripe relies on the `Host` header to construct URLs such as "reset password" links, so you'll need to ensure that
|
||||
Silverstripe CMS relies on the `Host` header to construct URLs such as "reset password" links, so you'll need to ensure that
|
||||
the systems hosting it only allow valid values for this header.
|
||||
See [Developer Guide: Security - Request hostname forgery](/developer_guides/security/secure_coding#request-hostname-forgery)
|
||||
.
|
||||
|
||||
### CDNs and other Reverse Proxies
|
||||
|
||||
If your Silverstripe site is hosted behind multiple HTTP layers, you're in charge of controlling which forwarded headers
|
||||
If your Silverstripe CMS site is hosted behind multiple HTTP layers, you're in charge of controlling which forwarded headers
|
||||
are considered valid, and which IPs can set them.
|
||||
See [Developer Guide: Security - Request hostname forgery](/developer_guides/security/secure_coding#request-hostname-forgery)
|
||||
.
|
||||
|
||||
### Symlinks
|
||||
|
||||
Silverstripe is a modular system, with modules installed and updated via the `composer` PHP dependency manager. These
|
||||
Silverstripe CMS is a modular system, with modules installed and updated via the `composer` PHP dependency manager. These
|
||||
are usually stored in `vendor/`, outside of the `public/` webroot. Since many modules rely on serving frontend assets
|
||||
such as CSS files or images, these are mapped over to the `public/_resources/` folder automatically. If the filesystem
|
||||
supports it, this is achieved through symlinks. Depending on your hosting and deployment mechanisms, you may need to
|
||||
@ -205,7 +205,7 @@ See [silverstripe/vendor-plugin](https://github.com/silverstripe/vendor-plugin)
|
||||
|
||||
### Caches
|
||||
|
||||
Silverstripe relies on various [caches](/developer_guides/performance/caching/)
|
||||
Silverstripe CMS relies on various [caches](/developer_guides/performance/caching/)
|
||||
to achieve performant responses. By default, those caches are stored in a temporary filesystem folder, and are not
|
||||
shared between multiple server instances. Alternative cache backends such as Redis can be
|
||||
[configured](/developer_guides/performance/caching/).
|
||||
@ -232,12 +232,12 @@ through the CMS.
|
||||
There are various community supported installation instructions for different environments. Nginx is a popular choice,
|
||||
see [Nginx webserver configuration](https://forum.silverstripe.org/t/nginx-webserver-configuration/2246).
|
||||
|
||||
Silverstripe is known to work with Microsoft IIS, and generates `web.config` files by default
|
||||
Silverstripe CMS is known to work with Microsoft IIS, and generates `web.config` files by default
|
||||
(
|
||||
see [Microsoft IIS and SQL Server configuration](https://forum.silverstripe.org/t/microsoft-iis-webserver-and-sql-server-support/2245))
|
||||
.
|
||||
|
||||
Additionally, there are community supported guides for installing Silverstripe on various environments:
|
||||
Additionally, there are community supported guides for installing Silverstripe CMS on various environments:
|
||||
|
||||
* [Hosting via Bitnami](https://bitnami.com/stack/silverstripe/virtual-machine): In the cloud or as a locally hosted
|
||||
virtual machine
|
||||
@ -248,12 +248,12 @@ Additionally, there are community supported guides for installing Silverstripe o
|
||||
* [Vagrant with silverstripe-australia/vagrant-environment](https://github.com/silverstripe-australia/vagrant-environment)
|
||||
* [Vagrant with BetterBrief/vagrant-skeleton](https://github.com/BetterBrief/vagrant-skeleton)
|
||||
|
||||
## PHP Requirements for older Silverstripe releases {#php-support}
|
||||
## PHP Requirements for older Silverstripe CMS releases {#php-support}
|
||||
|
||||
Silverstripe's PHP support has changed over time and if you are looking to upgrade PHP on your Silverstripe site, this
|
||||
Silverstripe CMS's PHP support has changed over time and if you are looking to upgrade PHP on your Silverstripe CMS site, this
|
||||
table may be of use:
|
||||
|
||||
| Silverstripe Version | PHP Version | More information |
|
||||
| Silverstripe CMS Version | PHP Version | More information |
|
||||
| -------------------- | ----------- | ---------------- |
|
||||
| 3.0 - 3.5 | 5.3 - 5.6 | [requirements docs](https://docs.silverstripe.org/en/3.4/getting_started/server_requirements/)
|
||||
| 3.6 | 5.3 - 7.1 | |
|
||||
@ -265,11 +265,6 @@ table may be of use:
|
||||
|
||||
Silverstripe CMS supports the following web browsers:
|
||||
|
||||
* Google Chrome
|
||||
* Internet Explorer 11
|
||||
* Microsoft Edge
|
||||
* Mozilla Firefox
|
||||
|
||||
We aim to provide satisfactory experiences in Apple Safari. Silverstripe CMS works well across Windows, Linux, and Mac
|
||||
operating systems.
|
||||
|
||||
|
@ -3,11 +3,11 @@ title: Composer
|
||||
summary: What is composer and how to use it with Silverstripe CMS
|
||||
---
|
||||
|
||||
# Using Silverstripe with Composer
|
||||
# Using Silverstripe CMS with Composer
|
||||
|
||||
## Requirements
|
||||
|
||||
[Composer](http://getcomposer.org/) is a package management tool for PHP that lets you install and upgrade Silverstripe
|
||||
[Composer](http://getcomposer.org/) is a package management tool for PHP that lets you install and upgrade Silverstripe CMS
|
||||
and its modules. We also have separate instructions
|
||||
for [installing modules with Composer](/developer_guides/extending/modules).
|
||||
|
||||
@ -49,14 +49,14 @@ composer create-project silverstripe/installer ./my-project 4.3.3
|
||||
```
|
||||
|
||||
When `create-project` is used with a release version like above, it will try to get the code from archives instead of
|
||||
creating git repositories. If you're planning to contribute to Silverstripe,
|
||||
creating git repositories. If you're planning to contribute to Silverstripe CMS,
|
||||
see [Using development versions](#using-development-versions).
|
||||
|
||||
## Adding modules to your project
|
||||
|
||||
Composer isn't only used to download Silverstripe CMS, it is also used to manage all Silverstripe modules. You can find
|
||||
thousands of modules on [https://addons.silverstripe.org](https://addons.silverstripe.org). Installing a module can be
|
||||
done with the following command:
|
||||
Composer isn't only used to download Silverstripe CMS, it is also used to manage all Silverstripe CMS modules.
|
||||
You can find thousands of modules on [https://addons.silverstripe.org](https://addons.silverstripe.org).
|
||||
Installing a module can be done with the following command:
|
||||
|
||||
```
|
||||
composer require silverstripe/blog
|
||||
@ -79,7 +79,7 @@ a little different. The version string for the `4` branch is `4.x-dev`.
|
||||
## Updating dependencies
|
||||
|
||||
Except for the control code of the Voyager space probe, every piece of code in the universe gets updated from time to
|
||||
time. Silverstripe modules are no exception.
|
||||
time. Silverstripe CMS modules are no exception.
|
||||
|
||||
To get the latest updates of the modules in your project, run this command:
|
||||
|
||||
@ -111,14 +111,14 @@ So your deployment process, as it relates to Composer, should be as follows:
|
||||
|
||||
## Composer managed modules, Git and .gitignore
|
||||
|
||||
Modules and themes managed by Composer should not be committed with your projects source code. Silverstripe ships with
|
||||
Modules and themes managed by Composer should not be committed with your projects source code. Silverstripe CMS ships with
|
||||
a [.gitignore](http://git-scm.com/docs/gitignore) file by default which prevents this. For more details
|
||||
read [Should I commit the dependencies in my vendor directory?](https://getcomposer.org/doc/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md)
|
||||
.
|
||||
|
||||
## Dev Environments for Contributing Code {#contributing}
|
||||
|
||||
So you want to contribute to Silverstripe? Fantastic! You can do this with composer too. You have to tell composer three
|
||||
So you want to contribute to Silverstripe CMS? Fantastic! You can do this with composer too. You have to tell composer three
|
||||
things in order to be able to do this:
|
||||
|
||||
- Keep the full git repository information
|
||||
@ -138,11 +138,11 @@ on [composer version naming](http://getcomposer.org/doc/02-libraries.md#specifyi
|
||||
|
||||
The `--keep-vcs` flag will make sure you have access to the git history of the installer and the requirements
|
||||
|
||||
The `--dev` flag is optional, and can be used to add a couple modules which are useful for Silverstripe development:
|
||||
The `--dev` flag is optional, and can be used to add a couple modules which are useful for Silverstripe CMS development:
|
||||
|
||||
* The `behat-extension` module allows running [Behat](http://behat.org) integration tests
|
||||
* The `docsviewer` module will let you preview changes to the project documentation
|
||||
* The `buildtools` module which adds [phing](http://phing.info) tasks for creating Silverstripe releases
|
||||
* The `buildtools` module which adds [phing](http://phing.info) tasks for creating Silverstripe CMS releases
|
||||
|
||||
Once the `create-project` command completes, you need to edit the `composer.json` in the project root and remove
|
||||
the `@stable` markers from the `silverstripe/cms` and `silverstripe/framework` version entries.
|
||||
@ -194,7 +194,7 @@ is to ensure that when developers are getting started, running `composer update`
|
||||
unstable version
|
||||
|
||||
However it is relatively easy to tell composer to use development versions. Not only is this required if you want to
|
||||
contribute back to the Silverstripe project, it also allows you to get fixes and API changes early.
|
||||
contribute back to the Silverstripe CMS project, it also allows you to get fixes and API changes early.
|
||||
|
||||
This is a two step process. First you get composer to start a project based on the latest unstable
|
||||
silverstripe/installer
|
||||
@ -324,7 +324,7 @@ on [packagist.org](http://packagist.org).
|
||||
|
||||
Follow the packagist.org advice on choosing a [unique name and vendor prefix](https://packagist.org/about). Please don't
|
||||
use the `silverstripe/<modulename>` vendor prefix, since that's reserved for modules produced by Silverstripe Ltd. In
|
||||
order to declare that your module is in fact a Silverstripe module, use the "silverstripe" tag in the composer.json
|
||||
order to declare that your module is in fact a Silverstripe CMS module, use the "silverstripe" tag in the composer.json
|
||||
file, and set the "type" to "silverstripe-module".
|
||||
|
||||
### What about themes?
|
||||
|
@ -13,7 +13,7 @@ information.
|
||||
* Each database row maps to a PHP object.
|
||||
* Each database column maps to a property on a PHP object.
|
||||
|
||||
All data tables in Silverstripe are defined as subclasses of [DataObject](api:SilverStripe\ORM\DataObject). The [DataObject](api:SilverStripe\ORM\DataObject) class represents a
|
||||
All data tables in Silverstripe CMS are defined as subclasses of [DataObject](api:SilverStripe\ORM\DataObject). The [DataObject](api:SilverStripe\ORM\DataObject) class represents a
|
||||
single row in a database table, following the ["Active Record"](http://en.wikipedia.org/wiki/Active_record_pattern)
|
||||
design pattern. Database Columns are defined as [Data Types](/developer_guides/model/data_types_and_casting) in the static `$db` variable
|
||||
along with any [relationships](relations) defined as `$has_one`, `$has_many`, `$many_many` properties on the class.
|
||||
@ -41,7 +41,7 @@ so on. After writing this class, we need to regenerate the database schema.
|
||||
|
||||
## Generating the Database Schema
|
||||
|
||||
After adding, modifying or removing `DataObject` subclasses, make sure to rebuild your Silverstripe database. The
|
||||
After adding, modifying or removing `DataObject` subclasses, make sure to rebuild your Silverstripe CMS database. The
|
||||
database schema is generated automatically by visiting the URL http://www.yoursite.com/dev/build while authenticated as an administrator.
|
||||
|
||||
This script will analyze the existing schema, compare it to what's required by your data classes, and alter the schema
|
||||
@ -60,7 +60,7 @@ It **won't** do any of the following
|
||||
* Delete tables
|
||||
* Delete fields
|
||||
* Rename any tables that it doesn't recognize. This allows other applications to coexist in the same database, as long as
|
||||
their table names don't match a Silverstripe data class.
|
||||
their table names don't match a Silverstripe CMS data class.
|
||||
|
||||
|
||||
[notice]
|
||||
@ -129,7 +129,7 @@ Using the `create()` method provides chainability, which can add elegance and br
|
||||
[/notice]
|
||||
|
||||
|
||||
Database columns and properties can be set as class properties on the object. The Silverstripe ORM handles the saving
|
||||
Database columns and properties can be set as class properties on the object. The Silverstripe CMS ORM handles the saving
|
||||
of the values through a custom `__set()` method.
|
||||
|
||||
```php
|
||||
@ -692,7 +692,7 @@ Note: Alternatively you can set defaults directly in the database-schema (rather
|
||||
## Subclasses
|
||||
|
||||
Inheritance is supported in the data model: separate tables will be linked together, the data spread across these
|
||||
tables. The mapping and saving logic is handled by Silverstripe, you don't need to worry about writing SQL most of the
|
||||
tables. The mapping and saving logic is handled by Silverstripe CMS , you don't need to worry about writing SQL most of the
|
||||
time.
|
||||
|
||||
For example, suppose we have the following set of classes:
|
||||
@ -751,7 +751,7 @@ The way the ORM stores the data is this:
|
||||
* In all the tables, ID is the primary key. A matching ID number is used for all parts of a particular record:
|
||||
record #2 in Page refers to the same object as record #2 in [SiteTree](api:SilverStripe\CMS\Model\SiteTree).
|
||||
|
||||
To retrieve a news article, Silverstripe joins the [SiteTree](api:SilverStripe\CMS\Model\SiteTree), [Page](api:SilverStripe\CMS\Model\SiteTree\Page) and NewsPage tables by their ID fields.
|
||||
To retrieve a news article, Silverstripe CMS joins the [SiteTree](api:SilverStripe\CMS\Model\SiteTree), [Page](api:SilverStripe\CMS\Model\SiteTree\Page) and NewsPage tables by their ID fields.
|
||||
|
||||
## Related Lessons
|
||||
* [Introduction to the ORM](https://www.silverstripe.org/learn/lessons/v4/introduction-to-the-orm-1)
|
||||
|
@ -11,7 +11,7 @@ to one another. An example of this is a `Player` object may have a relationship
|
||||
and could take part in many `Games`. Relations are a key part of designing and building a good data model.
|
||||
|
||||
Relations are built through static array definitions on a class, in the format `<relationship-name> => <classname>`.
|
||||
SilverStripe supports a number of relationship types and each relationship type can have any number of relations.
|
||||
Silverstripe CMS supports a number of relationship types and each relationship type can have any number of relations.
|
||||
|
||||
## has_one
|
||||
|
||||
|
@ -6,10 +6,10 @@ icon: code
|
||||
|
||||
# Data Types and Casting
|
||||
|
||||
Each model in a SilverStripe [DataObject](api:SilverStripe\ORM\DataObject) will handle data at some point. This includes database columns such as
|
||||
Each model in a Silverstripe CMS [DataObject](api:SilverStripe\ORM\DataObject) will handle data at some point. This includes database columns such as
|
||||
the ones defined in a `$db` array or simply a method that returns data for the template.
|
||||
|
||||
A Data Type is represented in SilverStripe by a [DBField](api:SilverStripe\ORM\FieldType\DBField) subclass. The class is responsible for telling the ORM
|
||||
A Data Type is represented in Silverstripe CMS by a [DBField](api:SilverStripe\ORM\FieldType\DBField) subclass. The class is responsible for telling the ORM
|
||||
about how to store its data in the database and how to format the information coming out of the database, i.e. on a template.
|
||||
|
||||
In the `Player` example, we have four database columns each with a different data type (Int, Varchar).
|
||||
@ -157,7 +157,7 @@ class Player extends DataObject
|
||||
}
|
||||
```
|
||||
|
||||
The properties on any SilverStripe object can be type casted automatically, by transforming its scalar value into an
|
||||
The properties on any Silverstripe CMS object can be type casted automatically, by transforming its scalar value into an
|
||||
instance of the [DBField](api:SilverStripe\ORM\FieldType\DBField) class, providing additional helpers. For example, a string can be cast as a [DBText](api:SilverStripe\ORM\FieldType\DBText)
|
||||
type, which has a `FirstSentence()` method to retrieve the first sentence in a longer piece of text.
|
||||
|
||||
@ -179,7 +179,7 @@ DBField::create_field('Date', '1982-01-01')->TimeDiff(); // shows "30 years ago"
|
||||
|
||||
## Casting ViewableData
|
||||
|
||||
Most objects in SilverStripe extend from [ViewableData](api:SilverStripe\View\ViewableData), which means they know how to present themselves in a view
|
||||
Most objects in Silverstripe CMS extend from [ViewableData](api:SilverStripe\View\ViewableData), which means they know how to present themselves in a view
|
||||
context. Through a `$casting` array, arbitrary properties and getters can be casted:
|
||||
|
||||
```php
|
||||
|
@ -10,11 +10,11 @@ iconBrand: searchengin
|
||||
|
||||
An object representing a SQL select query, which can be serialized into a SQL statement.
|
||||
It is easier to deal with object-wrappers than string-parsing a raw SQL-query.
|
||||
This object is used by the SilverStripe ORM internally.
|
||||
This object is used by the Silverstripe CMS ORM internally.
|
||||
|
||||
Dealing with low-level SQL is not encouraged, since the ORM provides
|
||||
powerful abstraction APIs (see [datamodel](/developer_guides/model/data_model_and_orm)).
|
||||
Starting with SilverStripe 3, records in collections are lazy loaded,
|
||||
Starting with Silverstripe CMS 3, records in collections are lazy loaded,
|
||||
and these collections have the ability to run efficient SQL
|
||||
such as counts or returning a single column.
|
||||
|
||||
@ -296,7 +296,7 @@ $map = $players->map('Name', 'NameWithBirthyear');
|
||||
|
||||
### Data types
|
||||
|
||||
As of SilverStripe 4.4, the following PHP types will be used to return database content:
|
||||
As of Silverstripe CMS 4.4, the following PHP types will be used to return database content:
|
||||
|
||||
* booleans will be an integer 1 or 0, to ensure consistency with MySQL that doesn't have native booleans
|
||||
* integer types returned as integers
|
||||
@ -304,7 +304,7 @@ As of SilverStripe 4.4, the following PHP types will be used to return database
|
||||
* strings returned as strings
|
||||
* dates / datetimes returned as strings
|
||||
|
||||
Up until SilverStripe 4.3, bugs meant that strings were used for every column type.
|
||||
Up until Silverstripe CMS 4.3, bugs meant that strings were used for every column type.
|
||||
|
||||
## Related Lessons
|
||||
* [Building custom SQL](https://www.silverstripe.org/learn/lessons/v4/beyond-the-orm-building-custom-sql-1)
|
||||
|
@ -6,12 +6,12 @@ icon: check-square
|
||||
|
||||
# Validation and Constraints
|
||||
|
||||
Traditionally, validation in SilverStripe has been mostly handled on the controller through [form validation](../forms).
|
||||
Traditionally, validation in Silverstripe CMS has been mostly handled on the controller through [form validation](../forms).
|
||||
|
||||
While this is a useful approach, it can lead to data inconsistencies if the record is modified outside of the
|
||||
controller and form context.
|
||||
|
||||
Most validation constraints are actually data constraints which belong on the model. SilverStripe provides the
|
||||
Most validation constraints are actually data constraints which belong on the model. Silverstripe CMS provides the
|
||||
[DataObject::validate()](api:SilverStripe\ORM\DataObject::validate()) method for this purpose.
|
||||
|
||||
By default, there is no validation - objects are always valid! However, you can overload this method in your DataObject
|
||||
|
@ -5,13 +5,13 @@ summary: Add versioning to your database content through the Versioned extension
|
||||
|
||||
# Versioning
|
||||
|
||||
Database content in SilverStripe can be "staged" before its publication, as well as track all changes through the
|
||||
Database content in Silverstripe CMS can be "staged" before its publication, as well as track all changes through the
|
||||
lifetime of a database record.
|
||||
|
||||
It is most commonly applied to pages in the CMS (the `SiteTree` class). Draft content edited in the CMS can be different
|
||||
from published content shown to your website visitors.
|
||||
|
||||
Versioning in SilverStripe is handled through the [Versioned](api:SilverStripe\Versioned\Versioned) class. As a [DataExtension](api:SilverStripe\ORM\DataExtension) it is possible to be applied to any [DataObject](api:SilverStripe\ORM\DataObject) subclass. The extension class will automatically update read and write operations done via the ORM via the `augmentSQL` database hook.
|
||||
Versioning in Silverstripe CMS is handled through the [Versioned](api:SilverStripe\Versioned\Versioned) class. As a [DataExtension](api:SilverStripe\ORM\DataExtension) it is possible to be applied to any [DataObject](api:SilverStripe\ORM\DataObject) subclass. The extension class will automatically update read and write operations done via the ORM via the `augmentSQL` database hook.
|
||||
|
||||
[notice]
|
||||
There are two complementary modules that improve content editor experience around "owned" nested objects (e.g. elemental blocks).
|
||||
@ -31,11 +31,11 @@ The second module extends CMS History UI adding control over nested objects.
|
||||
|
||||
## Understanding versioning concepts
|
||||
|
||||
This section discusses how SilverStripe implements versioning and related high level concepts without digging into technical details.
|
||||
This section discusses how Silverstripe CMS implements versioning and related high level concepts without digging into technical details.
|
||||
|
||||
### Stages
|
||||
|
||||
In most cases, you'll want to have one polished version of a `Page` visible to the general public while your editors might be working off a draft version. SilverStripe handles this through the concept of _stage_.
|
||||
In most cases, you'll want to have one polished version of a `Page` visible to the general public while your editors might be working off a draft version. Silverstripe CMS handles this through the concept of _stage_.
|
||||
|
||||
By default, adding the `Versioned` extension to a DataObject will create 2 stages:
|
||||
* "Stage" for tracking draft content
|
||||
@ -61,7 +61,7 @@ and has_one/has_many, however it relies on a pre-existing relationship to functi
|
||||
|
||||
If an object "owns" other objects, you'll usually want to publish the child objects when the parent object gets published. If those child objects themselves own other objects, you'll want the grand-children to be published along with the parent.
|
||||
|
||||
SilverStripe makes this possible by using the concept of _cascade publishing_. You can choose to recursively publish an object. When an object is recursively published – either through a user action or through code – all other records it owns that implement the Versioned extension will automatically be published. Publication will also cascade to children of children and so on.
|
||||
Silverstripe CMS makes this possible by using the concept of _cascade publishing_. You can choose to recursively publish an object. When an object is recursively published – either through a user action or through code – all other records it owns that implement the Versioned extension will automatically be published. Publication will also cascade to children of children and so on.
|
||||
|
||||
A non-recursive publish operation is also available if you want to publish a new version of a object without cascade publishing all its children.
|
||||
|
||||
@ -79,7 +79,7 @@ An unversioned object can also be owned by a versioned object. This can be used
|
||||
|
||||
#### Ownership through media insertion in content
|
||||
|
||||
Images and other files are tracked as versioned objects. If a file is referenced through an HTML text field, it needs to be published for it to be accessible to the public. SilverStripe will automatically pick up when an object references files through an HTML text field and recursively publish those files.
|
||||
Images and other files are tracked as versioned objects. If a file is referenced through an HTML text field, it needs to be published for it to be accessible to the public. Silverstripe CMS will automatically pick up when an object references files through an HTML text field and recursively publish those files.
|
||||
|
||||
This behavior works both for versioned and unversioned objects.
|
||||
|
||||
@ -201,7 +201,7 @@ Note that ownership cannot be used with polymorphic relations. E.g. has_one to n
|
||||
|
||||
#### Unversioned DataObject ownership
|
||||
|
||||
*Requires SilverStripe 4.1 or newer*
|
||||
*Requires Silverstripe CMS 4.1 or newer*
|
||||
|
||||
Ownership can be used with non-versioned DataObjects, as the necessary functionality is included by default
|
||||
by the versioned object through the [`RecursivePublishable`](api:SilverStripe\Versioned\RecursivePublishable) extension which is
|
||||
@ -591,7 +591,7 @@ The current stage for each request is determined by `VersionedHTTPMiddleware` be
|
||||
`Versioned::choose_site_stage()`. It checks for a `stage` GET parameter, so you can force a draft stage by appending
|
||||
`?stage=Stage` to your request.
|
||||
|
||||
Since SilverStripe 4.2, the current stage setting is no longer "sticky" in the session.
|
||||
Since Silverstripe CMS 4.2, the current stage setting is no longer "sticky" in the session.
|
||||
Any links presented on the view produced with `?stage=Stage` need to have the same GET parameters in order
|
||||
to retain the stage. If you are using the `SiteTree->Link()` and `Controller->Link()` methods,
|
||||
this is automatically the case for `DataObject` links, controller links and form actions.
|
||||
@ -842,7 +842,7 @@ public function init()
|
||||
|
||||
### Low level write and publication methods
|
||||
|
||||
SilverStripe will usually call these low level methods for you. However if you have specialised needs, you may call them directly.
|
||||
Silverstripe CMS will usually call these low level methods for you. However if you have specialised needs, you may call them directly.
|
||||
|
||||
To move a saved version from one stage to another, call [writeToStage(stage)](api:SilverStripe\Versioned\Versioned::writeToStage()) on the object. This is used internally to publish DataObjects.
|
||||
|
||||
@ -861,7 +861,7 @@ Versioned::set_reading_mode($origMode); // reset current mode
|
||||
|
||||
## Using the history viewer
|
||||
|
||||
Since SilverStripe 4.3 you can use the React and GraphQL driven history viewer UI to display historic changes and
|
||||
Since Silverstripe CMS 4.3 you can use the React and GraphQL driven history viewer UI to display historic changes and
|
||||
comparisons for a versioned DataObject. This is automatically enabled for SiteTree objects and content blocks in
|
||||
[dnadesign/silverstripe-elemental](https://github.com/dnadesign/silverstripe-elemental).
|
||||
|
||||
@ -873,7 +873,7 @@ If you want to enable the history viewer for a custom versioned DataObject, you
|
||||
* Add a HistoryViewerField to the DataObject's `getCMSFields`
|
||||
|
||||
**Please note:** these examples are given in the context of project-level customisation. You may need to adjust
|
||||
the webpack configuration slightly for use in a module. They are also designed to be used on SilverStripe 4.3 or
|
||||
the webpack configuration slightly for use in a module. They are also designed to be used on Silverstripe CMS 4.3 or
|
||||
later.
|
||||
|
||||
For these examples, you can use this simple DataObject and create a ModelAdmin for it:
|
||||
|
@ -7,13 +7,13 @@ icon: hammer
|
||||
# Scaffolding
|
||||
|
||||
The ORM already has a lot of information about the data represented by a `DataObject` through its `$db` property, so
|
||||
SilverStripe will use that information to scaffold some interfaces. This is done though [FormScaffolder](api:SilverStripe\Forms\FormScaffolder)
|
||||
Silverstripe CMS will use that information to scaffold some interfaces. This is done though [FormScaffolder](api:SilverStripe\Forms\FormScaffolder)
|
||||
to provide reasonable defaults based on the property type (e.g. a checkbox field for booleans). You can then further
|
||||
customise those fields as required.
|
||||
|
||||
## Form Fields
|
||||
|
||||
An example is `DataObject`, SilverStripe will automatically create your CMS interface so you can modify what you need.
|
||||
An example is `DataObject`, Silverstripe CMS will automatically create your CMS interface so you can modify what you need.
|
||||
|
||||
```php
|
||||
use SilverStripe\ORM\DataObject;
|
||||
|
@ -12,12 +12,12 @@ The addition of an indexes should be carefully evaluated as they can also increa
|
||||
`UPDATE`/`INSERT` and `DELETE`. An index on a column whose data is non unique will actually cost you performance.
|
||||
E.g. In most cases an index on `boolean` status flag, or `ENUM` state will not increase query performance.
|
||||
|
||||
It's important to find the right balance to achieve fast queries using the optimal set of indexes; For SilverStripe
|
||||
It's important to find the right balance to achieve fast queries using the optimal set of indexes; For Silverstripe CMS
|
||||
applications it's a good practice to:
|
||||
- add indexes on columns which are frequently used in `filter`, `where` or `orderBy` statements
|
||||
- for these, only include indexes for columns which are the most restrictive (return the least number of rows)
|
||||
|
||||
The SilverStripe framework already places certain indexes for you by default:
|
||||
The Silverstripe CMS framework already places certain indexes for you by default:
|
||||
- The primary key for each model has a `PRIMARY KEY` unique index
|
||||
- The `ClassName` column if your model inherits from `DataObject`
|
||||
- All relationships defined in the model have indexes for their `has_one` entity (for `many_many` relationships
|
||||
@ -73,7 +73,7 @@ class MyTestObject extends DataObject
|
||||
```
|
||||
|
||||
[alert]
|
||||
Please note that if you have previously used the removed `value` key to define an index's contents, SilverStripe will
|
||||
Please note that if you have previously used the removed `value` key to define an index's contents, Silverstripe CMS will
|
||||
now throw an error. Use `columns` instead.
|
||||
[/alert]
|
||||
|
||||
|
@ -23,7 +23,7 @@ Similarly, the `GroupedBy()` method builds on this and returns the same data in
|
||||
|
||||
This example deals with breaking up a [SS_List](api:SilverStripe\ORM\SS_List) into sub-headings by the first letter.
|
||||
|
||||
Let's say you have a set of Module objects, each representing a SilverStripe module, and you want to output a list of
|
||||
Let's say you have a set of Module objects, each representing a Silverstripe CMS module, and you want to output a list of
|
||||
these in alphabetical order, with each letter as a heading; something like the following list:
|
||||
|
||||
* B
|
||||
|
@ -1,11 +1,11 @@
|
||||
---
|
||||
title: Model and Databases
|
||||
summary: Learn how SilverStripe manages database tables, ways to query your database and how to publish data.
|
||||
introduction: This guide will cover how to create and manipulate data within SilverStripe and how to use the ORM (Object Relational Model) to query data.
|
||||
summary: Learn how Silverstripe CMS manages database tables, ways to query your database and how to publish data.
|
||||
introduction: This guide will cover how to create and manipulate data within Silverstripe CMS and how to use the ORM (Object Relational Model) to query data.
|
||||
icon: database
|
||||
---
|
||||
|
||||
In SilverStripe, application data will be represented by a [DataObject](api:SilverStripe\ORM\DataObject) class. A `DataObject` subclass defines the
|
||||
In Silverstripe CMS, application data will be represented by a [DataObject](api:SilverStripe\ORM\DataObject) class. A `DataObject` subclass defines the
|
||||
data columns, relationships and properties of a particular data record. For example, [Member](api:SilverStripe\Security\Member) is a `DataObject`
|
||||
which stores information about a person, CMS user or mail subscriber.
|
||||
|
||||
|
@ -10,7 +10,7 @@ A template can contain any markup language (e.g HTML, CSV, JSON..) and before be
|
||||
processed through [SSViewer](api:SilverStripe\View\SSViewer). This process replaces placeholders such as `$Var` with real content from your
|
||||
[model](../model) and allows you to define logic controls like `<% if $Var %>`.
|
||||
|
||||
An example of a SilverStripe template is below:
|
||||
An example of a Silverstripe CMS template is below:
|
||||
|
||||
**app/templates/Page.ss**
|
||||
|
||||
@ -50,7 +50,7 @@ text-based format.
|
||||
|
||||
## Template file location
|
||||
|
||||
SilverStripe templates are plain text files that have an `.ss` extension and are located within the `templates` directory of
|
||||
Silverstripe CMS templates are plain text files that have an `.ss` extension and are located within the `templates` directory of
|
||||
a module, theme, or your `app/` folder.
|
||||
|
||||
By default, templates will have the same name as the class they are used to render. So, your `Page` class will
|
||||
@ -236,7 +236,7 @@ You can use inequalities like `<`, `<=`, `>`, `>=` to compare numbers.
|
||||
|
||||
## Includes
|
||||
|
||||
Within SilverStripe templates we have the ability to include other templates using the `<% include %>` tag. The includes
|
||||
Within Silverstripe CMS templates we have the ability to include other templates using the `<% include %>` tag. The includes
|
||||
will be searched for using the same filename look-up rules as a regular template. However in the case of the include tag
|
||||
an additional `Includes` directory will be inserted into the resolved path just prior to the filename.
|
||||
|
||||
@ -564,7 +564,7 @@ Using standard HTML comments is supported. These comments will be included in th
|
||||
$EditForm <!-- Some public comment about the form -->
|
||||
```
|
||||
|
||||
However you can also use special SilverStripe comments which will be stripped out of the published site. This is useful
|
||||
However you can also use special Silverstripe CMS comments which will be stripped out of the published site. This is useful
|
||||
for adding notes for other developers but for things you don't want published in the public html.
|
||||
|
||||
```ss
|
||||
|
@ -5,7 +5,7 @@ summary: Some of the common variables and methods your templates can use, includ
|
||||
|
||||
# Common Variables
|
||||
|
||||
The page below describes a few of common variables and methods you'll see in a SilverStripe template. This is not an
|
||||
The page below describes a few of common variables and methods you'll see in a Silverstripe CMS template. This is not an
|
||||
exhaustive list. From your template you can call any method, database field, or relation on the object which is
|
||||
currently in scope as well as its subclasses or extensions.
|
||||
|
||||
@ -47,7 +47,7 @@ to locate your site’s images and css files.
|
||||
It renders in the template as `<base href="http://www.yoursite.com" /><!--[if lte IE 6]></base><![endif]-->`
|
||||
|
||||
[alert]
|
||||
A `<% base_tag %>;` is nearly always required or assumed by SilverStripe to exist.
|
||||
A `<% base_tag %>;` is nearly always required or assumed by Silverstripe CMS to exist.
|
||||
[/alert]
|
||||
|
||||
## CurrentMember
|
||||
@ -67,7 +67,7 @@ $Title
|
||||
$MenuTitle
|
||||
```
|
||||
|
||||
Most objects within SilverStripe will respond to `$Title` (i.e they should have a `Title` database field or at least a
|
||||
Most objects within Silverstripe CMS will respond to `$Title` (i.e they should have a `Title` database field or at least a
|
||||
`getTitle()` method).
|
||||
|
||||
The CMS module in particular provides two fields to label a page: `Title` and `MenuTitle`. `Title` is the title
|
||||
@ -127,14 +127,14 @@ By default `$MetaTags` renders:
|
||||
|
||||
```ss
|
||||
<title>Title of the Page</title>
|
||||
<meta name="generator" http-equiv="generator" content="SilverStripe 3.0" />
|
||||
<meta name="generator" content="SilverStripe - https://www.silverstripe.org">
|
||||
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
|
||||
```
|
||||
|
||||
`$MetaTags(false)` will render
|
||||
|
||||
```ss
|
||||
<meta name="generator" http-equiv="generator" content="SilverStripe 3.0" />
|
||||
<meta name="generator" content="SilverStripe - https://www.silverstripe.org">
|
||||
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
|
||||
```
|
||||
|
||||
@ -172,7 +172,7 @@ public function MetaComponents()
|
||||
<a href="$Link">..</a>
|
||||
```
|
||||
|
||||
All objects that could be accessible in SilverStripe should define a `Link` method and an `AbsoluteLink` method. Link
|
||||
All objects that could be accessible in Silverstripe CMS should define a `Link` method and an `AbsoluteLink` method. Link
|
||||
returns the relative URL for the object and `AbsoluteLink` outputs your full website address along with the relative
|
||||
link.
|
||||
|
||||
@ -382,7 +382,7 @@ $Form
|
||||
```
|
||||
|
||||
A page will normally contain some content and potentially a form of some kind. For example, the log-in page has a
|
||||
SilverStripe log-in form. If you are on such a page, the `$Form` variable will contain the HTML content of the form.
|
||||
Silverstripe CMS log-in form. If you are on such a page, the `$Form` variable will contain the HTML content of the form.
|
||||
Placing it just below `$Content` is a good default.
|
||||
|
||||
|
||||
|
@ -11,20 +11,20 @@ coding any references in the `<head>` tag of your template, as it enables a more
|
||||
[Requirements](api:SilverStripe\View\Requirements) class.
|
||||
|
||||
The examples below are using certain folder naming conventions (CSS files in `css/`, JavaScript files in `javascript/`).
|
||||
SilverStripe core modules like `cms` use a different naming convention (CSS and JavaScript files in `client/src/`).
|
||||
Silverstripe CMS core modules like `cms` use a different naming convention (CSS and JavaScript files in `client/src/`).
|
||||
The `Requirements` class can work with arbitrary file paths.
|
||||
|
||||
## Exposing static assets
|
||||
|
||||
Before requiring static asset files in PHP code or in a template, those assets need to be "exposed". This process allows SilverStripe projects and SilverStripe modules to make static asset files available via the web server from locations that would otherwise be blocked from web server access, such as the `vendor` folder.
|
||||
Before requiring static asset files in PHP code or in a template, those assets need to be "exposed". This process allows Silverstripe CMS projects and Silverstripe CMS modules to make static asset files available via the web server from locations that would otherwise be blocked from web server access, such as the `vendor` folder.
|
||||
|
||||
### Configuring your project "exposed" folders
|
||||
|
||||
Exposed assets are made available in your web root in a dedicated "resources" directory. Prior to SilverStripe 4.4, the name of this directory was hardcoded to `resources`. In SilverStripe 4.4 and above, the name of the resources directory can be configured by defining the `extra.resources-dir` key in your `composer.json`. SilverStripe projects created from `silverstripe/installer` 4.4 and above will automatically be configured to use `_resources` as their resource directory.
|
||||
Exposed assets are made available in your web root in a dedicated "resources" directory. Prior to Silverstripe CMS 4.4, the name of this directory was hardcoded to `resources`. In Silverstripe CMS 4.4 and above, the name of the resources directory can be configured by defining the `extra.resources-dir` key in your `composer.json`. Silverstripe CMS projects created from `silverstripe/installer` 4.4 and above will automatically be configured to use `_resources` as their resource directory.
|
||||
|
||||
Each folder that needs to be exposed must be entered under the `extra.expose` key in your `composer.json` file. Module developers should use a path relative to the root of their module (don't include the "vendor/package-developer/package-name" path).
|
||||
|
||||
This is a sample SilverStripe project `composer.json` file configured to expose some assets.
|
||||
This is a sample Silverstripe CMS project `composer.json` file configured to expose some assets.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -45,11 +45,11 @@ This is a sample SilverStripe project `composer.json` file configured to expose
|
||||
|
||||
Files contained inside the `app/client/dist` and `app/images` will be made publicly available under the `_resources` directory.
|
||||
|
||||
SilverStripe projects should not track the "resources" directory in their source control system.
|
||||
Silverstripe CMS projects should not track the "resources" directory in their source control system.
|
||||
|
||||
### Exposing assets in the web root {#exposing-assets-webroot}
|
||||
|
||||
SilverStripe projects ship with [silverstripe/vendor-plugin](https://github.com/silverstripe/vendor-plugin).
|
||||
Silverstripe CMS projects ship with [silverstripe/vendor-plugin](https://github.com/silverstripe/vendor-plugin).
|
||||
This Composer plugin automatically tries to expose assets from your project and installed modules after installation, or after an update.
|
||||
|
||||
Developers can explicitly expose static assets by calling `composer vendor-expose`. This is necessary after updating your `resources-dir` or `expose` configuration in your `composer.json` file.
|
||||
@ -421,14 +421,14 @@ careful when messing with the order of requirements.
|
||||
|
||||
## Javascript placement
|
||||
|
||||
By default, SilverStripe includes all Javascript files at the bottom of the page body, unless there's another script
|
||||
By default, Silverstripe CMS includes all Javascript files at the bottom of the page body, unless there's another script
|
||||
already loaded, then, it's inserted before the first `<script>` tag. If this causes problems, it can be configured.
|
||||
|
||||
```php
|
||||
Requirements::set_force_js_to_bottom(true);
|
||||
```
|
||||
|
||||
`Requirements.force_js_to_bottom`, will force SilverStripe to write the Javascript to the bottom of the page body, even
|
||||
`Requirements.force_js_to_bottom`, will force Silverstripe CMS to write the Javascript to the bottom of the page body, even
|
||||
if there is an earlier script tag.
|
||||
|
||||
If the Javascript files are preferred to be placed in the `<head>` tag rather than in the `<body>` tag,
|
||||
|
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Rendering data to a template
|
||||
summary: Call and render SilverStripe templates manually.
|
||||
summary: Call and render Silverstripe CMS templates manually.
|
||||
icon: code
|
||||
---
|
||||
|
||||
@ -50,7 +50,7 @@ return $this->customise([
|
||||
```
|
||||
|
||||
[info]
|
||||
Most classes in SilverStripe you want in your template extend `ViewableData` and allow you to call `renderWith`. This
|
||||
Most classes in Silverstripe CMS you want in your template extend `ViewableData` and allow you to call `renderWith`. This
|
||||
includes [Controller](api:SilverStripe\Control\Controller), [FormField](api:SilverStripe\Forms\FormField) and [DataObject](api:SilverStripe\ORM\DataObject) instances.
|
||||
[/info]
|
||||
|
||||
|
@ -8,7 +8,7 @@ icon: sitemap
|
||||
|
||||
## Theme types
|
||||
|
||||
Templates in SilverStripe are bundled into one of two groups:
|
||||
Templates in Silverstripe CMS are bundled into one of two groups:
|
||||
- Default Templates, such as those provided in `mymodule/templates` folder.
|
||||
- Theme templates, such as those provided in `themes/mytheme/templates` folders.
|
||||
|
||||
@ -32,10 +32,10 @@ by the full path (from the `templates` folder onwards).
|
||||
|
||||
### Nested Layouts through `$Layout` type
|
||||
|
||||
SilverStripe has basic support for nested layouts through a fixed template variable named `$Layout`. It's used for
|
||||
Silverstripe CMS has basic support for nested layouts through a fixed template variable named `$Layout`. It's used for
|
||||
storing top level template information separate to individual page layouts.
|
||||
|
||||
When `$Layout` is found within a root template file (one in `templates`), SilverStripe will attempt to fetch a child
|
||||
When `$Layout` is found within a root template file (one in `templates`), Silverstripe CMS will attempt to fetch a child
|
||||
template from the `templates/<namespace>/Layout/<class>.ss` path, where `<namespace>` and `<class>` represent
|
||||
the class being rendered. It will do a full sweep of your modules, core and custom code as it
|
||||
would if it was looking for a new root template, as well as looking down the class hierarchy until
|
||||
|
@ -1,12 +1,12 @@
|
||||
---
|
||||
title: Themes
|
||||
summary: What makes up a SilverStripe Theme. How to install one or write your own theme.
|
||||
summary: What makes up a Silverstripe CMS Theme. How to install one or write your own theme.
|
||||
icon: paint-brush
|
||||
---
|
||||
|
||||
# Themes
|
||||
|
||||
Themes can be used to kick start your SilverStripe projects, can be stored outside of your application code and your
|
||||
Themes can be used to kick start your Silverstripe CMS projects, can be stored outside of your application code and your
|
||||
application can provide multiple unique themes (i.e a mobile theme).
|
||||
|
||||
## Downloading
|
||||
@ -26,13 +26,13 @@ composer require my_vendor/my_theme [version]
|
||||
*Note:* `[version]` should be replaced with a version constraint if you know it, otherwise leave it blank to pull the latest version compatible with your project.
|
||||
|
||||
[alert]
|
||||
As you've added new files to your SilverStripe installation, make sure you clear the SilverStripe cache by appending
|
||||
As you've added new files to your Silverstripe CMS installation, make sure you clear the Silverstripe CMS cache by appending
|
||||
`?flush=1` to your website URL (e.g http://yoursite.com/?flush=1).
|
||||
[/alert]
|
||||
|
||||
### Configuring themes
|
||||
|
||||
After installing the files through either method, update the current theme in SilverStripe. This can be done by
|
||||
After installing the files through either method, update the current theme in Silverstripe CMS. This can be done by
|
||||
altering the `SSViewer.themes` setting in a [config.yml](../configuration)
|
||||
|
||||
**app/_config/app.yml**
|
||||
@ -71,17 +71,17 @@ main styles of syntax:
|
||||
|
||||
## Developing your own theme
|
||||
|
||||
A `theme` within SilverStripe is simply a collection of templates and other front end assets such as javascript and CSS located within the `themes` directory.
|
||||
A `theme` within Silverstripe CMS is simply a collection of templates and other front end assets such as javascript and CSS located within the `themes` directory.
|
||||
|
||||
![themes:basicfiles.gif](../../_images/basicfiles.gif)
|
||||
|
||||
SilverStripe 4 has support for cascading themes, which will allow users to define multiple themes for a project. This means you can have a template defined in any theme, and have it continue to look back through the list of themes until a match is found.
|
||||
Silverstripe CMS 4 has support for cascading themes, which will allow users to define multiple themes for a project. This means you can have a template defined in any theme, and have it continue to look back through the list of themes until a match is found.
|
||||
|
||||
To define extra themes simply add extra entries to the `SilverStripe\View\SSViewer.themes` configuration array. You will probably always want to ensure that you include `'$default'` in your list of themes to ensure that the base templates are used when required.
|
||||
|
||||
## Submitting your theme to addons
|
||||
|
||||
If you want to submit your theme to the SilverStripe addons directory then check:
|
||||
If you want to submit your theme to the Silverstripe CMS addons directory then check:
|
||||
|
||||
* You should ensure your templates are well structured, modular and commented so it's easy for other people to customise
|
||||
* Templates should not contain text inside images and all images provided must be open source and not break any
|
||||
|
@ -6,7 +6,7 @@ icon: globe
|
||||
|
||||
# Translations
|
||||
|
||||
Translations are easy to use with a template, and give access to SilverStripe's translation facilities. Here is an
|
||||
Translations are easy to use with a template, and give access to Silverstripe CMS's translation facilities. Here is an
|
||||
example:
|
||||
|
||||
```ss
|
||||
|
@ -73,7 +73,7 @@ $Me
|
||||
|
||||
Methods which return data to the template should either return an explicit object instance describing the type of
|
||||
content that method sends back, or provide a type in the `$casting` array for the object. When rendering that method
|
||||
to a template, SilverStripe will ensure that the object is wrapped in the correct type and values are safely escaped.
|
||||
to a template, Silverstripe CMS will ensure that the object is wrapped in the correct type and values are safely escaped.
|
||||
|
||||
```php
|
||||
use SilverStripe\CMS\Model\SiteTree;
|
||||
@ -92,7 +92,7 @@ class Page extends SiteTree
|
||||
}
|
||||
```
|
||||
|
||||
When calling `$MyCustomMethod` SilverStripe now has the context that this method will contain HTML and escape the data
|
||||
When calling `$MyCustomMethod` Silverstripe CMS now has the context that this method will contain HTML and escape the data
|
||||
accordingly.
|
||||
|
||||
[note]
|
||||
|
@ -1,14 +1,14 @@
|
||||
---
|
||||
title: Templates and Views
|
||||
summary: This guide showcases the SilverStripe template engine and learn how to build your own themes.
|
||||
introduction: SilverStripe comes with it's own templating engine. This guide walks you through the features of the template engine, how to create custom templates and ways to customise your data output.
|
||||
summary: This guide showcases the Silverstripe CMS template engine and learn how to build your own themes.
|
||||
introduction: Silverstripe CMS comes with it's own templating engine. This guide walks you through the features of the template engine, how to create custom templates and ways to customise your data output.
|
||||
icon: file-code
|
||||
---
|
||||
|
||||
Most of what will be public on your website comes from template files that are defined in SilverStripe. Either in the
|
||||
Most of what will be public on your website comes from template files that are defined in Silverstripe CMS. Either in the
|
||||
core framework, the modules or themes you install, and your own custom templates.
|
||||
|
||||
SilverStripe templates are simple text files that have an `.ss` extension. They can contain any markup language (e.g HTML,
|
||||
Silverstripe CMS templates are simple text files that have an `.ss` extension. They can contain any markup language (e.g HTML,
|
||||
XML, JSON..) and are processed to add features such as `$Var` to output variables and logic controls like
|
||||
`<% if $Var %>`. In this guide we'll look at the syntax of the custom template engine [SSViewer](api:SilverStripe\View\SSViewer) and how to render
|
||||
templates from your controllers.
|
||||
|
@ -5,7 +5,7 @@ summary: A brief look at the definition of a Controller, creating actions and ho
|
||||
|
||||
# Introduction to Controllers
|
||||
|
||||
The following example is for a simple [Controller](api:SilverStripe\Control\Controller) class. When building off the SilverStripe Framework you will
|
||||
The following example is for a simple [Controller](api:SilverStripe\Control\Controller) class. When building off the Silverstripe CMS you will
|
||||
subclass the base `Controller` class.
|
||||
|
||||
**app/code/controllers/TeamController.php**
|
||||
@ -46,7 +46,7 @@ routing.
|
||||
[/info]
|
||||
|
||||
[alert]
|
||||
Make sure that after you have modified the `routes.yml` file, that you clear your SilverStripe caches using `?flush=1`.
|
||||
Make sure that after you have modified the `routes.yml` file, that you clear your Silverstripe CMS caches using `?flush=1`.
|
||||
[/alert]
|
||||
|
||||
**app/_config/routes.yml**
|
||||
@ -69,13 +69,13 @@ Controllers respond by default to an `index` method. You don't need to define th
|
||||
can override the `index()` response to provide custom data back to the [Template and Views](../templates).
|
||||
|
||||
[notice]
|
||||
It is standard in SilverStripe for your controller actions to be `lowercasewithnospaces`
|
||||
It is standard in Silverstripe CMS for your controller actions to be `lowercasewithnospaces`
|
||||
[/notice]
|
||||
|
||||
Action methods can return one of four main things:
|
||||
|
||||
* an array. In this case the values in the array are available in the templates and the controller completes as usual by returning a [HTTPResponse](api:SilverStripe\Control\HTTPResponse) with the body set to the current template.
|
||||
* `HTML`. SilverStripe will wrap the `HTML` into a `HTTPResponse` and set the status code to 200.
|
||||
* `HTML`. Silverstripe CMS will wrap the `HTML` into a `HTTPResponse` and set the status code to 200.
|
||||
* an [HTTPResponse](api:SilverStripe\Control\HTTPResponse) containing a manually defined `status code` and `body`.
|
||||
* an [HTTPResponse_Exception](api:SilverStripe\Control\HTTPResponse_Exception). A special type of response which indicates an error. By returning the exception, the execution pipeline can adapt and display any error handlers.
|
||||
|
||||
@ -116,7 +116,7 @@ public function anotheraction(HTTPRequest $request)
|
||||
}
|
||||
|
||||
/**
|
||||
* We can render HTML and leave SilverStripe to set the response code and body.
|
||||
* We can render HTML and leave Silverstripe CMS to set the response code and body.
|
||||
*/
|
||||
public function htmlaction()
|
||||
{
|
||||
@ -151,7 +151,7 @@ See the [Access Controller](access_control) documentation.
|
||||
Controllers are automatically rendered with a template that makes their name. Our `TeamsController` would be rendered
|
||||
with a `TeamsController.ss` template. Individual actions are rendered in `TeamsController_{actionname}.ss`.
|
||||
|
||||
If a template of that name does not exist, then SilverStripe will fall back to the `TeamsController.ss` then to
|
||||
If a template of that name does not exist, then Silverstripe CMS will fall back to the `TeamsController.ss` then to
|
||||
`Controller.ss`.
|
||||
|
||||
Controller actions can use `renderWith` to override this template selection process as in the previous example with
|
||||
@ -163,7 +163,7 @@ For more information about templates, inheritance and how to render into views,
|
||||
## Link
|
||||
|
||||
Each controller should define a `Link()` method. This should be used to avoid hard coding your routing in views,
|
||||
as well as give other features in SilverStripe the ability to influence link behaviour.
|
||||
as well as give other features in Silverstripe CMS the ability to influence link behaviour.
|
||||
|
||||
**app/code/controllers/TeamController.php**
|
||||
|
||||
|
@ -144,7 +144,7 @@ start parsing variables and the appropriate controller action AFTER the `//`).
|
||||
|
||||
### Wildcard URL Patterns
|
||||
|
||||
As of SilverStripe 4.6 there are two wildcard patterns that can be used. `$@` and `$*`. These parameters can only be used
|
||||
As of Silverstripe CMS 4.6 there are two wildcard patterns that can be used. `$@` and `$*`. These parameters can only be used
|
||||
at the end of a URL pattern, any further rules are ignored.
|
||||
|
||||
Inspired by bash variadic variable syntax there are two ways to capture all URL parameters without having to explicitly
|
||||
@ -282,7 +282,7 @@ class BreadAPIController extends Controller
|
||||
```
|
||||
|
||||
<div class="alert" markdown="1">
|
||||
In SilverStripe Framework versions prior to 4.6, an empty key (`''`) must be used in place of the `'/'` key. When specifying an HTTP method, the empty string must be separated from the method (e.g. `'GET '`). The empty key and slash key are also equivalent in Director rules.
|
||||
In Silverstripe CMS versions prior to 4.6, an empty key (`''`) must be used in place of the `'/'` key. When specifying an HTTP method, the empty string must be separated from the method (e.g. `'GET '`). The empty key and slash key are also equivalent in Director rules.
|
||||
</div>
|
||||
|
||||
## Related Lessons
|
||||
|
@ -43,7 +43,7 @@ class MyController extends Controller
|
||||
```
|
||||
|
||||
[info]
|
||||
If the permission check fails, SilverStripe will return a `403` Forbidden HTTP status.
|
||||
If the permission check fails, Silverstripe CMS will return a `403` Forbidden HTTP status.
|
||||
[/info]
|
||||
|
||||
An action named "index" is white listed by default, unless `allowed_actions` is defined as an empty array, or the action
|
||||
|
@ -9,7 +9,7 @@ HTTP Middlewares allow you to add code that will run before or after a request h
|
||||
authentication, logging, caching, request processing, and many other purposes.
|
||||
|
||||
[notice]
|
||||
Note this interface replaces the SilverStripe 3 interface [RequestFilter](api:SilverStripe\Control\RequestFilter), which still works but is deprecated.
|
||||
Note this interface replaces the Silverstripe CMS 3 interface [RequestFilter](api:SilverStripe\Control\RequestFilter), which still works but is deprecated.
|
||||
[/notice]
|
||||
|
||||
To create a middleware class, implement `SilverStripe\Control\Middleware\HTTPMiddleware` and define the
|
||||
|
@ -1,11 +1,11 @@
|
||||
---
|
||||
title: Built-in Middleware
|
||||
summary: Middleware components that come with SilverStripe Framework
|
||||
summary: Middleware components that come with Silverstripe CMS
|
||||
---
|
||||
|
||||
# Built-in Middleware
|
||||
|
||||
SilverStripe Framework has a number of Middleware components.
|
||||
Silverstripe CMS has a number of Middleware components.
|
||||
You may find them in the [SilverStripe\Control\Middleware](api:SilverStripe\Control\Middleware) namespace.
|
||||
|
||||
| Name | Description |
|
||||
|
@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Controllers
|
||||
summary: Controllers form the backbone of your SilverStripe application. They handle routing URLs to your templates.
|
||||
introduction: In this guide you will learn how to define a Controller class and how they fit into the SilverStripe response and request cycle.
|
||||
summary: Controllers form the backbone of your Silverstripe CMS application. They handle routing URLs to your templates.
|
||||
introduction: In this guide you will learn how to define a Controller class and how they fit into the Silverstripe CMS response and request cycle.
|
||||
---
|
||||
|
||||
The [Controller](api:SilverStripe\Control\Controller) class handles the responsibility of delivering the correct outgoing [HTTPResponse](api:SilverStripe\Control\HTTPResponse) for a
|
||||
|
@ -6,7 +6,7 @@ iconBrand: wpforms
|
||||
|
||||
# Forms
|
||||
|
||||
The HTML `Form` is the most used way to interact with a user. SilverStripe provides classes to generate forms through
|
||||
The HTML `Form` is the most used way to interact with a user. Silverstripe CMS provides classes to generate forms through
|
||||
the [Form](api:SilverStripe\Forms\Form) class, [FormField](api:SilverStripe\Forms\FormField) instances to capture data and submissions through [FormAction](api:SilverStripe\Forms\FormAction).
|
||||
|
||||
[notice]
|
||||
@ -33,7 +33,7 @@ $form = new Form(
|
||||
|
||||
In practice, this looks like:
|
||||
|
||||
**app/code/PageController.php**
|
||||
**app/src/PageController.php**
|
||||
|
||||
```php
|
||||
use SilverStripe\CMS\Controllers\ContentController;
|
||||
@ -89,7 +89,7 @@ variable.
|
||||
[/info]
|
||||
|
||||
When constructing the `Form` instance (`new Form($controller, $name)`) both controller and name are required. The
|
||||
`$controller` and `$name` are used to allow SilverStripe to calculate the origin of the `Form object`. When a user
|
||||
`$controller` and `$name` are used to allow Silverstripe CMS to calculate the origin of the `Form object`. When a user
|
||||
submits the `HelloForm` from your `contact-us` page the form submission will go to `contact-us/HelloForm` before any of
|
||||
the [FormAction](api:SilverStripe\Forms\FormAction). The URL is known as the `$controller` instance will know the 'contact-us' link and we provide
|
||||
`HelloForm` as the `$name` of the form. `$name` **needs** to match the method name.
|
||||
|
@ -6,7 +6,7 @@ icon: check-square
|
||||
|
||||
# Form Validation
|
||||
|
||||
SilverStripe provides server-side form validation out of the box through the [Validator](api:SilverStripe\Forms\Validator) class and its' child class
|
||||
Silverstripe CMS provides server-side form validation out of the box through the [Validator](api:SilverStripe\Forms\Validator) class and its' child class
|
||||
[RequiredFields](api:SilverStripe\Forms\RequiredFields). A single `Validator` instance is set on each `Form`. Validators are implemented as an argument to
|
||||
the [Form](api:SilverStripe\Forms\Form) constructor or through the function `setValidator`.
|
||||
|
||||
@ -82,7 +82,7 @@ public function validate($validator)
|
||||
}
|
||||
```
|
||||
|
||||
The `validate` method should return `true` if the value passes any validation and `false` if SilverStripe should trigger
|
||||
The `validate` method should return `true` if the value passes any validation and `false` if Silverstripe CMS should trigger
|
||||
a validation error on the page. In addition a useful error message must be set on the given validator.
|
||||
|
||||
[notice]
|
||||
@ -218,7 +218,7 @@ $field->setCustomValidationMessage('Whoops, looks like you have missed me!');
|
||||
|
||||
## JavaScript validation
|
||||
|
||||
Although there are no built-in JavaScript validation handlers in SilverStripe, the `FormField` API is flexible enough
|
||||
Although there are no built-in JavaScript validation handlers in Silverstripe CMS, the `FormField` API is flexible enough
|
||||
to provide the information required in order to plug in custom libraries like [Parsley.js](http://parsleyjs.org/) or
|
||||
[jQuery.Validate](http://jqueryvalidation.org/). Most of these libraries work on HTML `data-` attributes or special
|
||||
classes added to each input. For Parsley we can structure the form like.
|
||||
@ -235,7 +235,7 @@ $field->setAttribute('data-parsley-mincheck', '2');
|
||||
|
||||
## Model Validation
|
||||
|
||||
An alternative (or additional) approach to validation is to place it directly on the database model. SilverStripe
|
||||
An alternative (or additional) approach to validation is to place it directly on the database model. Silverstripe CMS
|
||||
provides a [DataObject::validate()](api:SilverStripe\ORM\DataObject::validate()) method to validate data at the model level. See
|
||||
[Data Model Validation](../model/validation).
|
||||
|
||||
|
@ -6,7 +6,7 @@ icon: file-code
|
||||
|
||||
# Form Templates
|
||||
|
||||
Most markup generated in SilverStripe can be replaced by custom templates. Both [Form](api:SilverStripe\Forms\Form) and [FormField](api:SilverStripe\Forms\FormField) instances
|
||||
Most markup generated in Silverstripe CMS can be replaced by custom templates. Both [Form](api:SilverStripe\Forms\Form) and [FormField](api:SilverStripe\Forms\FormField) instances
|
||||
can be rendered out using custom templates using `setTemplate`.
|
||||
|
||||
|
||||
@ -29,7 +29,7 @@ modify as you need.
|
||||
*The default Form.ss can be found in `/vendor/silverstripe/framework/templates/SilverStripe/Forms/Includes/`*
|
||||
[/notice]
|
||||
|
||||
By default, Form and Fields follow the SilverStripe Template convention and are rendered into templates of the same
|
||||
By default, Form and Fields follow the Silverstripe CMS Template convention and are rendered into templates of the same
|
||||
class name (i.e EmailField will attempt to render into `EmailField.ss` and if that isn't found, `TextField.ss` or
|
||||
finally `FormField.ss`).
|
||||
|
||||
|
@ -11,7 +11,7 @@ should be done as safely as possible. Below outlines the things to consider when
|
||||
|
||||
## Cross-Site Request Forgery (CSRF)
|
||||
|
||||
SilverStripe protect users against [Cross-Site Request Forgery](https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)
|
||||
Silverstripe CMS protect users against [Cross-Site Request Forgery](https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)
|
||||
(known as `CSRF`) by adding a SecurityID [HiddenField](api:SilverStripe\Forms\HiddenField) to each [Form](api:SilverStripe\Forms\Form) instance. The `SecurityID` contains a
|
||||
random string generated by [SecurityToken](api:SilverStripe\Security\SecurityToken) to identify the particular user request vs a third-party forging fake
|
||||
requests.
|
||||
@ -74,7 +74,7 @@ $form->setFormMethod('POST', false);
|
||||
|
||||
## Spam and Bot Attacks
|
||||
|
||||
SilverStripe has no built-in protection for detailing with bots, captcha or other spam protection methods. This
|
||||
Silverstripe CMS has no built-in protection for detailing with bots, captcha or other spam protection methods. This
|
||||
functionality is available as an additional [Spam Protection](https://github.com/silverstripe/silverstripe-spamprotection)
|
||||
module if required. The module provides an consistent API for allowing third-party spam protection handlers such as
|
||||
[Recaptcha](http://www.google.com/recaptcha/intro/) and [Mollom](https://mollom.com/) to work within the `Form` API.
|
||||
@ -88,7 +88,7 @@ This data can inadvertently be stored either in a user's browser cache or in an
|
||||
cache such as a CDN or other caching-proxy. If incorrect `Cache-Control` headers are used, private data may be cached and
|
||||
accessible publicly through the CDN.
|
||||
|
||||
To ensure this doesn't happen SilverStripe adds `Cache-Control: no-store, no-cache, must-revalidate` headers to any
|
||||
To ensure this doesn't happen Silverstripe CMS adds `Cache-Control: no-store, no-cache, must-revalidate` headers to any
|
||||
forms that have validators or security tokens (all of them by default) applied to them; this ensures that CDNs
|
||||
(and browsers) will not cache these pages.
|
||||
See [/developer_guides/performance/http_cache_headers](Performance: HTTP Cache Headers).
|
||||
|
@ -5,7 +5,7 @@ summary: Find out how CMS interfaces use jQuery UI tabs to provide nested FormFi
|
||||
|
||||
# Tabbed Forms
|
||||
|
||||
SilverStripe's [FormScaffolder](api:SilverStripe\Forms\FormScaffolder) can automatically generate [Form](api:SilverStripe\Forms\Form) instances for certain database models. In the
|
||||
Silverstripe CMS's [FormScaffolder](api:SilverStripe\Forms\FormScaffolder) can automatically generate [Form](api:SilverStripe\Forms\Form) instances for certain database models. In the
|
||||
CMS and other scaffolded interfaces, it will output [TabSet](api:SilverStripe\Forms\TabSet) and [Tab](api:SilverStripe\Forms\Tab) objects and use jQuery Tabs to split
|
||||
parts of the data model.
|
||||
|
||||
|
@ -6,7 +6,7 @@ summary: A table containing a list of the common FormField subclasses.
|
||||
# Common FormField type subclasses
|
||||
|
||||
This is a high level overview of available [FormField](api:SilverStripe\Forms\FormField) subclasses. An automatically generated list is available
|
||||
on the SilverStripe API documentation.
|
||||
on the Silverstripe CMS API documentation.
|
||||
|
||||
## Basic
|
||||
|
||||
|
@ -6,7 +6,7 @@ icon: file-code
|
||||
|
||||
# Rich-text editing (WYSIWYG)
|
||||
|
||||
Editing and formatting content is the bread and butter of every content management system, which is why SilverStripe
|
||||
Editing and formatting content is the bread and butter of every content management system, which is why Silverstripe CMS
|
||||
has a tight integration with our preferred editor library, [TinyMCE](http://tinymce.com).
|
||||
|
||||
On top of the base functionality, we use our own insertion dialogs to ensure you can effectively select and upload
|
||||
@ -194,7 +194,7 @@ We use [shortcodes](/developer_guides/extending/shortcodes) to store information
|
||||
takes care of care of placing the shortcode replacements relative to its surrounding markup (e.g. left/right alignment).
|
||||
|
||||
### Image size pre-sets
|
||||
SilverStripe will suggest pre-set image size in the HTMLEditor. Editors can quickly switch between the pre-set size when interacting with images in the HTMLEditorField.
|
||||
Silverstripe CMS will suggest pre-set image size in the HTMLEditor. Editors can quickly switch between the pre-set size when interacting with images in the HTMLEditorField.
|
||||
|
||||
The default values are "Best fit" (600 pixels width) and original size. Developers can customise the pre-set sizes by altering their HTMLEditorConfig.
|
||||
|
||||
@ -314,7 +314,7 @@ In case you want to adhere to HTML4 instead, use the following configuration:
|
||||
HtmlEditorConfig::get('cms')->setOption('element_format', 'html');
|
||||
```
|
||||
|
||||
By default, TinyMCE and SilverStripe will generate valid HTML5 markup, but it will strip out HTML5 tags like
|
||||
By default, TinyMCE and Silverstripe CMS will generate valid HTML5 markup, but it will strip out HTML5 tags like
|
||||
`<article>` or `<figure>`. If you plan to use those, add them to the
|
||||
[valid_elements](http://www.tinymce.com/wiki.php/Configuration:valid_elements) configuration setting.
|
||||
|
||||
@ -329,7 +329,7 @@ to successfully process HTML5 tags, please use the
|
||||
|
||||
In the standard installation, you can insert links (internal/external/anchor/email),
|
||||
images as well as flash media files. The forms used for preparing the new content element
|
||||
are rendered by SilverStripe, but there's some JavaScript involved to transfer
|
||||
are rendered by Silverstripe CMS, but there's some JavaScript involved to transfer
|
||||
back and forth between a content representation the editor can understand, present and save.
|
||||
|
||||
Example: Remove field for "image captions"
|
||||
|
@ -6,7 +6,7 @@ icon: table
|
||||
|
||||
# GridField
|
||||
|
||||
[GridField](api:SilverStripe\Forms\GridField\GridField) is SilverStripe's implementation of data grids. The main purpose of the `FormField` is to display
|
||||
[GridField](api:SilverStripe\Forms\GridField\GridField) is Silverstripe CMS's implementation of data grids. The main purpose of the `FormField` is to display
|
||||
tabular data in a format that is easy to view and modify. It can be thought of as a HTML table with some tricks.
|
||||
|
||||
|
||||
|
@ -13,7 +13,6 @@ code for a `Form` is to create it as a subclass to `Form`. Let's look at a examp
|
||||
|
||||
**app/code/Page.php**
|
||||
|
||||
|
||||
```php
|
||||
use SilverStripe\Forms\FieldList;
|
||||
use SilverStripe\Forms\RequiredFields;
|
||||
|
@ -6,7 +6,7 @@ iconBrand: wpforms
|
||||
|
||||
# How to Create Lightweight Form
|
||||
|
||||
Out of the box, SilverStripe provides a robust and reusable set of HTML markup for [FormField](api:SilverStripe\Forms\FormField), however this can
|
||||
Out of the box, Silverstripe CMS provides a robust and reusable set of HTML markup for [FormField](api:SilverStripe\Forms\FormField), however this can
|
||||
sometimes produce markup which is unnecessarily bloated.
|
||||
|
||||
For example, a basic search form. We want to use the [Form](api:SilverStripe\Forms\Form) API to handle the form but we may want to provide a
|
||||
|
@ -134,7 +134,7 @@ First thing to note is that our new class implements two interfaces,
|
||||
Each interface allows our class to define particular behaviors and is a core
|
||||
concept of the modular `GridFieldConfig` system.
|
||||
|
||||
The `GridField_ColumnProvider` implementation tells SilverStripe that this class
|
||||
The `GridField_ColumnProvider` implementation tells Silverstripe CMS that this class
|
||||
will provide the `GridField` with an additional column of information. By
|
||||
implementing this interface we're required to define several methods to explain
|
||||
where we want the column to exist and how we need it to be formatted. This is
|
||||
|
@ -1,12 +1,12 @@
|
||||
---
|
||||
title: Forms
|
||||
summary: Capture user information through Forms. This guide will work through how to create SilverStripe forms, adding and modifying fields and how to handle form submissions.
|
||||
introduction: This guide will work through how to create SilverStripe forms, adding and modifying fields and how to handle form submissions.
|
||||
summary: Capture user information through Forms. This guide will work through how to create Silverstripe CMS forms, adding and modifying fields and how to handle form submissions.
|
||||
introduction: This guide will work through how to create Silverstripe CMS forms, adding and modifying fields and how to handle form submissions.
|
||||
iconBrand: wpforms
|
||||
---
|
||||
|
||||
The [Form](api:SilverStripe\Forms\Form) class provides a way to create interactive forms in your web application with very little effort.
|
||||
SilverStripe handles generating the correct semantic HTML markup for the form and each of the fields, as well as the
|
||||
Silverstripe CMS handles generating the correct semantic HTML markup for the form and each of the fields, as well as the
|
||||
framework for dealing with submissions and validation.
|
||||
|
||||
[CHILDREN Exclude="How_Tos,Fields"]
|
||||
|
@ -6,12 +6,12 @@ icon: laptop-code
|
||||
|
||||
# Configuration API
|
||||
|
||||
SilverStripe comes with a comprehensive code based configuration system through the [Config](api:SilverStripe\Core\Config\Config) class. It primarily
|
||||
Silverstripe CMS comes with a comprehensive code based configuration system through the [Config](api:SilverStripe\Core\Config\Config) class. It primarily
|
||||
relies on declarative [YAML](http://en.wikipedia.org/wiki/YAML) files, and falls back to procedural PHP code, as well
|
||||
as PHP static variables. This is provided by the [silverstripe/config](https://github.com/silverstripe/silverstripe-config)
|
||||
library.
|
||||
|
||||
The Configuration API can be seen as separate from other forms of variables in the SilverStripe system due to three
|
||||
The Configuration API can be seen as separate from other forms of variables in the Silverstripe CMS system due to three
|
||||
properties API:
|
||||
|
||||
- Configuration is **per class**, not per instance.
|
||||
@ -24,7 +24,7 @@ For providing content editors or CMS users a place to manage configuration see t
|
||||
|
||||
## Configuration Properties
|
||||
|
||||
Configuration values are static properties on any SilverStripe class. These should be at the top of the class and
|
||||
Configuration values are static properties on any Silverstripe CMS class. These should be at the top of the class and
|
||||
marked with a `@config` docblock. The API documentation will also list the static properties for the class. They should
|
||||
be marked `private static` and follow the `lower_case_with_underscores` structure.
|
||||
|
||||
@ -322,7 +322,7 @@ before A. In this case you will get an error when accessing your site.
|
||||
## Exclusionary rules
|
||||
|
||||
Some value sections might only make sense under certain environmental conditions - a class exists, a module is
|
||||
installed, an environment variable or constant is set, or SilverStripe is running in a certain environment mode (live,
|
||||
installed, an environment variable or constant is set, or Silverstripe CMS is running in a certain environment mode (live,
|
||||
dev, etc).
|
||||
|
||||
To accommodate this, value sections can be filtered to only be used when either a rule matches or doesn't match the
|
||||
@ -337,7 +337,7 @@ You then list any of the following rules as sub-keys, with informational values
|
||||
- 'classexists', in which case the value(s) should be classes that must exist
|
||||
- 'moduleexists', in which case the value(s) should be modules that must exist. This supports either folder
|
||||
name or composer `vendor/name` format.
|
||||
- 'environment', in which case the value(s) should be one of "live", "test" or "dev" to indicate the SilverStripe
|
||||
- 'environment', in which case the value(s) should be one of "live", "test" or "dev" to indicate the Silverstripe CMS
|
||||
mode the site must be in
|
||||
- 'envvarset', in which case the value(s) should be environment variables that must be set
|
||||
- 'constantdefined', in which case the value(s) should be constants that must be defined
|
||||
|
@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Configuration
|
||||
summary: SilverStripe provides several ways to store and modify your application settings. Learn about site wide settings and the YAML based configuration system.
|
||||
introduction: SilverStripe provides several ways to store and modify your application settings. Learn about site wide settings and the YAML based configuration system.
|
||||
summary: Silverstripe CMS provides several ways to store and modify your application settings. Learn about site wide settings and the YAML based configuration system.
|
||||
introduction: Silverstripe CMS provides several ways to store and modify your application settings. Learn about site wide settings and the YAML based configuration system.
|
||||
icon: laptop-code
|
||||
---
|
||||
|
||||
|
@ -6,7 +6,7 @@ icon: code
|
||||
|
||||
# Modules
|
||||
|
||||
SilverStripe is designed to be a modular application system - even the CMS is simply a module that plugs into the core
|
||||
Silverstripe CMS is designed to be a modular application system - even the CMS is simply a module that plugs into the core
|
||||
framework.
|
||||
|
||||
A module is a collection of classes, templates, and other resources that is loaded into a directory.
|
||||
@ -30,7 +30,7 @@ vendor/my_vendor/my_module/
|
||||
|
||||
Like with any Composer package, we recommend declaring your PHP classes through
|
||||
[PSR autoloading](https://getcomposer.org/doc/01-basic-usage.md#autoloading).
|
||||
SilverStripe will automatically discover templates and configuration settings
|
||||
Silverstripe CMS will automatically discover templates and configuration settings
|
||||
within your module when you next flush your cache.
|
||||
|
||||
|
||||
@ -44,7 +44,7 @@ within your module when you next flush your cache.
|
||||
|
||||
Modules are installed through the [Composer](http://getcomposer.org) package manager. It
|
||||
enables you to install modules from specific versions, checking for compatibilities between modules and even allowing
|
||||
to track development branches of them. To install modules using this method, you will first need to setup SilverStripe
|
||||
to track development branches of them. To install modules using this method, you will first need to setup Silverstripe CMS
|
||||
with [Composer](../../getting_started/composer).
|
||||
|
||||
Each module has a unique identifier, consisting of a vendor prefix and name. For example, the "blog" module has the
|
||||
@ -73,7 +73,7 @@ After you add or remove modules, make sure you rebuild the database, class and c
|
||||
## Creating a Module {#create}
|
||||
|
||||
Creating a module is a good way to re-use code and templates across multiple projects,
|
||||
or share your code with the community. SilverStripe already
|
||||
or share your code with the community. Silverstripe CMS already
|
||||
has certain modules included, for example the `cms` module and core functionality such as commenting and spam protection
|
||||
are also abstracted into modules allowing developers the freedom to choose what they want.
|
||||
|
||||
@ -83,10 +83,10 @@ read more about [publishing a module](how_tos/publish_a_module).
|
||||
|
||||
## Module Standard
|
||||
|
||||
The SilverStripe module standard defines a set of conventions that high-quality SilverStripe modules should follow. It’s a bit like PSR for SilverStripe CMS. Suggested improvements can be raised as pull requests.
|
||||
The Silverstripe CMS module standard defines a set of conventions that high-quality Silverstripe CMS modules should follow. It’s a bit like PSR for Silverstripe CMS. Suggested improvements can be raised as pull requests.
|
||||
This standard is also part of the more highlevel
|
||||
[Supported Modules Definition](https://www.silverstripe.org/software/addons/supported-modules-definition/)
|
||||
which the SilverStripe project applies to the modules it creates and maintains directly.
|
||||
which the Silverstripe CMS project applies to the modules it creates and maintains directly.
|
||||
|
||||
### Coding Guidelines
|
||||
|
||||
@ -119,7 +119,7 @@ Documentation will use the following format:
|
||||
* Security, license, links to more detailed docs.
|
||||
* CONTRIBUTING.md explaining terms of contribution.
|
||||
* A changelog: CHANGELOG.md (may link to other more detailed docs or GitHub releases if you want). You could [use a changelog generator](https://github.com/skywinder/Github-Changelog-Generator) to help create this.
|
||||
* Has a licence (`LICENSE` file) - for SilverStripe supported this needs to be BSD.
|
||||
* Has a licence (`LICENSE` file) - for Silverstripe CMS supported this needs to be BSD.
|
||||
* Detailed documentation in `/docs/en` as a nested set of GitHub-compatible Markdown files.
|
||||
* It is suggested to use a documentation page named `userguide.md` in `docs/en/` that includes documentation of module features that have CMS user functionality (if applicable). For modules with large userguides, this should be in a directory named `userguide` with an `index.md` linking to any other userguide pages.
|
||||
* Links and image references are relative, and are able to be followed in viewers such as GitHub.
|
||||
|
@ -43,7 +43,7 @@ class MyMemberExtension extends DataExtension
|
||||
Convention is for extension class names to end in `Extension`. This isn't a requirement but makes it clearer
|
||||
[/info]
|
||||
|
||||
After this class has been created, it does not yet apply it to any object. We need to tell SilverStripe what classes
|
||||
After this class has been created, it does not yet apply it to any object. We need to tell Silverstripe CMS what classes
|
||||
we want to add the `MyMemberExtension` too. To activate this extension, add the following via the [Configuration API](../configuration).
|
||||
|
||||
**app/_config/app.yml**
|
||||
|
@ -95,7 +95,7 @@ ShortcodeParser::get('default')->register('my_shortcode', ['Page', 'MyShortCodeM
|
||||
|
||||
## Built-in Shortcodes
|
||||
|
||||
SilverStripe comes with several shortcode parsers already.
|
||||
Silverstripe CMS comes with several shortcode parsers already.
|
||||
|
||||
### Links
|
||||
|
||||
|
@ -1,12 +1,12 @@
|
||||
---
|
||||
title: Injector
|
||||
summary: Introduction to using Dependency Injection within SilverStripe.
|
||||
summary: Introduction to using Dependency Injection within Silverstripe CMS.
|
||||
icon: code
|
||||
---
|
||||
|
||||
# Injector
|
||||
|
||||
The [Injector](api:SilverStripe\Core\Injector\Injector) class is the central manager of inter-class dependencies in SilverStripe. It offers developers the
|
||||
The [Injector](api:SilverStripe\Core\Injector\Injector) class is the central manager of inter-class dependencies in Silverstripe CMS. It offers developers the
|
||||
ability to declare the dependencies a class type has, or to change the nature of the dependencies defined by other
|
||||
developers.
|
||||
|
||||
|
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Aspects
|
||||
summary: Introduction to using aspect-oriented programming with SilverStripe.
|
||||
summary: Introduction to using aspect-oriented programming with Silverstripe CMS.
|
||||
icon: code
|
||||
---
|
||||
|
||||
@ -17,7 +17,7 @@ Aspect oriented programming is the idea that some logic abstractions can be appl
|
||||
[Wikipedia](http://en.wikipedia.org/wiki/Aspect-oriented_programming) provides a much more in-depth explanation.
|
||||
[/notice]
|
||||
|
||||
In the context of the SilverStripe [Dependency Injector](injector), Aspects are achieved thanks to PHP's `__call` magic
|
||||
In the context of the Silverstripe CMS [Dependency Injector](injector), Aspects are achieved thanks to PHP's `__call` magic
|
||||
method combined with the `Proxy` Design Pattern.
|
||||
|
||||
Assume an existing service declaration exists called `MyService`. An `AopProxyService` class instance is created, and
|
||||
@ -42,7 +42,7 @@ specific database server, whereas all read queries can be handled by slave serve
|
||||
A simplified implementation might look like the following.
|
||||
|
||||
[notice]
|
||||
This doesn't cover all cases used by SilverStripe so is not a complete solution, more just a guide to how it would be
|
||||
This doesn't cover all cases used by Silverstripe CMS so is not a complete solution, more just a guide to how it would be
|
||||
used.
|
||||
[/notice]
|
||||
|
||||
|
@ -1,10 +1,10 @@
|
||||
---
|
||||
title: How to Publish a SilverStripe module
|
||||
title: How to Publish a Silverstripe CMS module
|
||||
summary: Have you created some work you think others can use? Turn it into a module and share it.
|
||||
icon: rocket
|
||||
---
|
||||
|
||||
# How to Publish a SilverStripe module.
|
||||
# How to Publish a Silverstripe CMS module.
|
||||
|
||||
After you've [created](../modules#create) your own Silverstripe module,
|
||||
you could decide to make it open source and share it with the world.
|
||||
@ -12,7 +12,7 @@ you could decide to make it open source and share it with the world.
|
||||
If you wish to submit your module to our public directory, you take responsibility for a certain level of code quality,
|
||||
adherence to conventions, writing documentation, and releasing updates.
|
||||
|
||||
SilverStripe uses [Composer](../../../getting_started/composer/) to manage module releases and dependencies between
|
||||
Silverstripe CMS uses [Composer](../../../getting_started/composer/) to manage module releases and dependencies between
|
||||
modules. If you plan on releasing your module to the public, ensure that you provide a `composer.json` file in the root
|
||||
of your module containing the meta-data about your module.
|
||||
|
||||
@ -62,9 +62,9 @@ Once your module is published online with a service like github.com or bitbucket
|
||||
[Packagist](https://packagist.org/) to have the module accessible to developers. It'll automatically get picked
|
||||
up by [addons.silverstripe.org](http://addons.silverstripe.org/) website due to the `silverstripe` keyword in the file.
|
||||
|
||||
Note that SilverStripe modules have the following distinct characteristics:
|
||||
Note that Silverstripe CMS modules have the following distinct characteristics:
|
||||
|
||||
- SilverStripe can hook in to the composer installation process by declaring `type: silverstripe-vendormodule`.
|
||||
- Silverstripe CMS can hook in to the composer installation process by declaring `type: silverstripe-vendormodule`.
|
||||
- Any folder which should be exposed to the public webroot must be declared in the `extra.expose` config.
|
||||
These paths will be automatically rewritten to public urls which don't directly serve files from the `vendor`
|
||||
folder. For instance, `vendor/my-vendor/my-module/client` will be rewritten to
|
||||
@ -84,22 +84,22 @@ Requirements::javascript('my-vendor/my-module:client/js/script.js');
|
||||
|
||||
## Releasing versions
|
||||
|
||||
Over time you may have to release new versions of your module to continue to work with newer versions of SilverStripe.
|
||||
Over time you may have to release new versions of your module to continue to work with newer versions of Silverstripe CMS.
|
||||
By using Composer, this is made easy for developers by allowing them to specify what version they want to use. Each
|
||||
version of your module should be a separate branch in your version control and each branch should have a `composer.json`
|
||||
file explicitly defining what versions of SilverStripe you support.
|
||||
file explicitly defining what versions of Silverstripe CMS you support.
|
||||
|
||||
Say you have a module which supports SilverStripe 3.0. A new release of this module takes advantage of new features
|
||||
in SilverStripe 3.1. In this case, you would create a new branch for the 3.0 compatible code base of your module. This
|
||||
Say you have a module which supports Silverstripe CMS 3.0. A new release of this module takes advantage of new features
|
||||
in Silverstripe CMS 3.1. In this case, you would create a new branch for the 3.0 compatible code base of your module. This
|
||||
allows you to continue fixing bugs on this older release branch.
|
||||
|
||||
[info]
|
||||
As a convention, the `master` branch of your module should always work with the `master` branch of SilverStripe.
|
||||
As a convention, the `master` branch of your module should always work with the `master` branch of Silverstripe CMS.
|
||||
[/info]
|
||||
|
||||
Other branches should be created on your module as needed if they're required to support specific SilverStripe releases.
|
||||
Other branches should be created on your module as needed if they're required to support specific Silverstripe CMS releases.
|
||||
|
||||
You can have an overlap in supported versions, e.g two branches in your module both support SilverStripe 3.1. In this
|
||||
You can have an overlap in supported versions, e.g two branches in your module both support Silverstripe CMS 3.1. In this
|
||||
case, you should explain the differences in your `README.md` file.
|
||||
|
||||
Here's some common values for your `require` section
|
||||
|
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: How To's
|
||||
---
|
||||
# How To's: Extending Silverstripe
|
||||
# How To's: Extending Silverstripe CMS
|
||||
|
||||
[CHILDREN]
|
@ -1,15 +1,15 @@
|
||||
---
|
||||
title: Extending SilverStripe
|
||||
title: Extending Silverstripe CMS
|
||||
summary: Understand the ways to modify the built-in functionality through Extensions, Subclassing and Dependency Injection.
|
||||
introduction: SilverStripe is easily extensible to meet custom application requirements. This guide covers the wide range of API's to modify built-in functionality and make your own code easily extensible.
|
||||
introduction: Silverstripe CMS is easily extensible to meet custom application requirements. This guide covers the wide range of API's to modify built-in functionality and make your own code easily extensible.
|
||||
icon: code
|
||||
---
|
||||
|
||||
No two applications are ever going to be the same and SilverStripe is built with this in mind. The core framework
|
||||
No two applications are ever going to be the same and Silverstripe CMS is built with this in mind. The core framework
|
||||
includes common functionality and default behaviors easily complemented with add-ons such as modules, widgets and
|
||||
themes.
|
||||
|
||||
SilverStripe includes a myriad of extension API's such as *Extension Hooks* and support for programming patterns
|
||||
Silverstripe CMS includes a myriad of extension API's such as *Extension Hooks* and support for programming patterns
|
||||
such as *Dependency Injection*. Allowing developers to tailor the framework to their needs without modifying the core
|
||||
framework.
|
||||
|
||||
|
@ -47,7 +47,7 @@ Test case classes should end with `Test` (e.g `PageTest`) and test methods must
|
||||
Ensure you [import](http://php.net/manual/en/language.namespaces.importing.php#example-252) any classes you need for the test, including `SilverStripe\Dev\SapphireTest` or `SilverStripe\Dev\FunctionalTest`.
|
||||
[/info]
|
||||
|
||||
A SilverStripe unit test is created by extending one of two classes, [SapphireTest](api:SilverStripe\Dev\SapphireTest) or [FunctionalTest](api:SilverStripe\Dev\FunctionalTest).
|
||||
A Silverstripe CMS unit test is created by extending one of two classes, [SapphireTest](api:SilverStripe\Dev\SapphireTest) or [FunctionalTest](api:SilverStripe\Dev\FunctionalTest).
|
||||
|
||||
[SapphireTest](api:SilverStripe\Dev\SapphireTest) is used to test your model logic (such as a `DataObject`), and [FunctionalTest](api:SilverStripe\Dev\FunctionalTest) is used when
|
||||
you want to test a `Controller`, `Form` or anything that requires a web page.
|
||||
@ -63,7 +63,7 @@ documentation.
|
||||
|
||||
## Test Databases and Fixtures
|
||||
|
||||
SilverStripe tests create their own database when the test starts and fixture files are specified. New `ss_tmp` databases are created using the same
|
||||
Silverstripe CMS tests create their own database when the test starts and fixture files are specified. New `ss_tmp` databases are created using the same
|
||||
connection details you provide for the main website. The new `ss_tmp` database does not copy what is currently in your
|
||||
application database. To provide seed data use a [Fixture](fixtures) file.
|
||||
|
||||
@ -79,7 +79,7 @@ databases on your machine. To get rid of them, run `sake dev/tasks/CleanupTestDa
|
||||
|
||||
## Custom PHPUnit Configuration
|
||||
|
||||
The `phpunit` executable can be configured by command line arguments or through an XML file. SilverStripe comes with a
|
||||
The `phpunit` executable can be configured by command line arguments or through an XML file. Silverstripe CMS comes with a
|
||||
default `phpunit.xml.dist` that you can use as a starting point. Copy the file into `phpunit.xml` and customize to your
|
||||
needs.
|
||||
|
||||
|
@ -27,8 +27,8 @@ Performs a POST request on $url and retrieves the [HTTPResponse](api:SilverStrip
|
||||
of the response.
|
||||
|
||||
<div class="notice" markdown="1">
|
||||
**Compatibility Notice:** Previous versions of SilverStripe would send a GET request if `post()` was called with no POST variables supplied in the second argument.
|
||||
SilverStripe 4.6 and later always sends a POST request for consistency.
|
||||
**Compatibility Notice:** Previous versions of Silverstripe CMS would send a GET request if `post()` was called with no POST variables supplied in the second argument.
|
||||
Silverstripe CMS 4.6 and later always sends a POST request for consistency.
|
||||
</div>
|
||||
|
||||
## Other Requests
|
||||
|
@ -5,5 +5,5 @@ summary: Describe how your application should behave in plain text and run tests
|
||||
|
||||
# Behavior Testing
|
||||
|
||||
For behavior testing in SilverStripe, check out
|
||||
[SilverStripe Behat Documentation](https://github.com/silverstripe-labs/silverstripe-behat-extension/).
|
||||
For behavior testing in Silverstripe CMS, check out
|
||||
[Silverstripe CMS Behat Documentation](https://github.com/silverstripe-labs/silverstripe-behat-extension/).
|
||||
|
@ -7,7 +7,7 @@ summary: Populate test databases with fake seed data.
|
||||
|
||||
To test functionality correctly, we must use consistent data. If we are testing our code with the same data each
|
||||
time, we can trust our tests to yield reliable results and to identify when the logic changes. Each test run in
|
||||
SilverStripe starts with a fresh database containing no records. `Fixtures` provide a way to describe the initial data
|
||||
Silverstripe CMS starts with a fresh database containing no records. `Fixtures` provide a way to describe the initial data
|
||||
to load into the database. The [SapphireTest](api:SilverStripe\Dev\SapphireTest) class takes care of populating a test database with data from
|
||||
fixtures - all we have to do is define them.
|
||||
|
||||
@ -189,7 +189,7 @@ test.
|
||||
|
||||
### Fixtures for namespaced classes
|
||||
|
||||
As of SilverStripe 4 you will need to use fully qualfied class names in your YAML fixture files. In the above examples, they belong to the global namespace so there is nothing requires, but if you have a deeper DataObject, or it has a relationship to models that are part of the framework for example, you will need to include their namespaces:
|
||||
As of Silverstripe CMS 4 you will need to use fully qualfied class names in your YAML fixture files. In the above examples, they belong to the global namespace so there is nothing requires, but if you have a deeper DataObject, or it has a relationship to models that are part of the framework for example, you will need to include their namespaces:
|
||||
|
||||
|
||||
```yml
|
||||
@ -204,7 +204,7 @@ MyProject\Model\Team:
|
||||
```
|
||||
|
||||
[notice]
|
||||
If your tests are failing and your database has table names that follow the fully qualified class names, you've probably forgotten to implement `private static $table_name = 'Player';` on your namespaced class. This property was introduced in SilverStripe 4 to reduce data migration work. See [DataObject](api:SilverStripe\ORM\DataObject) for an example.
|
||||
If your tests are failing and your database has table names that follow the fully qualified class names, you've probably forgotten to implement `private static $table_name = 'Player';` on your namespaced class. This property was introduced in Silverstripe CMS 4 to reduce data migration work. See [DataObject](api:SilverStripe\ORM\DataObject) for an example.
|
||||
[/notice]
|
||||
|
||||
### Defining many_many_extraFields
|
||||
|
@ -6,7 +6,7 @@ summary: All the jargon you need to be a bonafide testing guru
|
||||
<dl>
|
||||
<dt>Assertion<dd>A predicate statement that must be true when a test runs.
|
||||
|
||||
<dt>Behat<dd>A behaviour-driven testing library used with SilverStripe as a higher-level alternative to the `FunctionalTest` API, see <http://behat.org>.
|
||||
<dt>Behat<dd>A behaviour-driven testing library used with Silverstripe CMS as a higher-level alternative to the `FunctionalTest` API, see <http://behat.org>.
|
||||
|
||||
<dt>Test Case<dd>The atomic class type in most unit test frameworks. New unit tests are created by inheriting from the base test case.
|
||||
|
||||
|
@ -108,7 +108,7 @@ The example **phpunit.xml** file should be placed in the root folder of your pro
|
||||
|
||||
## Caching
|
||||
|
||||
Just like on web requests, SilverStripe caches metadata about the execution context. This cache can get stale, e.g. when you change YAML configuration or add certain types of PHP code. In order to flush the cache, the **first time** this test is run use the `flush=1` CLI parameter:
|
||||
Just like on web requests, Silverstripe CMS caches metadata about the execution context. This cache can get stale, e.g. when you change YAML configuration or add certain types of PHP code. In order to flush the cache, the **first time** this test is run use the `flush=1` CLI parameter:
|
||||
|
||||
```sh
|
||||
vendor/bin/phpunit app/tests/PageTest.php '' flush=1
|
||||
|
@ -6,7 +6,7 @@ icon: envelope
|
||||
|
||||
# Testing Email within Unit Tests
|
||||
|
||||
SilverStripe's test system has built-in support for testing emails sent using the [Email](api:SilverStripe\Control\Email\Email) class. If you are
|
||||
Silverstripe CMS's test system has built-in support for testing emails sent using the [Email](api:SilverStripe\Control\Email\Email) class. If you are
|
||||
running a [SapphireTest](api:SilverStripe\Dev\SapphireTest) test, then it holds off actually sending the email, and instead lets you assert that an
|
||||
email was sent using this method.
|
||||
|
||||
|
@ -5,26 +5,26 @@ summary: Deploy robust applications by bundling Unit and Behavior tests with you
|
||||
|
||||
# Unit and Integration Testing
|
||||
|
||||
For behaviour testing in SilverStripe, check out [SilverStripe Behat Documentation](https://github.com/silverstripe-labs/silverstripe-behat-extension/).
|
||||
For behaviour testing in Silverstripe CMS, check out [Silverstripe CMS Behat Documentation](https://github.com/silverstripe-labs/silverstripe-behat-extension/).
|
||||
|
||||
## Introduction
|
||||
|
||||
The SilverStripe core contains various features designed to simplify the process of creating and managing automated tests.
|
||||
The Silverstripe CMS core contains various features designed to simplify the process of creating and managing automated tests.
|
||||
|
||||
SilverStripe uses [PHPUnit](http://www.phpunit.de) for unit tests, and the framework contains features to simplify the
|
||||
Silverstripe CMS uses [PHPUnit](http://www.phpunit.de) for unit tests, and the framework contains features to simplify the
|
||||
process of creating and managing tests.
|
||||
|
||||
If you're more familiar with unit testing, but want a refresher of some of the concepts and terminology, you can browse
|
||||
the [Testing Glossary](testing_glossary). To get started now, follow the installation instructions below.
|
||||
|
||||
If you are familiar with PHP coding but new to unit testing then check out Mark's presentation [Getting to Grips with SilverStripe Testing](http://www.slideshare.net/maetl/getting-to-grips-with-silverstripe-testing).
|
||||
If you are familiar with PHP coding but new to unit testing then check out Mark's presentation [Getting to Grips with Silverstripe CMS Testing](http://www.slideshare.net/maetl/getting-to-grips-with-silverstripe-testing).
|
||||
|
||||
You should also read over the [PHPUnit manual](http://www.phpunit.de/manual/current/en/). It provides a lot of
|
||||
fundamental concepts that we build on in this documentation.
|
||||
|
||||
## Running Tests
|
||||
|
||||
In order to run tests, you need to install SilverStripe using [/getting-started/composer](Composer),
|
||||
In order to run tests, you need to install Silverstripe CMS using [/getting-started/composer](Composer),
|
||||
which will pull in the required development dependencies to run tests.
|
||||
|
||||
Tests are run from the commandline, in your webroot folder:
|
||||
@ -42,7 +42,7 @@ to your `$PATH` definition in the shell profile (usually `~/.profile`): `PATH=./
|
||||
|
||||
## Caching
|
||||
|
||||
Just like on web requests, SilverStripe caches metadata about the execution context.
|
||||
Just like on web requests, Silverstripe CMS caches metadata about the execution context.
|
||||
This cache can get stale, e.g. when you change YAML configuration or add certain types of PHP code.
|
||||
In order to flush the cache, use the `flush=1` CLI parameter:
|
||||
|
||||
@ -82,7 +82,7 @@ or through an XML file. File-based configuration has
|
||||
the advantage of enforcing certain rules across test executions (e.g. excluding files from code coverage reports), and
|
||||
of course this information can be version controlled and shared with other team members.
|
||||
|
||||
SilverStripe comes with a default `phpunit.xml.dist` that you can use as a starting point. Copy the file into a new
|
||||
Silverstripe CMS comes with a default `phpunit.xml.dist` that you can use as a starting point. Copy the file into a new
|
||||
`phpunit.xml` and customize to your needs - PHPUnit will auto-detect its existence, and prioritize it over the default
|
||||
file.
|
||||
|
||||
@ -92,7 +92,7 @@ There's nothing stopping you from creating multiple XML files (see the `--config
|
||||
|
||||
### Database Permissions
|
||||
|
||||
SilverStripe tests create their own temporary database on every execution. Because of this the database user in your config file
|
||||
Silverstripe CMS tests create their own temporary database on every execution. Because of this the database user in your config file
|
||||
should have the appropriate permissions to create new databases on your server, otherwise tests will not run.
|
||||
|
||||
## Writing Tests
|
||||
@ -109,8 +109,8 @@ You will generally write two different kinds of test classes.
|
||||
* **Unit Test:** Test the behaviour of one of your DataObjects.
|
||||
* **Functional Test:** Test the behaviour of one of your controllers.
|
||||
|
||||
Tutorials and recipes for creating tests using the SilverStripe framework:
|
||||
Tutorials and recipes for creating tests using the Silverstripe CMS:
|
||||
|
||||
* [Creating a SilverStripe test](how_tos/write_a_sapphiretest): Writing tests to check core data objects
|
||||
* [Creating a Silverstripe CMS test](how_tos/write_a_sapphiretest): Writing tests to check core data objects
|
||||
* [Creating a functional test](how_tos/write_a_functionaltest): An overview of functional tests and how to write a functional test
|
||||
* [Testing Outgoing Email](how_tos/testing_email): An overview of the built-in email testing code
|
||||
|
@ -1,12 +1,12 @@
|
||||
---
|
||||
title: Environment Types
|
||||
summary: Configure your SilverStripe environment to define how your web application behaves.
|
||||
summary: Configure your Silverstripe CMS environment to define how your web application behaves.
|
||||
icon: exclamation-circle
|
||||
---
|
||||
|
||||
# Environment Types
|
||||
|
||||
SilverStripe knows three different environment types (or "modes"). Each of the modes gives you different tools
|
||||
Silverstripe CMS knows three different environment types (or "modes"). Each of the modes gives you different tools
|
||||
and behaviors. The environment is managed by the `SS_ENVIRONMENT_TYPE` variable through an
|
||||
[environment configuration file](../../getting_started/environment_management).
|
||||
The three environment types you can set are `dev`, `test` and `live`.
|
||||
@ -27,7 +27,7 @@ on a public server very carefully.
|
||||
|
||||
Test mode is designed for staging environments or other private collaboration sites before deploying a site live.
|
||||
|
||||
In this mode error messages are hidden from the user and SilverStripe includes [BasicAuth](api:SilverStripe\Security\BasicAuth) integration if you
|
||||
In this mode error messages are hidden from the user and Silverstripe CMS includes [BasicAuth](api:SilverStripe\Security\BasicAuth) integration if you
|
||||
want to password protect the site. You can enable that by adding this to your `app/_config/app.yml` file:
|
||||
|
||||
|
||||
@ -42,7 +42,7 @@ SilverStripe\Security\BasicAuth:
|
||||
|
||||
The default password protection in this mode (Basic Auth) is an oudated security measure which passes credentials without encryption over the network.
|
||||
It is considered insecure unless this connection itself is secured (via HTTPS).
|
||||
It also doesn't prevent access to web requests which aren't handled via SilverStripe (e.g. published assets).
|
||||
It also doesn't prevent access to web requests which aren't handled via Silverstripe CMS (e.g. published assets).
|
||||
Consider using additional authentication and authorisation measures to secure access (e.g. IP whitelists).
|
||||
|
||||
When using CGI/FastCGI with Apache, you will have to add the `RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]` rewrite rule to your `.htaccess` file
|
||||
|
@ -6,10 +6,10 @@ icon: exclamation-circle
|
||||
|
||||
# Logging and Error Handling
|
||||
|
||||
SilverStripe uses Monolog for both error handling and logging. It comes with two default configurations: one for
|
||||
Silverstripe CMS uses Monolog for both error handling and logging. It comes with two default configurations: one for
|
||||
logging, and another for core error handling. The core error handling implementation also comes with two default
|
||||
configurations: one for development environments, and another for test or live environments. On development
|
||||
environments, SilverStripe will deal harshly with any warnings or errors: a full call-stack is shown and execution
|
||||
environments, Silverstripe CMS will deal harshly with any warnings or errors: a full call-stack is shown and execution
|
||||
stops for anything, giving you early warning of a potential issue to handle.
|
||||
|
||||
## Raising errors and logging diagnostic information.
|
||||
@ -254,8 +254,8 @@ SilverStripe\Core\Injector\Injector:
|
||||
```
|
||||
|
||||
[info]
|
||||
In addition to SilverStripe-integrated logging, it is advisable to fall back to PHP's native logging functionality. A
|
||||
script might terminate before it reaches the SilverStripe error handling, for example in the case of a fatal error. Make
|
||||
In addition to Silverstripe CMS integrated logging, it is advisable to fall back to PHP's native logging functionality. A
|
||||
script might terminate before it reaches the Silverstripe CMS error handling, for example in the case of a fatal error. Make
|
||||
sure `log_errors` and `error_log` in your PHP ini file are configured.
|
||||
[/info]
|
||||
|
||||
@ -267,7 +267,7 @@ others.
|
||||
|
||||
### Replacing the logger
|
||||
|
||||
Monolog comes by default with SilverStripe, but you may use another PSR-3 compliant logger, if you wish. To do this,
|
||||
Monolog comes by default with Silverstripe CMS, but you may use another PSR-3 compliant logger, if you wish. To do this,
|
||||
set the `SilverStripe\Core\Injector\Injector.Monolog\Logger` configuration parameter, providing a new injector
|
||||
definition. For example:
|
||||
|
||||
@ -303,9 +303,9 @@ SilverStripe\Core\Injector\Injector:
|
||||
|
||||
You should register something with a `start()` method.
|
||||
|
||||
## Differences from SilverStripe 3
|
||||
## Differences from Silverstripe CMS 3
|
||||
|
||||
In SilverStripe 3, logging was based on the Zend Log module. Customisations were added using `SS_Log::add_writer()`.
|
||||
In Silverstripe CMS 3, logging was based on the Zend Log module. Customisations were added using `SS_Log::add_writer()`.
|
||||
This function no longer works, and any Zend Log writers will need to be replaced with Monolog handlers. Fortunately,
|
||||
a range of handlers are available, both in the core package and in add-ons. See the
|
||||
[Monolog documentation](https://github.com/Seldaek/monolog/blob/master/doc/01-usage.md) for more information.
|
||||
|
@ -7,12 +7,12 @@ summary: Useful debugging tools you can use right in the browser
|
||||
## Introduction
|
||||
|
||||
This page lists a number of "page options" , "rendering tools" or "special URL variables" that you can use to debug your
|
||||
SilverStripe applications. These are consumed in PHP using the $_REQUEST or $_GET superglobals throughout the SilverStripe
|
||||
core.
|
||||
Silverstripe CMS applications. These are consumed in PHP using the $_REQUEST or $_GET superglobals throughout the
|
||||
Silverstripe CMS core.
|
||||
|
||||
## Debug Toolbar
|
||||
|
||||
The easiest way to debug SilverStripe is through the
|
||||
The easiest way to debug Silverstripe CMS is through the
|
||||
[lekoala/silverstripe-debugbar](https://github.com/lekoala/silverstripe-debugbar) module.
|
||||
It similar to the browser "developer toolbar", and adds itself to the bottom of the screen
|
||||
when your site is in development mode. It shows you render times, database queries,
|
||||
|
@ -5,7 +5,7 @@ icon: bug
|
||||
---
|
||||
# Debugging
|
||||
|
||||
SilverStripe can be a large and complex framework to debug, but there are ways to make debugging less painful. In this
|
||||
Silverstripe CMS can be a large and complex framework to debug, but there are ways to make debugging less painful. In this
|
||||
guide we show the basics on defining the correct [Environment Type](environment_types) for your application and other
|
||||
built-in helpers for dealing with application errors.
|
||||
|
||||
@ -13,7 +13,7 @@ built-in helpers for dealing with application errors.
|
||||
|
||||
## Performance
|
||||
|
||||
See the [Profiling](../performance/profiling) documentation for more information on profiling SilverStripe to track down
|
||||
See the [Profiling](../performance/profiling) documentation for more information on profiling Silverstripe CMS to track down
|
||||
bottle-necks and identify slow moving parts of your application chain.
|
||||
|
||||
## Debugging Utilities
|
||||
|
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Partial Caching
|
||||
summary: Cache SilverStripe templates to reduce database queries.
|
||||
summary: Cache Silverstripe CMS templates to reduce database queries.
|
||||
icon: tachometer-alt
|
||||
---
|
||||
|
||||
|
@ -38,7 +38,7 @@ Note that this library describes usage of [PSR-6](http://www.php-fig.org/psr/psr
|
||||
but also exposes caches following the PSR-16 interface.
|
||||
|
||||
Cache objects are configured via YAML
|
||||
and SilverStripe's [dependency injection](/developer_guides/extending/injector) system.
|
||||
and Silverstripe CMS's [dependency injection](/developer_guides/extending/injector) system.
|
||||
|
||||
|
||||
```yml
|
||||
@ -184,7 +184,7 @@ interface. Use this interface to trigger `clear()` on your caches.
|
||||
|
||||
## Adapters
|
||||
|
||||
SilverStripe tries to identify the most performant cache available on your system
|
||||
Silverstripe CMS tries to identify the most performant cache available on your system
|
||||
through the [DefaultCacheFactory](api:SilverStripe\Core\Cache\DefaultCacheFactory) implementation:
|
||||
|
||||
* `PhpFilesCache` (PHP 5.6 or PHP 7 with [opcache](http://php.net/manual/en/book.opcache.php) enabled).
|
||||
|
@ -8,7 +8,7 @@ icon: tachometer-alt
|
||||
|
||||
## Overview
|
||||
|
||||
By default, SilverStripe sends headers which signal to HTTP caches
|
||||
By default, Silverstripe CMS sends headers which signal to HTTP caches
|
||||
that the response should be not considered cacheable.
|
||||
HTTP caches can either be intermediary caches (e.g. CDNs and proxies), or clients (e.g. browsers).
|
||||
The cache headers sent are `Cache-Control: no-cache, must-revalidate`;
|
||||
@ -121,7 +121,7 @@ class PageController extends ContentController
|
||||
}
|
||||
```
|
||||
|
||||
Note: SilverStripe will still override this preference when a session is active,
|
||||
Note: Silverstripe CMS will still override this preference when a session is active,
|
||||
a [CSRF token](/developer_guides/forms/form_security) token is present,
|
||||
or draft content has been requested.
|
||||
|
||||
@ -150,14 +150,14 @@ class PageController extends ContentController
|
||||
}
|
||||
```
|
||||
|
||||
Note: SilverStripe will still override this preference when a session is active,
|
||||
Note: Silverstripe CMS will still override this preference when a session is active,
|
||||
a [CSRF token](/developer_guides/forms/form_security) token is present,
|
||||
or draft content has been requested.
|
||||
|
||||
### Global opt-in, ignoring session (advanced)
|
||||
|
||||
This can be helpful in situations where forms are embedded on the website.
|
||||
SilverStripe will still override this preference when draft content has been requested.
|
||||
Silverstripe CMS will still override this preference when draft content has been requested.
|
||||
CAUTION: This mode relies on a developer examining each execution path to ensure
|
||||
that no session data is used to vary output.
|
||||
|
||||
@ -218,7 +218,7 @@ HTTP::register_modification_date('2014-10-10');
|
||||
|
||||
A `Vary` header tells caches which aspects of the response should be considered
|
||||
when calculating a cache key, usually in addition to the full URL.
|
||||
By default, SilverStripe will output a `Vary` header with the following content:
|
||||
By default, Silverstripe CMS will output a `Vary` header with the following content:
|
||||
|
||||
```
|
||||
Vary: X-Forwarded-Protocol
|
||||
|
@ -9,7 +9,7 @@ icon: tachometer-alt
|
||||
Profiling is the best way to identify bottle necks and other slow moving parts of your application prime for
|
||||
optimization.
|
||||
|
||||
SilverStripe does not include any profiling tools out of the box, but we recommend the use of existing tools such as
|
||||
Silverstripe CMS does not include any profiling tools out of the box, but we recommend the use of existing tools such as
|
||||
[XHProf](https://github.com/facebook/xhprof/) and [XDebug](http://xdebug.org/).
|
||||
|
||||
* [Profiling with XHProf](https://inviqa.com/blog/profiling-xhprof)
|
||||
|
@ -5,7 +5,7 @@ summary: Export your web pages as static HTML and serve the web like it's 1999.
|
||||
|
||||
# Static Publishing
|
||||
|
||||
One of the best ways to get the top performance out of SilverStripe is to bypass it completely. This saves on any loading
|
||||
One of the best ways to get the top performance out of Silverstripe CMS is to bypass it completely. This saves on any loading
|
||||
time, connecting to the database and formatting your templates. This is only appropriate approach on web pages that
|
||||
have completely static content.
|
||||
|
||||
@ -14,7 +14,7 @@ If you want to cache part of a page, or your site has interactive elements such
|
||||
[Partial Caching](partial_caching) is more suitable.
|
||||
[/info]
|
||||
|
||||
By publishing the page as HTML it's possible to run SilverStripe from behind a corporate firewall, on a low performance
|
||||
By publishing the page as HTML it's possible to run Silverstripe CMS from behind a corporate firewall, on a low performance
|
||||
server or serve millions of hits an hour without expensive hardware.
|
||||
|
||||
This functionality is available through the [Static Publisher with Queue](https://github.com/silverstripe/silverstripe-staticpublishqueue) module. The module provides hooks for developers to generate static HTML files for the whole application or publish key pages (e.g a web applications home page) as HTML to reduce load on the server.
|
||||
|
@ -1,12 +1,12 @@
|
||||
---
|
||||
title: Resource Usage
|
||||
summary: Manage SilverStripe's memory footprint and CPU usage.
|
||||
summary: Manage Silverstripe CMS's memory footprint and CPU usage.
|
||||
icon: tachometer-alt
|
||||
---
|
||||
|
||||
# Resource Usage
|
||||
|
||||
SilverStripe tries to keep its resource usage within the documented limits
|
||||
Silverstripe CMS tries to keep its resource usage within the documented limits
|
||||
(see the [server requirements](../../getting_started/server_requirements)).
|
||||
|
||||
These limits are defined through `memory_limit` and `max_execution_time` in the PHP configuration. They can be
|
||||
@ -22,7 +22,7 @@ resources are required temporarily. In general, we recommend running resource in
|
||||
[command line](../cli), where configuration defaults for these settings are higher or even unlimited.
|
||||
|
||||
[info]
|
||||
SilverStripe can request more resources through `Environment::increaseMemoryLimitTo()` and
|
||||
Silverstripe CMS can request more resources through `Environment::increaseMemoryLimitTo()` and
|
||||
`Environment::increaseTimeLimitTo()` functions.
|
||||
[/info]
|
||||
|
||||
|
@ -5,8 +5,8 @@ introduction: Make your applications faster by learning how to write more scalab
|
||||
icon: tachometer-alt
|
||||
---
|
||||
|
||||
The following guide describes the common ways to speed your SilverStripe website up. The general rules for getting
|
||||
the best performance out of SilverStripe include running the latest versions of PHP alongside a
|
||||
The following guide describes the common ways to speed your Silverstripe CMS website up. The general rules for getting
|
||||
the best performance out of Silverstripe CMS include running the latest versions of PHP alongside a
|
||||
[opcode](http://en.wikipedia.org/wiki/Opcode) cache such as [XCache](http://xcache.lighttpd.net/) or
|
||||
[APC](http://nz2.php.net/manual/en/intro.apc.php).
|
||||
|
||||
|
@ -8,7 +8,7 @@ icon: user
|
||||
|
||||
## Introduction
|
||||
|
||||
The [Member](api:SilverStripe\Security\Member) class is used to represent user accounts on a SilverStripe site (including newsletter recipients).
|
||||
The [Member](api:SilverStripe\Security\Member) class is used to represent user accounts on a Silverstripe CMS site (including newsletter recipients).
|
||||
|
||||
## Testing For Logged In Users
|
||||
|
||||
|
@ -5,12 +5,12 @@ icon: user-lock
|
||||
---
|
||||
# Access Control and Page Security
|
||||
|
||||
There is a fairly comprehensive security mechanism in place for SilverStripe. If you want to add premium content to your
|
||||
There is a fairly comprehensive security mechanism in place for Silverstripe CMS. If you want to add premium content to your
|
||||
site you have to figure this stuff out, and it's not entirely obvious.
|
||||
|
||||
## Ways to restrict access
|
||||
|
||||
There are a number of ways to restrict access in SilverStripe. In the security tab in the CMS you can create groups
|
||||
There are a number of ways to restrict access in Silverstripe CMS. In the security tab in the CMS you can create groups
|
||||
that have access to certain parts. The options can be found on the [permissions](/developer_guides/security/permissions) documentation.
|
||||
|
||||
Once you have groups, you can set access for each page for a particular group. This can be:
|
||||
@ -20,7 +20,7 @@ Once you have groups, you can set access for each page for a particular group.
|
||||
|
||||
It is unclear how this works for data-objects that are not pages.
|
||||
|
||||
## The Security Groups in SilverStripe
|
||||
## The Security Groups in Silverstripe CMS
|
||||
|
||||
In the security tab you can make groups for security. The way this was intended was as follows (this may be a counter
|
||||
intuitive):
|
||||
@ -40,7 +40,7 @@ privileges from its parent group.
|
||||
|
||||
## Permission checking is at class level
|
||||
|
||||
SilverStripe provides a security mechanism via the *Permission::check* method (see [LeftAndMain](api:SilverStripe\Admin\LeftAndMain) for examples on how
|
||||
Silverstripe CMS provides a security mechanism via the *Permission::check* method (see [LeftAndMain](api:SilverStripe\Admin\LeftAndMain) for examples on how
|
||||
the admin screens work).
|
||||
|
||||
(next step -- go from *Permission::checkMember*...)
|
||||
|
@ -7,7 +7,7 @@ icon: lock
|
||||
|
||||
## Introduction
|
||||
|
||||
This class implements SilverStripe's permission system.
|
||||
This class implements Silverstripe CMS's permission system.
|
||||
|
||||
## Usage
|
||||
|
||||
|
@ -1,22 +1,22 @@
|
||||
---
|
||||
title: Authentication
|
||||
summary: Explains SilverStripe's Authentication options and custom authenticators.
|
||||
summary: Explains Silverstripe CMS's Authentication options and custom authenticators.
|
||||
icon: users-cog
|
||||
---
|
||||
|
||||
# Authentication
|
||||
|
||||
By default, SilverStripe provides a [MemberAuthenticator](api:SilverStripe\Security\MemberAuthenticator\MemberAuthenticator) class which hooks into its own internal
|
||||
By default, Silverstripe CMS provides a [MemberAuthenticator](api:SilverStripe\Security\MemberAuthenticator\MemberAuthenticator) class which hooks into its own internal
|
||||
authentication system.
|
||||
|
||||
## User Interface
|
||||
|
||||
SilverStripe comes with a default login form interface,
|
||||
Silverstripe CMS comes with a default login form interface,
|
||||
that's embedded into your page templates through the `$Form` placeholder.
|
||||
Since it's embedded into your own site styling and behaviour,
|
||||
it can require adjustments to your particular context.
|
||||
|
||||
Starting with SilverStripe 4.5, the view logic may be handled through the
|
||||
Starting with Silverstripe CMS 4.5, the view logic may be handled through the
|
||||
[silverstripe/login-forms](https://github.com/silverstripe/silverstripe-login-forms) module (if present).
|
||||
|
||||
## Controllers
|
||||
@ -48,8 +48,8 @@ following base classes:
|
||||
|
||||
## Default Admin
|
||||
|
||||
When a new SilverStripe site is created for the first time, it may be necessary to create a default admin to provide
|
||||
CMS access for the first time. SilverStripe provides a default admin configuration system, which allows a username
|
||||
When a new Silverstripe CMS site is created for the first time, it may be necessary to create a default admin to provide
|
||||
CMS access for the first time. Silverstripe CMS provides a default admin configuration system, which allows a username
|
||||
and password to be configured for a single special user outside of the normal membership system.
|
||||
|
||||
It is advisable to configure this user in your `.env` file inside of the web root, as below:
|
||||
|
@ -7,7 +7,7 @@ icon: user-secret
|
||||
|
||||
## Introduction
|
||||
|
||||
This page details notes on how to ensure that we develop secure SilverStripe applications.
|
||||
This page details notes on how to ensure that we develop secure Silverstripe CMS applications.
|
||||
See our "[Release Process](/contributing/release_process#security-releases) on how to report security issues.
|
||||
|
||||
## SQL Injection
|
||||
@ -70,7 +70,7 @@ DB::prepared_query(
|
||||
|
||||
### Automatic escaping
|
||||
|
||||
SilverStripe internally will use parameterised queries in SQL statements wherever possible.
|
||||
Silverstripe CMS internally will use parameterised queries in SQL statements wherever possible.
|
||||
|
||||
If necessary Silverstripe performs any required escaping through database-specific methods (see [Database::addslashes()](api:SilverStripe\ORM\Connect\Database::addslashes())).
|
||||
For [MySQLDatabase](api:SilverStripe\ORM\Connect\MySQLDatabase), this will be `[mysql_real_escape_string()](http://de3.php.net/mysql_real_escape_string)`.
|
||||
@ -201,13 +201,13 @@ variables ($RAW_data instead of $data).
|
||||
|
||||
## XSS (Cross-Site-Scripting)
|
||||
|
||||
SilverStripe helps you guard any output against clientside attacks initiated by malicious user input, commonly known as
|
||||
Silverstripe CMS helps you guard any output against clientside attacks initiated by malicious user input, commonly known as
|
||||
XSS (Cross-Site-Scripting). With some basic guidelines, you can ensure your output is safe for a specific use case (e.g.
|
||||
displaying a blog post in HTML from a trusted author, or escaping a search parameter from an untrusted visitor before
|
||||
redisplaying it).
|
||||
|
||||
[notice]
|
||||
Note: SilverStripe templates do not remove tags, please use [strip_tags()](http://php.net/strip_tags) for this purpose
|
||||
Note: Silverstripe CMS templates do not remove tags, please use [strip_tags()](http://php.net/strip_tags) for this purpose
|
||||
or [sanitize](http://htmlpurifier.org/) it correctly.
|
||||
[/notice]
|
||||
|
||||
@ -216,12 +216,12 @@ for in-depth information about "Cross-Site-Scripting".
|
||||
|
||||
### What if I can't trust my editors?
|
||||
|
||||
The default configuration of SilverStripe assumes some level of trust is given to your editors who have access
|
||||
The default configuration of Silverstripe CMS assumes some level of trust is given to your editors who have access
|
||||
to the CMS. Though the HTML WYSIWYG editor is configured to provide some control over the HTML an editor provides,
|
||||
this is not enforced server side, and so can be bypassed by a malicious editor. A editor that does so can use an
|
||||
XSS attack against an admin to perform any administrative action.
|
||||
|
||||
If you can't trust your editors, SilverStripe must be configured to filter the content so that any javascript is
|
||||
If you can't trust your editors, Silverstripe CMS must be configured to filter the content so that any javascript is
|
||||
stripped out
|
||||
|
||||
To enable filtering, set the HtmlEditorField::$sanitise_server_side [configuration](/developer_guides/configuration/configuration) property to
|
||||
@ -253,7 +253,7 @@ We recommend configuring [shortcodes](/developer_guides/extending/shortcodes) th
|
||||
|
||||
### Escaping model properties
|
||||
|
||||
[SSViewer](api:SilverStripe\View\SSViewer) (the SilverStripe template engine) automatically takes care of escaping HTML tags from specific
|
||||
[SSViewer](api:SilverStripe\View\SSViewer) (the Silverstripe CMS template engine) automatically takes care of escaping HTML tags from specific
|
||||
object-properties by [casting](/developer_guides/model/data_types_and_casting) its string value into a [DBField](api:SilverStripe\ORM\FieldType\DBField) object.
|
||||
|
||||
PHP:
|
||||
@ -447,7 +447,7 @@ HtmlEditorField::$sanitise_server_side config property to true.
|
||||
|
||||
## Cross-Site Request Forgery (CSRF)
|
||||
|
||||
SilverStripe has built-in countermeasures against [CSRF](http://shiflett.org/articles/cross-site-request-forgeries) identity theft for all form submissions. A form object
|
||||
Silverstripe CMS has built-in countermeasures against [CSRF](http://shiflett.org/articles/cross-site-request-forgeries) identity theft for all form submissions. A form object
|
||||
will automatically contain a `SecurityID` parameter which is generated as a secure hash on the server, connected to the
|
||||
currently active session of the user. If this form is submitted without this parameter, or if the parameter doesn't
|
||||
match the hash stored in the users session, the request is discarded.
|
||||
@ -457,7 +457,7 @@ It is also recommended to limit form submissions to the intended HTTP verb (most
|
||||
through [Form::setStrictFormMethodCheck()](api:SilverStripe\Forms\Form::setStrictFormMethodCheck()).
|
||||
|
||||
Sometimes you need to handle state-changing HTTP submissions which aren't handled through
|
||||
SilverStripe's form system. In this case, you can also check the current HTTP request
|
||||
Silverstripe CMS's form system. In this case, you can also check the current HTTP request
|
||||
for a valid token through [SecurityToken::checkRequest()](api:SilverStripe\Security\SecurityToken::checkRequest()).
|
||||
|
||||
## Casting user input
|
||||
@ -503,7 +503,7 @@ cast types can be found here:
|
||||
* `(array)` - cast to array
|
||||
* `(object)` - cast to object
|
||||
|
||||
Note that there is also a 'SilverStripe' way of casting fields on a class, this is a different type of casting to the
|
||||
Note that there is also a 'Silverstripe CMS' way of casting fields on a class, this is a different type of casting to the
|
||||
standard PHP way. See [casting](/developer_guides/model/data_types_and_casting).
|
||||
|
||||
|
||||
@ -570,7 +570,7 @@ list of allowed extensions by adding these to the `File.allowed_extensions` conf
|
||||
|
||||
## Passwords
|
||||
|
||||
SilverStripe stores passwords with a strong hashing algorithm (blowfish) by default
|
||||
Silverstripe CMS stores passwords with a strong hashing algorithm (blowfish) by default
|
||||
(see [PasswordEncryptor](api:SilverStripe\Security\PasswordEncryptor)). It adds randomness to these hashes via
|
||||
salt values generated with the strongest entropy generators available on the platform
|
||||
(see [RandomGenerator](api:SilverStripe\Security\RandomGenerator)). This prevents brute force attacks with
|
||||
@ -581,8 +581,8 @@ you can also enforce specific password policies by configuring a
|
||||
[PasswordValidator](api:SilverStripe\Security\PasswordValidator). This can be done through a `_config.php` file
|
||||
at runtime, or via YAML configuration.
|
||||
|
||||
From SilverStripe 4.3 onwards, the default password validation rules are configured in the framework's `passwords.yml`
|
||||
file. You will need to ensure that your config file is processed after it. For SilverStripe <4.3 you will need to
|
||||
From Silverstripe CMS 4.3 onwards, the default password validation rules are configured in the framework's `passwords.yml`
|
||||
file. You will need to ensure that your config file is processed after it. For Silverstripe CMS <4.3 you will need to
|
||||
use a `_config.php` file to modify the class's config at runtime (see `_config.php` installed in your mysite/app folder
|
||||
if you're using silverstripe/recipe-core).
|
||||
|
||||
@ -660,7 +660,7 @@ as well as the login form.
|
||||
|
||||
## Request hostname forgery {#request-hostname-forgery}
|
||||
|
||||
To prevent a forged hostname appearing being used by the application, SilverStripe
|
||||
To prevent a forged hostname appearing being used by the application, Silverstripe CMS
|
||||
allows the configure of a whitelist of hosts that are allowed to access the system. By defining
|
||||
this whitelist in your `.env` file, any request presenting a `Host` header that is
|
||||
_not_ in this list will be blocked with a HTTP 400 error:
|
||||
@ -672,9 +672,9 @@ SS_ALLOWED_HOSTS="www.example.com,example.com,subdomain.example.com"
|
||||
Please note that if this configuration is defined, you _must_ include _all_ subdomains (eg www.)
|
||||
that will be accessing the site.
|
||||
|
||||
When SilverStripe is run behind a reverse proxy, it's normally necessary for this proxy to
|
||||
When Silverstripe CMS is run behind a reverse proxy, it's normally necessary for this proxy to
|
||||
use the `X-Forwarded-Host` request header to tell the webserver which hostname was originally
|
||||
requested. However, when SilverStripe is not run behind a proxy, this header can still be
|
||||
requested. However, when Silverstripe CMS is not run behind a proxy, this header can still be
|
||||
used by attackers to fool the server into mistaking its own identity.
|
||||
|
||||
The risk of this kind of attack causing damage is especially high on sites which utilise caching
|
||||
@ -725,11 +725,11 @@ following in your .htaccess to ensure this behaviour is activated.
|
||||
</IfModule>
|
||||
```
|
||||
|
||||
As of SilverStripe 4, this behaviour is on by default, and the environment variable is no longer required. For correct operation, it is necessary to always set `SS_TRUSTED_PROXY_IPS` if using a proxy.
|
||||
As of Silverstripe CMS 4, this behaviour is on by default, and the environment variable is no longer required. For correct operation, it is necessary to always set `SS_TRUSTED_PROXY_IPS` if using a proxy.
|
||||
|
||||
## Secure Sessions, Cookies and TLS (HTTPS)
|
||||
|
||||
SilverStripe recommends the use of TLS(HTTPS) for your application, and you can easily force the use through the
|
||||
Silverstripe CMS recommends the use of TLS(HTTPS) for your application, and you can easily force the use through the
|
||||
director function `forceSSL()`
|
||||
|
||||
```php
|
||||
@ -761,7 +761,7 @@ and automatically redirect any requests with basic authentication headers to fir
|
||||
disable this behaviour using `CanonicalURLMiddleware::singleton()->setForceBasicAuthToSSL(false)`, or via Injector
|
||||
configuration in YAML.
|
||||
|
||||
We also want to ensure cookies are not shared between secure and non-secure sessions, so we must tell SilverStripe to
|
||||
We also want to ensure cookies are not shared between secure and non-secure sessions, so we must tell Silverstripe CMS to
|
||||
use a [secure session](https://docs.silverstripe.org/en/3/developer_guides/cookies_and_sessions/sessions/#secure-session-cookie).
|
||||
To do this, you may set the `cookie_secure` parameter to `true` in your `config.yml` for `Session`
|
||||
|
||||
@ -822,7 +822,7 @@ For sensitive pages, such as members areas, or places where sensitive informatio
|
||||
|
||||
- The headers `Cache-control: no-store` and `Pragma: no-cache` along with expiry headers of `Expires: <current date>`
|
||||
and `Date: <current date>` will ensure that sensitive content is not stored locally or able to be retrieved by
|
||||
unauthorised local persons. SilverStripe adds the current date for every request, and we can add the other cache
|
||||
unauthorised local persons. Silverstripe CMS adds the current date for every request, and we can add the other cache
|
||||
headers to the request for our secure controllers:
|
||||
|
||||
```php
|
||||
|
@ -1,18 +1,18 @@
|
||||
---
|
||||
title: Rate Limiting
|
||||
summary: SilverStripe's in built rate limiting features
|
||||
summary: Silverstripe CMS's in built rate limiting features
|
||||
icon: tachometer-alt
|
||||
---
|
||||
|
||||
# Rate Limiting
|
||||
|
||||
SilverStripe Framework comes with a [Middleware](../controllers/middlewares/) that provides rate limiting
|
||||
for the Security controller. This provides added protection to a potentially vulnerable part of a SilverStripe application
|
||||
Silverstripe CMS comes with a [Middleware](../controllers/middlewares/) that provides rate limiting
|
||||
for the Security controller. This provides added protection to a potentially vulnerable part of a Silverstripe CMS application
|
||||
where an attacker is free to bombard your login forms or other Security endpoints.
|
||||
|
||||
## Applying rate limiting to controllers
|
||||
|
||||
You can apply rate limiting to other specific controllers or your entire SilverStripe application. When applying rate
|
||||
You can apply rate limiting to other specific controllers or your entire Silverstripe CMS application. When applying rate
|
||||
limiting to other controllers you can define custom limits for each controller.
|
||||
|
||||
First, you need to define your rate limit middleware with the required settings:
|
||||
|
@ -1,12 +1,12 @@
|
||||
---
|
||||
title: Personal Data
|
||||
summary: How the SilverStripe CMS deals with data privacy
|
||||
summary: How the Silverstripe CMS deals with data privacy
|
||||
icon: user-ninja
|
||||
---
|
||||
|
||||
# Personal Data
|
||||
|
||||
SilverStripe is an application framework which can be used to process
|
||||
Silverstripe CMS is an application framework which can be used to process
|
||||
and store data. Any data can be sensitive, particularly if it is
|
||||
considered personal data. Many regulatory frameworks such as the
|
||||
[EU General Data Protection Regulation (GDPR)](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation)
|
||||
@ -14,19 +14,19 @@ can be interpreted to regard basic data points such as email and IP addresses
|
||||
as personally identifiable data.
|
||||
|
||||
This document is aiding implementors and auditors in determining
|
||||
the impact of using the SilverStripe Framework and CMS
|
||||
the impact of using the Silverstripe CMS
|
||||
to build online services. Since every website and app built with
|
||||
SilverStripe will be different, it can only provide starting points.
|
||||
Silverstripe CMS will be different, it can only provide starting points.
|
||||
|
||||
## Storage
|
||||
|
||||
The SilverStripe CMS does not provide any built-in mechanisms for users to submit personal data,
|
||||
The Silverstripe CMS does not provide any built-in mechanisms for users to submit personal data,
|
||||
or register a user account. CMS authors are created by administrators through the CMS UI.
|
||||
Since even the email address required to create such an account can be considered personal data,
|
||||
you’ll need to get consent from existing and new CMS authors,
|
||||
or cover this through other contractual arrangements with the individuals.
|
||||
|
||||
The primary location where SilverStripe can be configured to store personal data is the database.
|
||||
The primary location where Silverstripe CMS can be configured to store personal data is the database.
|
||||
Under different regulations, individuals can have the "right to be forgotten",
|
||||
and can ask website operators to remove their data.
|
||||
Most of the time, CMS administrators can action this without any technical help through
|
||||
@ -38,12 +38,12 @@ Note that CMS users aren’t versioned by default, so you can completely remove
|
||||
|
||||
## Transmission and Processing
|
||||
|
||||
SilverStripe recommends the use of encryption in transit (e.g. TLS/SSL),
|
||||
Silverstripe CMS recommends the use of encryption in transit (e.g. TLS/SSL),
|
||||
and at rest (e.g. database encryption), but does not enforce these.
|
||||
|
||||
## Cookies
|
||||
|
||||
SilverStripe will default to using PHP sessions for tracking logged-in users,
|
||||
Silverstripe CMS will default to using PHP sessions for tracking logged-in users,
|
||||
which uniquely link users to their device/browser through a session cookie.
|
||||
If the user chooses the "Remember me" feature on login,
|
||||
this unique link will persist across sessions.
|
||||
@ -52,7 +52,7 @@ See `SilverStripe\Security\Member::$auto_login_token_lifetime` for details.
|
||||
|
||||
## Login Attempts
|
||||
|
||||
SilverStripe is configured by default to record login attempts, in order to lock out users
|
||||
Silverstripe CMS is configured by default to record login attempts, in order to lock out users
|
||||
after a defined number of attempts, and hence limit the attack surface of the login process.
|
||||
This is predicated on tracking the IP address of the attempt, which can be considered personal data.
|
||||
IP addresses related to these attempts are stored indefinitely unless manually purged
|
||||
@ -62,11 +62,11 @@ See `SilverStripe\Security\Security::$login_recording` and
|
||||
|
||||
## Logging and Exceptions
|
||||
|
||||
SilverStripe provides a logging mechanism, which depending on your usage, configuration and hosting
|
||||
environment might store personal data outside of the SilverStripe database.
|
||||
Silverstripe CMS provides a logging mechanism, which depending on your usage, configuration and hosting
|
||||
environment might store personal data outside of the Silverstripe CMS database.
|
||||
The core system stores personal data for members, but does not log it.
|
||||
|
||||
As a PHP application, SilverStripe can also throw exceptions. These can include
|
||||
As a PHP application, Silverstripe CMS can also throw exceptions. These can include
|
||||
metadata such as method arguments and session data. If your application is configured
|
||||
to catch exceptions and log them (e.g. via a SaaS product), you could inadvertently store
|
||||
personal data in other systems. One mitigation is to create whitelists based on
|
||||
|
@ -6,7 +6,7 @@ icon: user-shield
|
||||
|
||||
# Security and User Authentication
|
||||
|
||||
This guide covers using and extending the user authentication in SilverStripe, permissions, user groups and roles, and
|
||||
This guide covers using and extending the user authentication in Silverstripe CMS, permissions, user groups and roles, and
|
||||
how to secure your code against malicious behaviors of both your users and hackers.
|
||||
|
||||
[CHILDREN Exclude=How_to]
|
||||
|
@ -1,20 +1,20 @@
|
||||
---
|
||||
title: Email
|
||||
summary: Send HTML and plain text email from your SilverStripe application.
|
||||
summary: Send HTML and plain text email from your Silverstripe CMS application.
|
||||
icon: envelope-open
|
||||
---
|
||||
|
||||
# Email
|
||||
|
||||
Creating and sending email in SilverStripe is done through the [Email](api:SilverStripe\Control\Email\Email) and [Mailer](api:SilverStripe\Control\Email\Mailer) classes. This document
|
||||
Creating and sending email in Silverstripe CMS is done through the [Email](api:SilverStripe\Control\Email\Email) and [Mailer](api:SilverStripe\Control\Email\Mailer) classes. This document
|
||||
covers how to create an `Email` instance, customise it with a HTML template, then send it through a custom `Mailer`.
|
||||
|
||||
## Configuration
|
||||
|
||||
SilverStripe provides an API over the top of the [SwiftMailer](http://swiftmailer.org/) PHP library which comes with an
|
||||
Silverstripe CMS provides an API over the top of the [SwiftMailer](http://swiftmailer.org/) PHP library which comes with an
|
||||
extensive list of "transports" for sending mail via different services.
|
||||
|
||||
Out of the box, SilverStripe will use the built-in PHP `mail()` command via the `Swift_MailTransport` class. If you'd
|
||||
Out of the box, Silverstripe CMS will use the built-in PHP `mail()` command via the `Swift_MailTransport` class. If you'd
|
||||
like to use a more robust transport to send mail you can swap out the transport used by the `Mailer` via config:
|
||||
|
||||
```yml
|
||||
@ -111,13 +111,13 @@ if ($email->send()) {
|
||||
```
|
||||
|
||||
[alert]
|
||||
As we've added a new template file (`MyCustomEmail`) make sure you clear the SilverStripe cache for your changes to
|
||||
As we've added a new template file (`MyCustomEmail`) make sure you clear the Silverstripe CMS cache for your changes to
|
||||
take affect.
|
||||
[/alert]
|
||||
|
||||
#### Custom plain templates
|
||||
|
||||
By default SilverStripe will generate a plain text representation of the email from the HTML body. However if you'd like
|
||||
By default Silverstripe CMS will generate a plain text representation of the email from the HTML body. However if you'd like
|
||||
to specify your own own plaintext version/template you can use `$email->setPlainTemplate()` to render a custom view of
|
||||
the plain email:
|
||||
|
||||
|
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: CSV Import
|
||||
summary: Load data into your Silverstripe database in bulk
|
||||
summary: Load data into your Silverstripe CMS database in bulk
|
||||
icon: upload
|
||||
---
|
||||
# Import CSV data
|
||||
@ -8,7 +8,7 @@ icon: upload
|
||||
## Introduction
|
||||
|
||||
CSV import can be easily achieved through PHP's built-in `fgetcsv()` method,
|
||||
but this method doesn't know anything about your datamodel. In SilverStripe,
|
||||
but this method doesn't know anything about your datamodel. In Silverstripe CMS,
|
||||
this can be handled through the a specialized CSV importer class that can
|
||||
be customised to fit your data.
|
||||
|
||||
|
@ -215,7 +215,7 @@ public function players()
|
||||
```
|
||||
|
||||
[warning]
|
||||
As we've added a new template (PlayersRss.ss) make sure you clear your SilverStripe cache.
|
||||
As we've added a new template (PlayersRss.ss) make sure you clear your Silverstripe CMS cache.
|
||||
[/warning]
|
||||
|
||||
|
||||
|
@ -1,6 +1,6 @@
|
||||
---
|
||||
summary: Integrate other web services within your application or make your SilverStripe data available.
|
||||
introduction: Integrate other web services within your application or make your SilverStripe data available.
|
||||
summary: Integrate other web services within your application or make your Silverstripe CMS data available.
|
||||
introduction: Integrate other web services within your application or make your Silverstripe CMS data available.
|
||||
title: Integration and Web Services
|
||||
---
|
||||
|
||||
|
@ -47,7 +47,7 @@ default site search, have a look at those extensions and modify as required.
|
||||
|
||||
### Fulltext Filter
|
||||
|
||||
SilverStripe provides a [FulltextFilter](api:SilverStripe\ORM\Filters\FulltextFilter) which you can use to perform custom fulltext searches on
|
||||
Silverstripe CMS provides a [FulltextFilter](api:SilverStripe\ORM\Filters\FulltextFilter) which you can use to perform custom fulltext searches on
|
||||
[DataList](api:SilverStripe\ORM\DataList)s.
|
||||
|
||||
Example DataObject:
|
||||
|
@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Search
|
||||
summary: Provide your users with advanced search functionality.
|
||||
introduction: Give users the ability to search your applications. Fulltext search for Page Content (and other attributes like "Title") can be easily added to SilverStripe.
|
||||
introduction: Give users the ability to search your applications. Fulltext search for Page Content (and other attributes like "Title") can be easily added to Silverstripe CMS.
|
||||
---
|
||||
|
||||
[CHILDREN]
|
@ -5,7 +5,7 @@ summary: Display templates and PHP code in different languages based on the pref
|
||||
|
||||
# i18n
|
||||
|
||||
The i18n class (short for "internationalization") in SilverStripe enables you to display templates and PHP code in
|
||||
The i18n class (short for "internationalization") in Silverstripe CMS enables you to display templates and PHP code in
|
||||
different languages based on your global settings and the preferences of your website users. This process is also known
|
||||
as l10n (short for "localization").
|
||||
|
||||
@ -43,9 +43,9 @@ these translations are available. See [unicode.org](http://unicode.org/cldr/data
|
||||
for a complete listing of available locales.
|
||||
|
||||
The `i18n` logic doesn't set the PHP locale via [setlocale()](http://php.net/setlocale).
|
||||
Localisation methods in SilverStripe rely on explicit locale settings as documented below.
|
||||
Localisation methods in Silverstripe CMS rely on explicit locale settings as documented below.
|
||||
If you rely on PHP's built-in localisation such as [strftime()](http://php.net/strftime),
|
||||
please only change locale information selectively. Setting `LC_ALL` or `LC_NUMERIC` will cause issues with SilverStripe
|
||||
please only change locale information selectively. Setting `LC_ALL` or `LC_NUMERIC` will cause issues with Silverstripe CMS
|
||||
operations such as decimal separators in database queries.
|
||||
|
||||
### Getting the locale
|
||||
@ -92,7 +92,7 @@ i18n::config()
|
||||
->set('time_format', 'HH:mm');
|
||||
```
|
||||
|
||||
Localization in SilverStripe uses PHP's [intl extension](http://php.net/intl).
|
||||
Localization in Silverstripe CMS uses PHP's [intl extension](http://php.net/intl).
|
||||
Formats for it's [IntlDateFormatter](http://php.net/manual/en/class.intldateformatter.php)
|
||||
are defined in [ICU format](http://www.icu-project.org/apiref/icu4c/classSimpleDateFormat.html#details),
|
||||
not PHP's built-in [date()](http://nz.php.net/manual/en/function.date.php).
|
||||
@ -105,7 +105,7 @@ client-side logic (for `DateField` polyfills and other readonly dates and times)
|
||||
|
||||
### Adding locales
|
||||
|
||||
SilverStripe now uses the php-intl extension. Before adding an extra locale, make sure the ICU library on your server supports it (see https://www.php.net/manual/en/resourcebundle.locales.php for more info).
|
||||
Silverstripe CMS now uses the php-intl extension. Before adding an extra locale, make sure the ICU library on your server supports it (see https://www.php.net/manual/en/resourcebundle.locales.php for more info).
|
||||
|
||||
They can be accessed via the `SilverStripe\i18n\Data\Intl\IntlLocales.locales` [config setting](/developer_guides/configuration).
|
||||
|
||||
@ -120,7 +120,7 @@ SilverStripe\i18n\Data\Intl\IntlLocales:
|
||||
|
||||
### i18n in URLs
|
||||
|
||||
By default, URLs for pages in SilverStripe (the `SiteTree->URLSegment` property)
|
||||
By default, URLs for pages in Silverstripe CMS (the `SiteTree->URLSegment` property)
|
||||
are automatically reduced to the allowed allowed subset of ASCII characters.
|
||||
If characters outside this subset are added, they are either removed or (if possible) "transliterated".
|
||||
This describes the process of converting from one character set to another
|
||||
@ -157,7 +157,7 @@ $field->setDateFormat('d.M.y'); // set a more specific date format (single digit
|
||||
|
||||
## Translating text
|
||||
|
||||
Adapting a module to make it localizable is easy with SilverStripe. You just need to avoid hardcoding strings that are
|
||||
Adapting a module to make it localizable is easy with Silverstripe CMS. You just need to avoid hardcoding strings that are
|
||||
language-dependent and use a translator function call instead.
|
||||
|
||||
|
||||
@ -354,7 +354,7 @@ Each module can have one language table per locale, stored by convention in the
|
||||
The translation is powered by [Zend_Translate](http://framework.zend.com/manual/current/en/modules/zend.i18n.translating.html),
|
||||
which supports different translation adapters, dealing with different storage formats.
|
||||
|
||||
By default, SilverStripe uses a YAML format which is loaded via the
|
||||
By default, Silverstripe CMS uses a YAML format which is loaded via the
|
||||
[symfony/translate](http://symfony.com/doc/current/translation.html) library.
|
||||
|
||||
Example: framework/lang/en.yml (extract)
|
||||
|
@ -72,7 +72,7 @@ Shortcodes represent an embeded asset within a block of HTML text. For instance,
|
||||
of a page with a shortcode image:
|
||||
|
||||
```html
|
||||
<p>Welcome to SilverStripe! This is the default homepage.</p>
|
||||
<p>Welcome to Silverstripe CMS! This is the default homepage.</p>
|
||||
<p>[image src="/assets/12824172.jpeg" id="27" width="400" height="400" class="leftAlone ss-htmleditorfield-file image" title="My Image"]</p>
|
||||
```
|
||||
|
||||
@ -131,7 +131,7 @@ As with storage, there are also different ways of loading the content (or proper
|
||||
|
||||
### Additional file types
|
||||
|
||||
SilverStripe has a pre-defined list of common file types. `File::getFileType` will return "unknown" for files outside that list.
|
||||
Silverstripe CMS has a pre-defined list of common file types. `File::getFileType` will return "unknown" for files outside that list.
|
||||
|
||||
You can add your own file extensions and its description with the following configuration.
|
||||
|
||||
|
@ -153,12 +153,12 @@ For usage on a website form, see [`FileField`](api:SilverStripe\Assets\FileField
|
||||
|
||||
#### Source images
|
||||
|
||||
Whenever SilverStripe performs a manipulation on an image, it saves the output
|
||||
Whenever Silverstripe CMS performs a manipulation on an image, it saves the output
|
||||
as a new image file, and applies compression during the process. If the source
|
||||
image already had lossy compression applied, this leads to the image being
|
||||
compressed twice over which can produce a poor result. To ensure the best
|
||||
quality output images, it's recommended to upload high quality source images
|
||||
(minimal or no compression) in to your asset store, and let SilverStripe take
|
||||
(minimal or no compression) in to your asset store, and let Silverstripe CMS take
|
||||
care of applying compression.
|
||||
|
||||
Very high resolution images may cause GD to crash (especially on shared hosting
|
||||
@ -167,7 +167,7 @@ around 2000px on the longest edge.
|
||||
|
||||
#### Forced resampling
|
||||
|
||||
Since the 'master' images in your asset store may have a large file size, SilverStripe
|
||||
Since the 'master' images in your asset store may have a large file size, Silverstripe CMS
|
||||
can apply compression to your images to save bandwidth - even if no other manipulation
|
||||
(such as a crop or resize) is taking place. In many cases this can result in a smaller
|
||||
overall file size, which may be appropriate for streaming to web users.
|
||||
|
@ -34,7 +34,7 @@ Access restrictions:
|
||||
|
||||
## Permission Model
|
||||
|
||||
Like all other objects in SilverStripe, permissions are generally controlled via `can*()` methods,
|
||||
Like all other objects in Silverstripe CMS, permissions are generally controlled via `can*()` methods,
|
||||
for example `canView()` (see [permissions](/developer_guides/security/permissions)).
|
||||
|
||||
The permission model defines the following actions:
|
||||
@ -49,7 +49,7 @@ The permission model defines the following actions:
|
||||
There's a few rules guiding their access, in descending order of priority:
|
||||
|
||||
* Published and unprotected files can be downloaded by anyone knowing the URL.
|
||||
They bypass any SilverStripe permission checks (served directly by the webserver).
|
||||
They bypass any Silverstripe CMS permission checks (served directly by the webserver).
|
||||
* Access can be restricted by custom `can*()` method implementations on `File`
|
||||
(through [extensions](/developer_guides/extending/extensions)).
|
||||
This logic can overrule any further restrictions below.
|
||||
@ -85,7 +85,7 @@ can still be downloaded through a public URL until a `write()` operation is trig
|
||||
|
||||
## Asset stores
|
||||
|
||||
Out of the box, SilverStripe comes with two asset stores: a public and a protected one.
|
||||
Out of the box, Silverstripe CMS comes with two asset stores: a public and a protected one.
|
||||
Most operations which act on assets work independently of this mechanism,
|
||||
without having to consider whether any specific file is protected or public, but can normally be
|
||||
instructed to favour private or protected stores in some cases.
|
||||
@ -226,7 +226,7 @@ a single entity for access control, so specific variants cannot be individually
|
||||
## How file access is protected
|
||||
|
||||
Filesystem paths can change depending if the file is protected or public,
|
||||
but its public URL stays the same. You just need to use SilverStripe's APIs to generate URLs to those files.
|
||||
but its public URL stays the same. You just need to use Silverstripe CMS's APIs to generate URLs to those files.
|
||||
Similarly, operations which modify files do not normally need to be told whether the file is protected or public
|
||||
either. This provides a consistent method for interacting with files.
|
||||
|
||||
@ -311,7 +311,7 @@ implementation of the `AssetStore` is `FlysystemAssetStore`.
|
||||
|
||||
### Configuring: Protected folder location
|
||||
|
||||
In the default SilverStripe configuration, protected assets are placed within the web root into the
|
||||
In the default Silverstripe CMS configuration, protected assets are placed within the web root into the
|
||||
`assets/.protected` folder, into which is also generated a `.htaccess` or `web.config` configured
|
||||
to deny any and all direct web requests.
|
||||
|
||||
|
@ -21,7 +21,7 @@ The assets module is composed of these major storage classes:
|
||||
* [api:SilverStripe\Assets\Storage\DBFile]: This is the DB field used by the File dataobject internally for
|
||||
storing references to physical files in the asset backend.
|
||||
* [api:SilverStripe\Assets\Flysystem\FlysystemAssetStore]: The default backend, provided by
|
||||
[Flysystem](https://flysystem.thephpleague.com/), which SilverStripe uses as an asset persistence layer.
|
||||
[Flysystem](https://flysystem.thephpleague.com/), which Silverstripe CMS uses as an asset persistence layer.
|
||||
* [api:SilverStripe\Assets\InterventionBackend]: Default image resizing mechanism, provided by
|
||||
[intervention image](http://image.intervention.io/).
|
||||
|
||||
@ -118,7 +118,7 @@ This corresponds to a file with the following properties:
|
||||
- Variant: FitWzYwLDYwXQ (corresponds to `Fit[60,60]`)
|
||||
|
||||
The URL for this file will not match the physical location on disk.
|
||||
It leaves out the `.protected/` folder, and leaves that to SilverStripe's integrated routing:
|
||||
It leaves out the `.protected/` folder, and leaves that to Silverstripe CMS's integrated routing:
|
||||
`http://www.example.com/assets/my-protected-folder/b63923d8d4/my-protected-file.jpg`.
|
||||
|
||||
For more information on how protected files are stored see the [file security](/developer_guides/files/file_security)
|
||||
|
@ -6,7 +6,7 @@ icon: compress-arrows-alt
|
||||
|
||||
# File migration
|
||||
|
||||
This section describes how to upgrade existing filesystems from earlier versions of SilverStripe.
|
||||
This section describes how to upgrade existing filesystems from earlier versions of Silverstripe CMS.
|
||||
|
||||
## Running migration
|
||||
|
||||
@ -90,7 +90,7 @@ It attempts to continue running to "complete" status even if it encounters error
|
||||
to ensure if everything went smoothly. Note that it's currently not possible to run specific subtasks via a queuedjob.
|
||||
|
||||
While you can run the job directly through the CMS, it'll usually be more constrained by PHP `max_execution_time` settings.
|
||||
Many platforms such as the New Zealand Government Common Web Platform or SilverStripe Platform
|
||||
Many platforms such as the New Zealand Government Common Web Platform or Silverstripe Cloud
|
||||
are configured to run jobs automatically without time limits
|
||||
([1](https://docs.platform.silverstripe.com/development/platform-yml-file/#cron-tasks),
|
||||
[2](https://www.cwp.govt.nz/developer-docs/en/2/working_with_projects/infrastructural_considerations/)).
|
||||
@ -100,8 +100,8 @@ when executing the file migration job.
|
||||
|
||||
## Migration of existing thumbnails
|
||||
|
||||
Thumbnails generated through SilverStripe's image manipulation layer can be created by authors
|
||||
resizing images in the rich text editor, through template or PHP code, or by SilverStripe's built-in CMS logic.
|
||||
Thumbnails generated through Silverstripe CMS's image manipulation layer can be created by authors
|
||||
resizing images in the rich text editor, through template or PHP code, or by Silverstripe CMS's built-in CMS logic.
|
||||
They are now called "variants", and are placed in a different folder structure. In order to avoid re-generating those thumbnails,
|
||||
and cluttering up your asset store with orphaned files, the task will move them to the new location by default.
|
||||
|
||||
@ -158,10 +158,10 @@ SilverStripe\Assets\Flysystem\FlysystemAssetStore:
|
||||
|
||||
## Review draft/protected files served through PHP
|
||||
|
||||
In SilverStripe 3.x, files were always public. This allowed them to be served
|
||||
In Silverstripe CMS 3.x, files were always public. This allowed them to be served
|
||||
directly by your webserver without performing any checks in PHP logic (e.g. permissions).
|
||||
|
||||
In SilverStripe 4.x, this behaviour is retained for public and unprotected files.
|
||||
In Silverstripe CMS 4.x, this behaviour is retained for public and unprotected files.
|
||||
If files are in draft, or are protected by additional permission checks,
|
||||
they are now served via PHP. Although those additional requests are fairly lightweight,
|
||||
you need to take them into account in your capacity planning (e.g. max workers configuration).
|
||||
@ -210,38 +210,38 @@ Use the following estimates to decide how you will run your file migration:
|
||||
| < 10000 | Command Line | 10000 seconds | 950 MB |
|
||||
| 10000+ | Command Line or contact support | n/a | n/a |
|
||||
|
||||
Your exact experience will vary based on your host server, the size of your files and other conditions. If your site is hosted on a managed environement (e.g.: [Common Web Platform](https://www.cwp.govt.nz/service-desk) or [SilverStripe Platform](https://docs.platform.silverstripe.com/support/)), you may not have access to the command line to manually run the migration task. Contact your hosting provider's helpdesk if that's your case.
|
||||
Your exact experience will vary based on your host server, the size of your files and other conditions. If your site is hosted on a managed environement (e.g.: [Common Web Platform](https://www.cwp.govt.nz/service-desk) or [Silverstripe Cloud](https://docs.platform.silverstripe.com/support/)), you may not have access to the command line to manually run the migration task. Contact your hosting provider's helpdesk if that's your case.
|
||||
|
||||
|
||||
## Natural path vs Hash Path
|
||||
|
||||
Two types of paths are used by SilverStripe CMS when serving files:
|
||||
Two types of paths are used by Silverstripe CMS when serving files:
|
||||
* Natural paths and
|
||||
* Hash paths.
|
||||
|
||||
Natural paths will match the path displayed in SilverStripe's asset management section (e.g.: `assets/Folder/form.pdf`). Hash paths will include a partial hash as directory name (e.g.: `assets/Folder/282318025b/form.pdf`). The hash is generated by computing the sha1 hash of the provided file and keeping the first ten characters.
|
||||
Natural paths will match the path displayed in Silverstripe CMS's asset management section (e.g.: `assets/Folder/form.pdf`). Hash paths will include a partial hash as directory name (e.g.: `assets/Folder/282318025b/form.pdf`). The hash is generated by computing the sha1 hash of the provided file and keeping the first ten characters.
|
||||
|
||||
The hash path has the advantage of being unique for every version of the file your users might upload. This allows multiple versions of the same file to co-exist, enabling features like [file archives](04_File_Storage#archived). This is why hash path is the default file format for the protected file store.
|
||||
|
||||
The Natural path has the advantage of being easier to understand and permanent. When a newer version of a file is published to a natural path, it will be accessible at the same URL as the previous version. This is why natural path is the default file format for the public file store.
|
||||
|
||||
[Learn more about SilverStripe File Storage](04_File_Storage)
|
||||
[Learn more about Silverstripe CMS File Storage](04_File_Storage)
|
||||
|
||||
## Migration from SilverStripe 3 to Silverstripe 4.4 or later
|
||||
## Migration from Silverstripe CMS 3 to Silverstripe CMS 4.4 or later
|
||||
|
||||
While the SilverStripe 3 file paths may look similar to the natural paths in SilverStripe 4.4, the database entries for each file have to be normalised to conform to the new SilverStripe 4 structure. File variants (e.g. image thumbnails) are stored differently in SilverStripe 4. They will automatically be moved to their new location.
|
||||
While the Silverstripe CMS 3 file paths may look similar to the natural paths in Silverstripe CMS 4.4, the database entries for each file have to be normalised to conform to the new Silverstripe CMS 4 structure. File variants (e.g. image thumbnails) are stored differently in Silverstripe CMS 4. They will automatically be moved to their new location.
|
||||
|
||||
SilverStripe 3 did not support draft files which means that all migrated SilverStripe 3 files will automatically be published by the File Migration Task.
|
||||
Silverstripe CMS 3 did not support draft files which means that all migrated Silverstripe CMS 3 files will automatically be published by the File Migration Task.
|
||||
|
||||
File names can not contain "double underscores" in SilverStripe 4 (`__`) because those characters are used to indicate a "file variant". SilverStripe 3 files not conforming to this rule will automatically be renamed by the file migration task to remove extra underscores.
|
||||
File names can not contain "double underscores" in Silverstripe CMS 4 (`__`) because those characters are used to indicate a "file variant". Silverstripe CMS 3 files not conforming to this rule will automatically be renamed by the file migration task to remove extra underscores.
|
||||
|
||||
### Will old URLs to SilverStripe 3 files still resolve?
|
||||
### Will old URLs to Silverstripe CMS 3 files still resolve?
|
||||
|
||||
In most cases, the SilverStripe 3 file path will be identical to the public path of the file in SilverStripe 4. Links to SilverStripe 3 file variants (e.g. cropped images) will automatically be redirected to their new location.
|
||||
In most cases, the Silverstripe CMS 3 file path will be identical to the public path of the file in Silverstripe CMS 4. Links to Silverstripe CMS 3 file variants (e.g. cropped images) will automatically be redirected to their new location.
|
||||
|
||||
### What about file references in `HTMLText` database fields?
|
||||
|
||||
The shortcode format in SilverStripe 4 has changed from SilverStripe 3. This means that when CMS editors try to edit existing content and alter image or file links, the reference to the file will not work.
|
||||
The shortcode format in Silverstripe CMS 4 has changed from Silverstripe CMS 3. This means that when CMS editors try to edit existing content and alter image or file links, the reference to the file will not work.
|
||||
|
||||
After running the file migration, you can run the short code migration task to update your existing HTML content in your database:
|
||||
|
||||
@ -249,31 +249,31 @@ After running the file migration, you can run the short code migration task to u
|
||||
sake dev/tasks/TagsToShortcodeTask
|
||||
```
|
||||
|
||||
This will rewrite your existing shortcodes to the newer format SilverStripe 4 expects as well as convert `img` and `a` tags to use shortcodes.
|
||||
This will rewrite your existing shortcodes to the newer format Silverstripe CMS 4 expects as well as convert `img` and `a` tags to use shortcodes.
|
||||
|
||||
### Migrating from SilverStripe 3.2 (or below) to SilverStripe 4.4
|
||||
### Migrating from Silverstripe CMS 3.2 (or below) to Silverstripe CMS 4.4
|
||||
|
||||
The format for image variants was changed in SilverStripe 3.3. In SilverStripe 3.2 and below variants would be included in the file name with a dash:
|
||||
* `Uploads/_resampled/FitWzQwLDMwXQ-image.jpg` in SilverStripe 3.2 and below
|
||||
* `Uploads/_resampled/FitWzQwLDMwXQ/image.jpg` in SilverStripe 3.3 and above
|
||||
The format for image variants was changed in Silverstripe CMS 3.3. In Silverstripe CMS 3.2 and below variants would be included in the file name with a dash:
|
||||
* `Uploads/_resampled/FitWzQwLDMwXQ-image.jpg` in Silverstripe CMS 3.2 and below
|
||||
* `Uploads/_resampled/FitWzQwLDMwXQ/image.jpg` in Silverstripe CMS 3.3 and above
|
||||
|
||||
The file migration task didn't account for this nuance until the SilverStripe 4.4.4 release. If you ran the file migration task using a prior version, your SilverStripe 3.2 thumbnails might not have been migrated, or their paths might have been appended as variants. e.g.: `FitWzQwLDMwXQ-image__Uploads__resampled.jpg`
|
||||
The file migration task didn't account for this nuance until the Silverstripe CMS 4.4.4 release. If you ran the file migration task using a prior version, your Silverstripe CMS 3.2 thumbnails might not have been migrated, or their paths might have been appended as variants. e.g.: `FitWzQwLDMwXQ-image__Uploads__resampled.jpg`
|
||||
|
||||
Those variants will need to be regenerated. Thumbnails generated through templates or code will automatically be regenerated on the next uncached request to SilverStripe. Thumbnails embedded in HTML fields will be regenerated when the page is republished. Variants that were improperly renamed must be removed manually.
|
||||
Those variants will need to be regenerated. Thumbnails generated through templates or code will automatically be regenerated on the next uncached request to Silverstripe CMS. Thumbnails embedded in HTML fields will be regenerated when the page is republished. Variants that were improperly renamed must be removed manually.
|
||||
|
||||
If you are running SilverStripe 4.4.4 or greater, SilverStripe 3.2 variants will be migrated normally.
|
||||
If you are running Silverstripe CMS 4.4.4 or greater, Silverstripe CMS 3.2 variants will be migrated normally.
|
||||
|
||||
## Migrating from SilverStripe 4.3 or below to SilverStripe 4.4 or above
|
||||
## Migrating from Silverstripe CMS 4.3 or below to Silverstripe CMS 4.4 or above
|
||||
|
||||
Silverstripe 4.0 to 4.3 were using hash paths for the public file store as well as the protected file store. This meant that every time a new version of a file was published, it would be served under a different URL.
|
||||
|
||||
SilverStripe 4.4 and later default to using natural paths for public store files. After upgrading to SilverStripe 4.4 or above, you can run the file migration task to normalise your existing files.
|
||||
Silverstripe CMS 4.4 and later default to using natural paths for public store files. After upgrading to Silverstripe CMS 4.4 or above, you can run the file migration task to normalise your existing files.
|
||||
|
||||
This will take all existing files under a hash path and move them to their natural path.
|
||||
|
||||
### Do I need to re-migrate my files?
|
||||
|
||||
No, you do not need to run the file migration task when upgrading to SilverStripe 4.4 or later.
|
||||
No, you do not need to run the file migration task when upgrading to Silverstripe CMS 4.4 or later.
|
||||
|
||||
Your existing files will still resolve. Old hash paths will be redirected to the latest version of the file. As newer versions of existing files are published, they will be moved to their natural path.
|
||||
|
||||
@ -281,11 +281,11 @@ You can choose to run the migration task at any point.
|
||||
|
||||
### What if I’m using `legacy_filenames`?
|
||||
|
||||
SilverStripe 4.0 to 4.3 allowed you to enable a `legacy_filenames` mode. This would be equivalent to using natural paths for both the public store and the protected store.
|
||||
Silverstripe CMS 4.0 to 4.3 allowed you to enable a `legacy_filenames` mode. This would be equivalent to using natural paths for both the public store and the protected store.
|
||||
|
||||
With the introduction of natural paths for the public store, the primary reason for `legacy_filenames` mode is no longer relevant. `legacy_filenames` mode is now considered deprecated, however leaving it enabled will not have any impact on your project – it will simply be ignored.
|
||||
|
||||
After upgrading to SilverStripe 4.4 or later, you should run the file migration task to normalise your protected files. This will move your protected files to their equivalent hash path.
|
||||
After upgrading to Silverstripe CMS 4.4 or later, you should run the file migration task to normalise your protected files. This will move your protected files to their equivalent hash path.
|
||||
|
||||
### What if I want to keep using hash paths for my public files?
|
||||
|
||||
|
@ -10,7 +10,7 @@ icon: folder-open
|
||||
## Introduction
|
||||
|
||||
File management and abstraction is provided by the [silverstripe/assets](https://github.com/silverstripe/silverstripe-assets).
|
||||
This provides the basis for the storage of all non-static files and resources usable by a SilverStripe web application.
|
||||
This provides the basis for the storage of all non-static files and resources usable by a Silverstripe CMS web application.
|
||||
|
||||
By default the [api:SilverStripe\Assets\File] has these characteristics:
|
||||
|
||||
|
@ -7,12 +7,12 @@ icon: sitemap
|
||||
|
||||
## Introduction
|
||||
|
||||
A lot can be achieved in SilverStripe by adding properties and form fields
|
||||
A lot can be achieved in Silverstripe CMS by adding properties and form fields
|
||||
to your own page types (via [SiteTree::getCMSFields()](api:SilverStripe\CMS\Model\SiteTree::getCMSFields())), as well as creating
|
||||
your own data management interfaces through [ModelAdmin](api:SilverStripe\Admin\ModelAdmin). But sometimes
|
||||
you'll want to go deeper and tailor the underlying interface to your needs as well.
|
||||
For example, to build a personalized CMS dashboard, or content "slots" where authors
|
||||
can drag their content into. At its core, SilverStripe is a web application
|
||||
can drag their content into. At its core, Silverstripe CMS is a web application
|
||||
built on open standards and common libraries, so lots of the techniques should
|
||||
feel familiar to you. This is just a quick run down to get you started
|
||||
with some special conventions.
|
||||
@ -60,13 +60,13 @@ coding conventions.
|
||||
|
||||
A pattern library is a collection of user interface design elements, this helps developers and designers collaborate and to provide a quick preview of elements as they were intended without the need to build an entire interface to see it.
|
||||
Components built in React and used by the CMS are actively being added to the pattern library.
|
||||
The pattern library can be used to preview React components without including them in the SilverStripe CMS.
|
||||
The pattern library can be used to preview React components without including them in the Silverstripe CMS.
|
||||
|
||||
### Viewing the latest pattern library
|
||||
|
||||
The easiest way to access the pattern library is to view it online. The pattern library for the latest SilverStripe 4 development branch is automatically built and deployed. Note that this may include new components that are not yet available in a stable release.
|
||||
The easiest way to access the pattern library is to view it online. The pattern library for the latest Silverstripe CMS 4 development branch is automatically built and deployed. Note that this may include new components that are not yet available in a stable release.
|
||||
|
||||
[Browse the SilverStripe pattern library online](https://silverstripe.github.io/silverstripe-pattern-lib/).
|
||||
[Browse the Silverstripe CMS pattern library online](https://silverstripe.github.io/silverstripe-pattern-lib/).
|
||||
|
||||
### Running the pattern library
|
||||
|
||||
@ -74,7 +74,7 @@ If you're developing a new React component, running the pattern library locally
|
||||
|
||||
The pattern library is built from the `silverstripe/admin` module, but it also requires `silverstripe/asset-admin`, `silversrtipe/cms` and `silverstripe/campaign-admin`.
|
||||
|
||||
To run the pattern library locally, you'll need a SilverStripe project based on `silverstripe/recipe-cms` and `yarn` installed locally. The pattern library requires the JS source files so you'll need to use the `--prefer-source` flag when installing your dependencies with Composer.
|
||||
To run the pattern library locally, you'll need a Silverstripe CMS project based on `silverstripe/recipe-cms` and `yarn` installed locally. The pattern library requires the JS source files so you'll need to use the `--prefer-source` flag when installing your dependencies with Composer.
|
||||
|
||||
```bash
|
||||
composer install --prefer-source
|
||||
@ -88,7 +88,7 @@ The pattern library will be available at [http://localhost:6006](http://localhos
|
||||
|
||||
If you want to build a static version of the pattern library, you can replace `yarn pattern-lib` with `yarn build-storybook`. This will output the pattern library files to a `storybook-static` folder.
|
||||
|
||||
The SilverStripe pattern library is built using the [StoryBook JS library](https://storybook.js.org/). You can read the StoryBook documentation to learn about more advanced features and customisation options.
|
||||
The Silverstripe CMS pattern library is built using the [StoryBook JS library](https://storybook.js.org/). You can read the StoryBook documentation to learn about more advanced features and customisation options.
|
||||
|
||||
## The Admin URL
|
||||
|
||||
@ -183,7 +183,7 @@ Refer to [Layout reference](/developer_guides/customising_the_admin_interface/cm
|
||||
|
||||
## Forms
|
||||
|
||||
SilverStripe constructs forms and its fields within PHP,
|
||||
Silverstripe CMS constructs forms and its fields within PHP,
|
||||
mainly through the [getCMSFields()](api:SilverStripe\ORM\DataObject::getCMSFields()) method.
|
||||
This in turn means that the CMS loads these forms as HTML via Ajax calls,
|
||||
e.g. after saving a record (which requires a form refresh), or switching the section in the CMS.
|
||||
@ -253,7 +253,7 @@ correctly configured form.
|
||||
__Deprecated:__
|
||||
The following documentation regarding Entwine applies to legacy code only.
|
||||
If you're developing new functionality in React powered sections please refer to
|
||||
[ReactJS in SilverStripe](./How_Tos/Extend_CMS_Interface.md#reactjs-in-silverstripe).
|
||||
[ReactJS in Silverstripe CMS](./How_Tos/Extend_CMS_Interface.md#reactjs-in-silverstripe).
|
||||
|
||||
[jQuery.entwine](https://github.com/hafriedlander/jquery.entwine) is a thirdparty library
|
||||
which allows us to attach behaviour to DOM elements in a flexible and structured mannger.
|
||||
@ -302,10 +302,10 @@ so as a developer just declare your dependencies through the [Requirements](api:
|
||||
|
||||
## Client-side routing
|
||||
|
||||
SilverStripe uses the HTML5 browser history to modify the URL without a complete
|
||||
Silverstripe CMS uses the HTML5 browser history to modify the URL without a complete
|
||||
window refresh. We us the below systems in combination to achieve this:
|
||||
* [Page.js](https://github.com/visionmedia/page.js) routing library is used for most
|
||||
cms sections, which provides additional SilverStripe specific functionality via the
|
||||
cms sections, which provides additional Silverstripe CMS specific functionality via the
|
||||
`vendor/silverstripe/admin/client/src/lib/Router.js` wrapper.
|
||||
The router is available on `window.ss.router` and provides the same API as
|
||||
described in the
|
||||
@ -591,7 +591,7 @@ To avoid repetition, we've written some helpers for various use cases:
|
||||
|
||||
## Buttons
|
||||
|
||||
SilverStripe automatically applies a [jQuery UI button style](http://jqueryui.com/demos/button/)
|
||||
Silverstripe CMS automatically applies a [jQuery UI button style](http://jqueryui.com/demos/button/)
|
||||
to all elements with the class `.ss-ui-button`. We've extended the jQuery UI widget a bit
|
||||
to support defining icons via HTML5 data attributes (see `ssui.core.js`).
|
||||
These icon identifiers relate to icon files in `vendor/silverstripe/framework/admin/images/sprites/src/btn-icons`,
|
||||
|
@ -8,7 +8,7 @@ summary: Add interactivity enhancements to the admin with Javascript
|
||||
__Deprecated:__
|
||||
The following documentation regarding JavaScript layouts applies to legacy code only.
|
||||
If you're developing new functionality in React powered sections please refer to
|
||||
[ReactJS in SilverStripe](./how_tos/extend_cms_interface/#react-rendered-ui).
|
||||
[ReactJS in Silverstripe CMS](./how_tos/extend_cms_interface/#react-rendered-ui).
|
||||
|
||||
The CMS markup is structured into "panels", which are the base units containing interface components (or other panels),
|
||||
as declared by the class `cms-panel`. Panels can be made collapsible, and get the ability to be resized and aligned with
|
||||
|
@ -10,7 +10,7 @@ summary: How content previews work in the CMS
|
||||
__Deprecated:__
|
||||
The following documentation regarding JavaScript layouts and Entwine applies to legacy code only.
|
||||
If you're developing new functionality in React powered sections please refer to
|
||||
[ReactJS in SilverStripe](./How_Tos/Extend_CMS_Interface.md#reactjs-in-silverstripe).
|
||||
[ReactJS in Silverstripe CMS](./How_Tos/Extend_CMS_Interface.md#reactjs-in-silverstripe).
|
||||
|
||||
With the addition of side-by-side editing, the preview has the ability to appear
|
||||
within the CMS window when editing content in the _Pages_ section of the CMS.
|
||||
|
@ -6,7 +6,7 @@ icon: text-width
|
||||
|
||||
# WYSIWYG Styles
|
||||
|
||||
SilverStripe lets you customise the style of content in the CMS. This is done by setting up a CSS file called
|
||||
Silverstripe CMS lets you customise the style of content in the CMS. This is done by setting up a CSS file called
|
||||
`editor.css` in either your theme or in your `app/` folder. This is set through yaml config:
|
||||
|
||||
```yaml
|
||||
|
@ -1,12 +1,12 @@
|
||||
---
|
||||
title: Javascript Development
|
||||
summary: Advanced documentation about writing and customizing javascript within SilverStripe.
|
||||
summary: Advanced documentation about writing and customizing javascript within Silverstripe CMS.
|
||||
iconBrand: js
|
||||
---
|
||||
|
||||
# Javascript Development
|
||||
|
||||
The following document is an advanced guide on building rich javascript interactions within the SilverStripe CMS and
|
||||
The following document is an advanced guide on building rich javascript interactions within the Silverstripe CMS and
|
||||
a list of our best practices for contributing and modifying the core javascript framework.
|
||||
|
||||
## ES6 and build tools
|
||||
@ -19,7 +19,7 @@ in a browser. This transpiling can be done using a variety of toolchains, but th
|
||||
environment as part of your workflow.
|
||||
|
||||
As stated above, there are many ways to solve the problem of transpiling. The toolchain
|
||||
we use in core SilverStripe modules includes:
|
||||
we use in core Silverstripe CMS modules includes:
|
||||
* [Babel](http://babeljs.io) (ES6 transpiler)
|
||||
* [Webpack](http://webpack.js.org) (Module bundler)
|
||||
|
||||
@ -31,10 +31,10 @@ If you're developing new functionality in React powered sections please refer to
|
||||
## jQuery, jQuery UI and jQuery.entwine: Our libraries of choice
|
||||
|
||||
We predominantly use [jQuery](http://jquery.com) as our abstraction library for DOM related programming, within the
|
||||
SilverStripe CMS and certain framework aspects.
|
||||
Silverstripe CMS and certain framework aspects.
|
||||
|
||||
For richer interactions such as drag'n'drop, and more complicated interface elements like tabs or accordions,
|
||||
SilverStripe CMS uses [jQuery UI](http://ui.jquery.com) on top of jQuery.
|
||||
Silverstripe CMS uses [jQuery UI](http://ui.jquery.com) on top of jQuery.
|
||||
|
||||
For any custom code developed with jQuery, you have four choices to structure it: Custom jQuery Code, a jQuery Plugin, a
|
||||
jQuery UI Widget, or a `jQuery.entwine` behaviour. We'll detail below where each solution is appropriate.
|
||||
@ -258,7 +258,7 @@ Global properties are evil. They are accessible by other scripts, might be overw
|
||||
```
|
||||
|
||||
You can run `[jQuery.noConflict()](http://docs.jquery.com/Core/jQuery.noConflict)` to avoid namespace clashes.
|
||||
NoConflict mode is enabled by default in the SilverStripe CMS javascript.
|
||||
NoConflict mode is enabled by default in the Silverstripe CMS javascript.
|
||||
|
||||
### Initialize at document.ready
|
||||
|
||||
@ -347,7 +347,7 @@ See [interactive example on jsbin.com](http://jsbin.com/opuva)
|
||||
|
||||
You can also use the [jQuery.metadata Plugin](http://docs.jquery.com/Plugins/Metadata/metadata) to serialize data into
|
||||
properties of DOM elements. This is useful if you want to encode element-specific data in markup, for example when
|
||||
rendering a form element through the SilverStripe templating engine.
|
||||
rendering a form element through the Silverstripe CMS templating engine.
|
||||
|
||||
Example: Restricted numeric value field
|
||||
|
||||
@ -373,14 +373,14 @@ See [interactive example on jsbin.com](http://jsbin.com/axafa)
|
||||
|
||||
Ajax responses will sometimes need to update existing DOM elements, for example refresh a set of search results.
|
||||
Returning plain HTML is generally a good default behaviour, as it allows you to keep template rendering in one place (in
|
||||
SilverStripe PHP code), and is easy to deal with in JavaScript.
|
||||
Silverstripe CMS PHP code), and is easy to deal with in JavaScript.
|
||||
|
||||
If you need to process or inspect returned data, consider extracting it from the loaded HTML instead (through id/class
|
||||
attributes, or the jQuery.metadata plugin). For returning status messages, please use the HTTP status-codes.
|
||||
|
||||
Only return evaluated JavaScript snippets if unavoidable. Most of the time you can just pass data around, and let the
|
||||
clientside react to changes appropriately without telling it directly through JavaScript in AJAX responses. Don't use
|
||||
the [Form](api:SilverStripe\Forms\Form) SilverStripe class, which is built solely around
|
||||
the [Form](api:SilverStripe\Forms\Form) Silverstripe CMS class, which is built solely around
|
||||
this inflexible concept.
|
||||
|
||||
Example: Autocomplete input field loading page matches through AJAX
|
||||
@ -460,7 +460,7 @@ $('.autocomplete input').on('change', function() {
|
||||
|
||||
Although they are the minority of cases, there are times when a simple HTML fragment isn't enough. For example, if you
|
||||
have server side code that needs to trigger the update of a couple of elements in the CMS left-hand tree, it would be
|
||||
inefficient to send back the HTML of entire tree. SilverStripe can serialize to and from JSON (see the [Convert](api:SilverStripe\Core\Convert) class), and jQuery deals very well with it through
|
||||
inefficient to send back the HTML of entire tree. Silverstripe CMS can serialize to and from JSON (see the [Convert](api:SilverStripe\Core\Convert) class), and jQuery deals very well with it through
|
||||
[jQuery.getJSON()](http://docs.jquery.com/Ajax/jQuery.getJSON#urldatacallback), as long as the HTTP content-type is
|
||||
properly set.
|
||||
|
||||
@ -526,7 +526,7 @@ Documentation in JavaScript usually resembles the JavaDoc standard, although the
|
||||
flexibility of the language it can be hard to generate automated documentation, particularly with the predominant usage
|
||||
of closure constructs in jQuery and jQuery.entwine.
|
||||
|
||||
To generate documentation for SilverStripe code, use [JSDoc toolkit](http://code.google.com/p/jsdoc-toolkit/) (see
|
||||
To generate documentation for Silverstripe CMS code, use [JSDoc toolkit](http://code.google.com/p/jsdoc-toolkit/) (see
|
||||
[reference of supported tags](http://code.google.com/p/jsdoc-toolkit/wiki/TagReference)). For more class-oriented
|
||||
JavaScript, take a look at the [jsdoc cookbook](http://code.google.com/p/jsdoc-toolkit/wiki/CookBook). The `@lends`
|
||||
and `@borrows` properties are particularly useful for documenting jQuery-style code.
|
||||
|
@ -19,7 +19,7 @@ There are some several members of this ecosystem that all work together to provi
|
||||
All of these pillars of the frontend application can be customised, giving you more control over how the admin interface looks, feels, and behaves.
|
||||
|
||||
[alert]
|
||||
These technologies underpin the future of SilverStripe CMS development, but their current implementation is
|
||||
These technologies underpin the future of Silverstripe CMS development, but their current implementation is
|
||||
_experimental_. Our APIs are not expected to change drastically between releases, but they are excluded from
|
||||
our [semantic versioning](https://semver.org) commitments for the time being. Any breaking changes will be
|
||||
clearly signalled in release notes.
|
||||
@ -138,7 +138,7 @@ The above query is almost self-descriptive. It gets a user by ID, returns his or
|
||||
}
|
||||
```
|
||||
|
||||
On its own, GraphQL offers nothing functional, as it's just a query language. You still need a service that will invoke queries and map their results to UI. For that, SilverStripe uses an implementation of [Apollo](http://dev.apollodata.com/) that works with React.
|
||||
On its own, GraphQL offers nothing functional, as it's just a query language. You still need a service that will invoke queries and map their results to UI. For that, Silverstripe CMS uses an implementation of [Apollo](http://dev.apollodata.com/) that works with React.
|
||||
|
||||
## For more information
|
||||
|
||||
@ -151,7 +151,7 @@ documentation available all over the web. We recommend:
|
||||
|
||||
# The Injector API
|
||||
|
||||
Much like SilverStripe's [Injector API](../../extending/injector) in PHP,
|
||||
Much like Silverstripe CMS's [Injector API](../../extending/injector) in PHP,
|
||||
the client-side framework has its own implementation of dependency injection
|
||||
known as `Injector`. Using Injector, you can register new services, and
|
||||
transform existing services.
|
||||
@ -809,7 +809,7 @@ You could manipulate the action called by the originalReducer, there isn't an ex
|
||||
|
||||
One of the strengths of GraphQL is that it allows us to declaratively state exactly what data a given component needs to function. Because GraphQL queries and mutations are considered primary concerns of a component, they are not abstracted away somewhere in peripheral asynchronous functions. Rather, they are co-located with the component definition itself.
|
||||
|
||||
The downside of this is that, because queries are defined statically at compile time, they don't adapt well to the extension patterns that are inherent to SilverStripe projects. For instance, a query for a Member record may include fields for `FirstName` and `Email`, but if you have customised that class via extensions, and would like the component using that query to display your custom fields, your only option is to override the entire query and the component with a custom implementation. In backend code, this would be tantamount to replacing the entire `Member` class and `SecurityAdmin` section just because you had a new field. You would never do that, right? It's an over-aggressive hack! We need APIs that make extension easy.
|
||||
The downside of this is that, because queries are defined statically at compile time, they don't adapt well to the extension patterns that are inherent to Silverstripe CMS projects. For instance, a query for a Member record may include fields for `FirstName` and `Email`, but if you have customised that class via extensions, and would like the component using that query to display your custom fields, your only option is to override the entire query and the component with a custom implementation. In backend code, this would be tantamount to replacing the entire `Member` class and `SecurityAdmin` section just because you had a new field. You would never do that, right? It's an over-aggressive hack! We need APIs that make extension easy.
|
||||
|
||||
To that end, the `Injector` library provides a container for abstract representations of GraphQL queries and mutations. You can register and transform them as you do components and reducers. They exist merely as abstract concepts until `Injector` loads, at which time all transformations are applied, and each registered query and mutation is composed and attached to their assigned components.
|
||||
|
||||
|
@ -76,7 +76,7 @@ public function getCMSActions()
|
||||
__Deprecated:__
|
||||
The following documentation regarding jQuery, jQueryUI and Entwine applies to legacy code only.
|
||||
If you're developing new functionality in React powered sections please refer to
|
||||
[ReactJS in SilverStripe](./extend_cms_interface.md#reactjs-in-silverstripe).
|
||||
[ReactJS in Silverstripe CMS](./extend_cms_interface.md#reactjs-in-silverstripe).
|
||||
|
||||
As with the *Save* and *Save & publish* buttons, you might want to add some scripted reactions to user actions on the
|
||||
frontend. You can affect the state of the button through the jQuery UI calls.
|
||||
|
@ -7,7 +7,7 @@ summary: Make custom changes to the left hand menu in the CMS
|
||||
## Adding an administration panel
|
||||
|
||||
Every time you add a new extension of the [LeftAndMain](api:SilverStripe\Admin\LeftAndMain) class to the CMS,
|
||||
SilverStripe will automatically create a new [CMSMenuItem](api:SilverStripe\Admin\CMSMenuItem) for it
|
||||
Silverstripe CMS will automatically create a new [CMSMenuItem](api:SilverStripe\Admin\CMSMenuItem) for it
|
||||
|
||||
The most popular extension of LeftAndMain is a [ModelAdmin](api:SilverStripe\Admin\ModelAdmin) class, so
|
||||
for a more detailed introduction to creating new `ModelAdmin` interfaces, read
|
||||
@ -20,7 +20,7 @@ provide a custom title and icon.
|
||||
|
||||
### Defining a Custom Icon
|
||||
|
||||
First we'll need a custom icon. For this purpose SilverStripe uses 16x16
|
||||
First we'll need a custom icon. For this purpose Silverstripe CMS uses 16x16
|
||||
black-and-transparent PNG graphics. In this case we'll place the icon in
|
||||
`app/images`, but you are free to use any location.
|
||||
|
||||
|
@ -6,7 +6,7 @@ title: Customise the CMS pages list
|
||||
The pages "list" view in the CMS is a powerful alternative to visualizing
|
||||
your site's content, and can be better suited than a tree for large flat
|
||||
hierarchies. A good example would be a collection of news articles,
|
||||
all contained under a "holder" page type, a quite common pattern in SilverStripe.
|
||||
all contained under a "holder" page type, a quite common pattern in Silverstripe CMS.
|
||||
|
||||
The "list" view allows you to paginate through a large number of records,
|
||||
as well as sort and filter them in a way that would be hard to achieve in a tree structure.
|
||||
|
@ -23,7 +23,7 @@ but in the CMS usually is a [SiteTree](api:SilverStripe\CMS\Model\SiteTree) obje
|
||||
A tree node in CMS could be rendered with lot of extra information but a node title, such as a
|
||||
link that wraps around the node title, a node's id which is given as id attribute of the node
|
||||
<li> tag, a extra checkbox beside the tree title, tree icon class or extra <span>
|
||||
tags showing the node status, etc. SilverStripe tree node will be typically rendered into html
|
||||
tags showing the node status, etc. Silverstripe CMS tree node will be typically rendered into html
|
||||
code like this:
|
||||
|
||||
|
||||
|
@ -28,14 +28,14 @@ Modules may come with their own additional reports.
|
||||
|
||||
## Creating custom reports
|
||||
|
||||
Custom reports can be created quickly and easily. A general knowledge of SilverStripe's
|
||||
Custom reports can be created quickly and easily. A general knowledge of Silverstripe CMS's
|
||||
[datamodel and ORM](../../model/data_model_and_orm) is useful before creating a custom report.
|
||||
|
||||
Inside the *app/code* folder create a file called *CustomSideReport.php*. Inside this file we can add our site reports.
|
||||
|
||||
The following example will create a report to list every page on the current site.
|
||||
|
||||
###CustomSideReport.php
|
||||
**CustomSideReport.php**
|
||||
|
||||
```php
|
||||
use SilverStripe\Reports\Report;
|
||||
|
@ -5,11 +5,11 @@ introduction: The Admin interface can be extended to provide additional function
|
||||
iconBrand: react
|
||||
---
|
||||
|
||||
The Admin interface is bundled within the SilverStripe Framework but is most commonly used in conjunction with the `cms`
|
||||
The Admin interface is bundled within the Silverstripe CMS but is most commonly used in conjunction with the `cms`
|
||||
module. The main class for displaying the interface is a specialized [Controller](api:SilverStripe\Control\Controller) called [LeftAndMain](api:SilverStripe\Admin\LeftAndMain), named
|
||||
as it is designed around a left hand navigation and a main edit form.
|
||||
|
||||
Starting with SilverStripe 4, the user interface logic is transitioned from
|
||||
Starting with Silverstripe CMS 4, the user interface logic is transitioned from
|
||||
jQuery and [jQuery.entwine](https://github.com/hafriedlander/jquery.entwine),
|
||||
which is replaced with [ReactJS](http://reactjs.com/). The transition is
|
||||
done iteratively, starting with `AssetAdmin` and `CampaignAdmin`.
|
||||
|
@ -1,12 +1,12 @@
|
||||
---
|
||||
title: App Object and Kernel
|
||||
summary: Provides bootstrapping and entrypoint to the SilverStripe application
|
||||
summary: Provides bootstrapping and entrypoint to the Silverstripe CMS application
|
||||
---
|
||||
|
||||
# Kernel
|
||||
|
||||
The [Kernel](api:SilverStripe\Core\Kernel) object provides a container for the various manifests, services, and components
|
||||
which a SilverStripe application must have available in order for requests to be executed.
|
||||
which a Silverstripe CMS application must have available in order for requests to be executed.
|
||||
|
||||
This can be accessed in user code via Injector
|
||||
|
||||
@ -96,11 +96,11 @@ $response->output();
|
||||
|
||||
## Custom application actions
|
||||
|
||||
If it's necessary to boot a SilverStripe kernel and application, but not do any
|
||||
If it's necessary to boot a Silverstripe CMS kernel and application, but not do any
|
||||
request processing, you can use the Application::execute() method to invoke a custom
|
||||
application entry point.
|
||||
|
||||
This may be necessary if using SilverStripe code within the context of a non-SilverStripe
|
||||
This may be necessary if using Silverstripe CMS code within the context of a non-Silverstripe CMS
|
||||
application.
|
||||
|
||||
For example, the below will setup a request, session, and current controller,
|
||||
|
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Execution pipeline
|
||||
summary: An overview of the steps involved in delivering a SilverStripe web page.
|
||||
summary: An overview of the steps involved in delivering a Silverstripe CMS web page.
|
||||
icon: route
|
||||
---
|
||||
|
||||
@ -9,7 +9,7 @@ icon: route
|
||||
## Introduction
|
||||
|
||||
In order to transform a HTTP request or a commandline exeuction into a response,
|
||||
SilverStripe needs to boot its core and run through several stages of processing.
|
||||
Silverstripe CMS needs to boot its core and run through several stages of processing.
|
||||
|
||||
## Request Rewriting
|
||||
|
||||
@ -19,7 +19,7 @@ The implementation depends on your web server; we'll show you the most common on
|
||||
Apache with [mod_rewrite](http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html).
|
||||
Check our [installation guides](/getting_started/installation) on how other web servers like IIS or nginx handle rewriting.
|
||||
|
||||
The standard SilverStripe project ships with a `.htaccess` file in your webroot for this purpose.
|
||||
The standard Silverstripe CMS project ships with a `.htaccess` file in your webroot for this purpose.
|
||||
By default, requests will be passed through for files existing on the filesystem.
|
||||
Some access control is in place to deny access to potentially sensitive files in the webroot, such as YAML configuration files.
|
||||
If no file can be directly matched, control is handed off to `index.php`.
|
||||
|
@ -1,11 +1,11 @@
|
||||
---
|
||||
title: Command Line Interface
|
||||
summary: Automate SilverStripe, run Cron Jobs or sync with other platforms through the Command Line Interface.
|
||||
introduction: Automate SilverStripe, run Cron Jobs or sync with other platforms through the Command Line Interface.
|
||||
summary: Automate Silverstripe CMS, run Cron Jobs or sync with other platforms through the Command Line Interface.
|
||||
introduction: Automate Silverstripe CMS, run Cron Jobs or sync with other platforms through the Command Line Interface.
|
||||
icon: terminal
|
||||
---
|
||||
|
||||
SilverStripe can call [Controllers](../controllers) through a command line interface (CLI) just as easily as through a
|
||||
Silverstripe CMS can call [Controllers](../controllers) through a command line interface (CLI) just as easily as through a
|
||||
web browser. This functionality can be used to automate tasks with cron jobs, run unit tests, or anything else that
|
||||
needs to interface over the command line.
|
||||
|
||||
@ -23,7 +23,7 @@ more). This can be a good thing, your CLI can be configured to use higher memory
|
||||
to have.
|
||||
[/notice]
|
||||
|
||||
## Sake - SilverStripe Make
|
||||
## Sake - Silverstripe CMS Make
|
||||
|
||||
Sake is a simple wrapper around `cli-script.php`. It also tries to detect which `php` executable to use if more than one
|
||||
are available. It is accessible via `vendor/bin/sake`.
|
||||
@ -48,7 +48,7 @@ This currently only works on UNIX like systems, not on Windows.
|
||||
|
||||
### Configuration
|
||||
|
||||
Sometimes SilverStripe needs to know the URL of your site. For example, when sending an email or generating static
|
||||
Sometimes Silverstripe CMS needs to know the URL of your site. For example, when sending an email or generating static
|
||||
files. When you're visiting the site in a web browser this is easy to work out, but when executing scripts on the
|
||||
command line, it has no way of knowing.
|
||||
|
||||
@ -155,7 +155,7 @@ vendor/bin/sake myurl "myparam=1&myotherparam=2"
|
||||
## Running Regular Tasks With Cron
|
||||
|
||||
On a UNIX machine, you can typically run a scheduled task with a [cron job](http://en.wikipedia.org/wiki/Cron). Run
|
||||
`BuildTask` in SilverStripe as a cron job using `sake`.
|
||||
`BuildTask` in Silverstripe CMS as a cron job using `sake`.
|
||||
|
||||
The following will run `MyTask` every minute.
|
||||
|
||||
|
@ -9,7 +9,7 @@ icon: cookie-bite
|
||||
|
||||
Cookies are a mechanism for storing data in the remote browser and thus tracking or identifying return users.
|
||||
|
||||
SilverStripe uses cookies for remembering users preferences. Application code can modify a users cookies through
|
||||
Silverstripe CMS uses cookies for remembering users preferences. Application code can modify a users cookies through
|
||||
the [Cookie](api:SilverStripe\Control\Cookie) class. This class mostly follows the PHP API.
|
||||
|
||||
### set
|
||||
|
@ -95,7 +95,7 @@ to specifically remove it.
|
||||
$session->clear('MyValue');
|
||||
```
|
||||
|
||||
Or you can clear every single value in the session at once. Note SilverStripe stores some of its own session data
|
||||
Or you can clear every single value in the session at once. Note Silverstripe CMS stores some of its own session data
|
||||
including form and page comment information. None of this is vital but `clear_all` will clear everything.
|
||||
```php
|
||||
$session->clearAll();
|
||||
@ -115,7 +115,7 @@ This uses the session_name `SECSESSID` for `https` connections instead of the de
|
||||
|
||||
## Relaxing checks around user agent strings
|
||||
|
||||
Out of the box, SilverStripe will invalidate a user's session if the `User-Agent` header changes. This provides some supplemental protection against session high-jacking attacks.
|
||||
Out of the box, Silverstripe CMS will invalidate a user's session if the `User-Agent` header changes. This provides some supplemental protection against session high-jacking attacks.
|
||||
|
||||
It is possible to disable the user agent header session validation. However, it is not recommended.
|
||||
|
||||
|
@ -41,7 +41,7 @@ SilverStripe\Control\Director:
|
||||
|
||||
In addition to the default `/graphql` endpoint provided by this module by default,
|
||||
along with the `admin/graphql` endpoint provided by the CMS modules (if they're installed),
|
||||
you may want to set up another GraphQL server running on the same installation of SilverStripe.
|
||||
you may want to set up another GraphQL server running on the same installation of Silverstripe CMS.
|
||||
|
||||
Let's set up a new controller to handle the requests.
|
||||
|
||||
|
@ -18,7 +18,7 @@ Docs for the current stable version (3.x) can be found
|
||||
|
||||
## Authentication
|
||||
|
||||
Some SilverStripe resources have permission requirements to perform CRUD operations
|
||||
Some Silverstripe CMS resources have permission requirements to perform CRUD operations
|
||||
on, for example the `Member` object in the previous examples.
|
||||
|
||||
If you are logged into the CMS and performing a request from the same session then
|
||||
@ -45,7 +45,7 @@ the [CSRF Middleware](csrf_protection) enabled. (It is by default).**
|
||||
Silverstripe CMS has built-in support for [HTTP basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).
|
||||
|
||||
There is a `BasicAuthAuthenticator` which can be configured for GraphQL that
|
||||
will only activate when required. It is kept separate from the SilverStripe CMS
|
||||
will only activate when required. It is kept separate from the Silverstripe CMS
|
||||
authenticator because GraphQL needs to use the successfully authenticated member
|
||||
for CMS permission filtering, whereas the global `BasicAuth` does not log the
|
||||
member in or use it for model security. Note that basic auth will bypass MFA authentication
|
||||
|
@ -27,7 +27,7 @@ is the use of a CSRF token for any requests that destroy or mutate data.
|
||||
By default, this module comes with a `CSRFMiddleware` implementation that forces all mutations to check
|
||||
for the presence of a CSRF token in the request. That token must be applied to a header named` X-CSRF-TOKEN`.
|
||||
|
||||
In SilverStripe, CSRF tokens are most commonly stored in the session as `SecurityID`, or accessed through
|
||||
In Silverstripe CMS, CSRF tokens are most commonly stored in the session as `SecurityID`, or accessed through
|
||||
the `SecurityToken` API, using `SecurityToken::inst()->getValue()`.
|
||||
|
||||
Queries do not require CSRF tokens.
|
||||
|
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Developer Guides
|
||||
introduction: The following guides take a more detailed look into the core concepts and code examples for building SilverStripe applications.
|
||||
introduction: The following guides take a more detailed look into the core concepts and code examples for building Silverstripe CMS applications.
|
||||
---
|
||||
|
||||
In each guide you'll find reference documentation followed by a collection of short and informal How-to's which contain
|
||||
|
@ -1,66 +1,66 @@
|
||||
---
|
||||
title: Upgrading to SilverStripe 4
|
||||
summary: Upgrade your project SilverStripe 4 and keep it up to date with the latest fixes, security patches and new features.
|
||||
title: Upgrading to Silverstripe CMS 4
|
||||
summary: Upgrade your project Silverstripe CMS 4 and keep it up to date with the latest fixes, security patches and new features.
|
||||
---
|
||||
|
||||
# Upgrading a SilverStripe 3 project to SilverStripe 4
|
||||
# Upgrading a Silverstripe CMS 3 project to Silverstripe CMS 4
|
||||
|
||||
SilverStripe applications should be kept up to date with the latest security releases. Usually an update or upgrade to
|
||||
your SilverStripe installation means overwriting files, flushing the cache and updating your database schema.
|
||||
Silverstripe CMS applications should be kept up to date with the latest security releases. Usually an update or upgrade to
|
||||
your Silverstripe CMS installation means overwriting files, flushing the cache and updating your database schema.
|
||||
|
||||
## Understanding and planning your upgrade {#planning}
|
||||
|
||||
How easy will it be to update my project? It's a fair question, and sometimes a difficult one to answer.
|
||||
|
||||
* SilverStripe follows _semantic versioning_ (see our [release process](/contributing/release_process) for details).
|
||||
* Silverstripe CMS follows _semantic versioning_ (see our [release process](/contributing/release_process) for details).
|
||||
* "Major" releases introduce API changes that may break your application.
|
||||
* "Minor" releases (x.y) introduce API changes in a backwards compatible way and can mark some API as deprecated.
|
||||
* "Patch" releases (x.y.z) fix bugs without introducing any API changes.
|
||||
* If you've made custom branches of SilverStripe core, or any thirdparty module, upgrades are going to be more complex.
|
||||
* If you've made custom branches of Silverstripe CMS core, or any thirdparty module, upgrades are going to be more complex.
|
||||
* More custom features will mean more work to re-test all of those features, and adapt to API changes in core.
|
||||
* Customisations of a well defined type - such as custom page types or custom blog widgets -
|
||||
are going to be easier to upgrade than customisations that modify deep system internals like rewriting SQL queries.
|
||||
|
||||
### Overview of changes
|
||||
|
||||
There are some fundamental changes in SilverStripe 4:
|
||||
There are some fundamental changes in Silverstripe CMS 4:
|
||||
|
||||
* PHP 7.1 is now the minimum required version for SilverStripe 4.5.0 and above. We strongly recommend you only use [supported versions of PHP](https://www.php.net/supported-versions.php). Note: SilverStripe 4.0.0 through 4.4.0 still support PHP 5.6.
|
||||
* PHP 7.4 is supported from SilverStripe 4.5.3 and above.
|
||||
* SilverStripe is now even more modular which allows you to remove functionality your project might not need.
|
||||
* Common functionality sets can now be installed via SilverStripe _recipes_.
|
||||
* SilverStripe modules can now be installed in the `vendor/` folder along with your regular PHP packages.
|
||||
* PHP 7.1 is now the minimum required version for Silverstripe CMS 4.5.0 and above. We strongly recommend you only use [supported versions of PHP](https://www.php.net/supported-versions.php). Note: Silverstripe CMS 4.0.0 through 4.4.0 still support PHP 5.6.
|
||||
* PHP 7.4 is supported from Silverstripe CMS 4.5.3 and above.
|
||||
* Silverstripe CMS is now even more modular which allows you to remove functionality your project might not need.
|
||||
* Common functionality sets can now be installed via Silverstripe CMS _recipes_.
|
||||
* Silverstripe CMS modules can now be installed in the `vendor/` folder along with your regular PHP packages.
|
||||
* All classes are namespaced: You have to use these, but can decide if you namespace your project code.
|
||||
* PHP _traits_ replace a few core classes (e.g. `Object`) and make it easy to apply common patterns
|
||||
* Public files can now be served from a `public/` webroot for added security.
|
||||
* Versioning is more powerful through an "ownership" concept, and available for all DataObject classes.
|
||||
* Changes across objects can be collected in a "campaign" for batch publication.
|
||||
* GraphQL is now the favourite way of creating web services with SilverStripe.
|
||||
* GraphQL is now the favourite way of creating web services with Silverstripe CMS.
|
||||
* Asset management has been completely redone with a brand new React-based UI, protected draft files and versioning.
|
||||
* Parts of the CMS UI are now built with React and Bootstrap instead of Entwine and custom CSS.
|
||||
* PSR-4 auto-loading is supported for modules and for your project code.
|
||||
|
||||
[Learn more about major API changes introduced by SilverStripe 4](#list-of-major-api-changes),
|
||||
[Learn more about major API changes introduced by Silverstripe CMS 4](#list-of-major-api-changes),
|
||||
and dig into the changelogs for [4.0.0](/changelogs/4.0.0), [4.1.0](/changelogs/4.1.0), [4.2.0](/changelogs/4.2.0), and [4.3.0](/changelogs/4.3.0).
|
||||
|
||||
### Using recipes instead of requiring individual modules
|
||||
The SilverStripe CMS and SilverStripe Framework are becoming more modular. Many of the secondary features contained in SilverStripe CMS 3 and SilverStripe Framework 3 have been moved to separate modules.
|
||||
The Silverstripe CMS and Silverstripe Framework are becoming more modular. Many of the secondary features contained in Silverstripe CMS 3 and Silverstripe Framework 3 have been moved to separate modules.
|
||||
|
||||
SilverStripe 4 introduces the concept of _recipes_. Recipes are a combination of modules to achieve a common pattern.
|
||||
Silverstripe CMS 4 introduces the concept of _recipes_. Recipes are a combination of modules to achieve a common pattern.
|
||||
|
||||
Read the [Switching to recipes](#switching-to-recipes) section of this guide for more information about how recipes work.
|
||||
|
||||
### Automating your upgrades using the SilverStripe Upgrader tool
|
||||
### Automating your upgrades using the Silverstripe CMS Upgrader tool
|
||||
We've developed [an upgrader tool](https://github.com/silverstripe/silverstripe-upgrader) which you can use to help
|
||||
with the upgrade process. The upgrader is unlikely to completely upgrade your project, however it can take care of the most tedious part of the upgrade.
|
||||
It can also be used to upgrade your existing SilverStripe 4 project to a newer minor release.
|
||||
It can also be used to upgrade your existing Silverstripe CMS 4 project to a newer minor release.
|
||||
If you have previously used the upgrader tool, make sure to use its newest version.
|
||||
Since 1.4.0, there's a [self update feature](https://github.com/silverstripe/silverstripe-upgrader/blob/master/README.md#self-update).
|
||||
|
||||
### Identify known issues
|
||||
|
||||
It's sometimes hard to tell if an issue you're hitting is caused by upgrading project code,
|
||||
or is a known issue in SilverStripe. Often an issue is fixed already, but not
|
||||
or is a known issue in Silverstripe CMS. Often an issue is fixed already, but not
|
||||
yet packaged in the release you're upgrading to. Use our
|
||||
[issue search across our core modules](https://silverstripe-github-issues.now.sh/?supported=0&status=all),
|
||||
and ensure you're including closed ones (they might be done but not released yet).
|
||||
@ -83,7 +83,7 @@ Never update a website on the live server. Get it working on a development copy
|
||||
|
||||
### Install composer
|
||||
|
||||
[Composer](http://getcomposer.org) is a tool for managing PHP dependencies. SilverStripe 4 requires composer version _1.1_ or greater. Read the [SilverStripe _Getting started_ guide](/getting_started/composer) for more details.
|
||||
[Composer](http://getcomposer.org) is a tool for managing PHP dependencies. Silverstripe CMS 4 requires composer version _1.1_ or greater. Read the [Silverstripe CMS _Getting started_ guide](/getting_started/composer) for more details.
|
||||
|
||||
We recommend using `recipe-cms` in your `composer.json` file to help you keep up to date.
|
||||
|
||||
@ -125,7 +125,7 @@ Each command in the upgrader has somewhat different arguments. However, most of
|
||||
* `--root-dir` which can be use to explicitly specify the root of your project. If this is not specified then the current working directory is assumed to be the root of the project.
|
||||
|
||||
[info]
|
||||
Sample upgrader commands in this guide assume your working directory is the root of your SilverStripe project. You'll need to use the `--root-dir` flag if that's not the case.
|
||||
Sample upgrader commands in this guide assume your working directory is the root of your Silverstripe CMS project. You'll need to use the `--root-dir` flag if that's not the case.
|
||||
[/info]
|
||||
|
||||
#### Install the upgrader globally with composer
|
||||
@ -157,7 +157,7 @@ The upgrader comes with an `all` command. This command will attempt to run all t
|
||||
upgrade-code all --namespace="App\\Web" --psr4
|
||||
```
|
||||
|
||||
* `--recipe-core-constraint` defines your SilverStripe release version (optional, will default to the most recent stable release).
|
||||
* `--recipe-core-constraint` defines your Silverstripe CMS release version (optional, will default to the most recent stable release).
|
||||
* `--cwp-constraint` can be used instead `--recipe-core-constraint` when upgrading a CWP project.
|
||||
* `--namespace` allows you to specify how your project will be namespaced (optional).
|
||||
* `--psr4` allows you to specify that your project structure respects the PSR-4 standard and to automatically use sub-namespaces.
|
||||
@ -177,11 +177,11 @@ The first step is to update your dependencies' constraints in your `composer.jso
|
||||
|
||||
If you've installed the upgrader, you can use the `recompose` command to help you upgrade your dependencies. This command will try to:
|
||||
* upgrade your PHP constraint
|
||||
* upgrade core SilverStripe modules to their version 4 equivalent
|
||||
* upgrade core Silverstripe CMS modules to their version 4 equivalent
|
||||
* switch to recipes where possible
|
||||
* find SilverStripe 4 compatible versions of third party modules.
|
||||
* find Silverstripe CMS 4 compatible versions of third party modules.
|
||||
|
||||
Take for example the following SilverStripe 3 `composer.json` file.
|
||||
Take for example the following Silverstripe CMS 3 `composer.json` file.
|
||||
```json
|
||||
{
|
||||
"name": "app/cms-website",
|
||||
@ -235,16 +235,16 @@ The instructions in this section assume that you'll be editing your `composer.js
|
||||
|
||||
Where possible, we recommend you use recipes.
|
||||
|
||||
If your SilverStripe 3 project requires the `silverstripe/cms` module, replace that dependency with `silverstripe/recipe-cms`. The version constraint for `silverstripe/recipe-cms` must match your targeted version of SilverStripe:
|
||||
* `~4.0.0` to upgrade to SilverStripe 4.0
|
||||
* `~4.1.0` to upgrade to SilverStripe 4.1
|
||||
* `~4.2.0` to upgrade to SilverStripe 4.2
|
||||
If your Silverstripe CMS 3 project requires the `silverstripe/cms` module, replace that dependency with `silverstripe/recipe-cms`. The version constraint for `silverstripe/recipe-cms` must match your targeted version of Silverstripe CMS:
|
||||
* `~4.0.0` to upgrade to Silverstripe CMS 4.0
|
||||
* `~4.1.0` to upgrade to Silverstripe CMS 4.1
|
||||
* `~4.2.0` to upgrade to Silverstripe CMS 4.2
|
||||
* and so on.
|
||||
|
||||
If your SilverStripe 3 project requires the `silverstripe/framework` module without `silverstripe/cms`, replace `silverstripe/framework` with `silverstripe/recipe-core`. The version constraint for `silverstripe/recipe-core` must match your targeted version of SilverStripe:
|
||||
* `~4.0.0` to upgrade to SilverStripe 4.0
|
||||
* `~4.1.0` to upgrade to SilverStripe 4.1
|
||||
* `~4.2.0` to upgrade to SilverStripe 4.2
|
||||
If your Silverstripe CMS 3 project requires the `silverstripe/framework` module without `silverstripe/cms`, replace `silverstripe/framework` with `silverstripe/recipe-core`. The version constraint for `silverstripe/recipe-core` must match your targeted version of Silverstripe CMS:
|
||||
* `~4.0.0` to upgrade to Silverstripe CMS 4.0
|
||||
* `~4.1.0` to upgrade to Silverstripe CMS 4.1
|
||||
* `~4.2.0` to upgrade to Silverstripe CMS 4.2
|
||||
* and so on.
|
||||
|
||||
The following modules are implicitly required by `silverstripe/recipe-core`. They can be removed from your `composer.json` dependencies if you are using `silverstripe/recipe-core` or `silverstripe/recipe-cms`.
|
||||
@ -264,7 +264,7 @@ The following modules are implicitly required by `silverstripe/recipe-cms`. They
|
||||
* `silverstripe/versioned`
|
||||
* `silverstripe/recipe-core`
|
||||
|
||||
Take for example the following SilverStripe 3 `composer.json`.
|
||||
Take for example the following Silverstripe CMS 3 `composer.json`.
|
||||
```json
|
||||
{
|
||||
"name": "app/cms-website",
|
||||
@ -277,7 +277,7 @@ Take for example the following SilverStripe 3 `composer.json`.
|
||||
}
|
||||
```
|
||||
|
||||
After switching to SilverStripe 4 recipes, the `composer.json` file should look like this.
|
||||
After switching to Silverstripe CMS 4 recipes, the `composer.json` file should look like this.
|
||||
```json
|
||||
{
|
||||
"name": "app/cms-website",
|
||||
@ -288,11 +288,11 @@ After switching to SilverStripe 4 recipes, the `composer.json` file should look
|
||||
```
|
||||
|
||||
#### Explicitly defining your dependencies
|
||||
If you would rather explicitly define your dependencies, you can do so. Update the `silverstripe/framework` constraint and `silverstripe/cms` constraint to match your targeted minor version of SilverStripe 4. If you use `silverstripe/reports` and `silverstripe/siteconfig`, update their constraints as well.
|
||||
If you would rather explicitly define your dependencies, you can do so. Update the `silverstripe/framework` constraint and `silverstripe/cms` constraint to match your targeted minor version of Silverstripe CMS 4. If you use `silverstripe/reports` and `silverstripe/siteconfig`, update their constraints as well.
|
||||
|
||||
In most cases, you'll also want to require the same modules as the equivalent recipes. If you don't, your users will likely lose some features after the upgrade is completed.
|
||||
|
||||
Take for example the following SilverStripe 3 `composer.json`.
|
||||
Take for example the following Silverstripe CMS 3 `composer.json`.
|
||||
```json
|
||||
{
|
||||
"name": "app/cms-website",
|
||||
@ -305,7 +305,7 @@ Take for example the following SilverStripe 3 `composer.json`.
|
||||
}
|
||||
```
|
||||
|
||||
After switching to SilverStripe 4 and explicitly defining your dependencies, the `composer.json` file should look like this.
|
||||
After switching to Silverstripe CMS 4 and explicitly defining your dependencies, the `composer.json` file should look like this.
|
||||
```json
|
||||
{
|
||||
"name": "app/cms-website",
|
||||
@ -325,11 +325,11 @@ After switching to SilverStripe 4 and explicitly defining your dependencies, the
|
||||
```
|
||||
|
||||
#### Updating third party dependencies
|
||||
If you project requires third party modules, you'll need to adjust their associated constraint. This will allow you to retrieve a SilverStripe 4 compatible version of the module.
|
||||
If you project requires third party modules, you'll need to adjust their associated constraint. This will allow you to retrieve a Silverstripe CMS 4 compatible version of the module.
|
||||
|
||||
[Look up the module on Packagist](https://packagist.org/) to see if a SilverStripe 4 version is provided.
|
||||
[Look up the module on Packagist](https://packagist.org/) to see if a Silverstripe CMS 4 version is provided.
|
||||
|
||||
Take for example the following SilverStripe 3 `composer.json`.
|
||||
Take for example the following Silverstripe CMS 3 `composer.json`.
|
||||
```json
|
||||
{
|
||||
"name": "app/cms-website",
|
||||
@ -341,9 +341,9 @@ Take for example the following SilverStripe 3 `composer.json`.
|
||||
}
|
||||
```
|
||||
|
||||
Looking at the [Packagist entry for `dnadesign/silverstripe-elemental`](https://packagist.org/packages/dnadesign/silverstripe-elemental#2.0.0), you can see that versions 2.0.0 and above of this module are compatible with SilverStripe 4. So you can update that constraint to `^2.0.0`.
|
||||
Looking at the [Packagist entry for `dnadesign/silverstripe-elemental`](https://packagist.org/packages/dnadesign/silverstripe-elemental#2.0.0), you can see that versions 2.0.0 and above of this module are compatible with Silverstripe CMS 4. So you can update that constraint to `^2.0.0`.
|
||||
|
||||
Alternatively, you can set a very permissive constraint and let composer find a SilverStripe 4 compatible version. After you're done updating your dependencies, make sure you adjust your constraints to be more specific.
|
||||
Alternatively, you can set a very permissive constraint and let composer find a Silverstripe CMS 4 compatible version. After you're done updating your dependencies, make sure you adjust your constraints to be more specific.
|
||||
|
||||
Once you've updated your third-party modules constraints, try updating your dependencies by running `composer update`. If composer can't resolve all your dependencies it will throw an error.
|
||||
|
||||
@ -353,9 +353,9 @@ You'll likely have some conflicts to resolve, whether you've updated your depend
|
||||
|
||||
Running a `composer update` will tell you which modules are conflicted and suggest alternative combinations of modules that might work.
|
||||
|
||||
The most typical reason for a conflict is that the maintainer of a module has not released a version compatible with SilverStripe 4.
|
||||
The most typical reason for a conflict is that the maintainer of a module has not released a version compatible with Silverstripe CMS 4.
|
||||
|
||||
If the maintainer of the module is in the process of upgrading to SilverStripe 4, a development version of the module might be available. In some cases, it can be worthwhile to look up the repository of the module or to reach out to the maintainer.
|
||||
If the maintainer of the module is in the process of upgrading to Silverstripe CMS 4, a development version of the module might be available. In some cases, it can be worthwhile to look up the repository of the module or to reach out to the maintainer.
|
||||
|
||||
Another possible cause of a dependency conflict is the use of private packages. The `recompose` command does not take into consideration the `repositories` entries in your project's `composer.json` file. Constraints on private packages have to be defined manually.
|
||||
|
||||
@ -372,7 +372,7 @@ If you're going to install a development version of third party modules, you sho
|
||||
}
|
||||
```
|
||||
|
||||
If no development release is available for SilverStripe 4, you can upgrade the module manually or remove the module from your project.
|
||||
If no development release is available for Silverstripe CMS 4, you can upgrade the module manually or remove the module from your project.
|
||||
|
||||
#### Upgrading the module manually
|
||||
|
||||
@ -384,9 +384,9 @@ This approach has the advantage of keeping the module out of your codebase. It a
|
||||
|
||||
When forking the module, you should convert it to a vendor module.
|
||||
|
||||
Upgrade the module so it works with version `4` of SilverStripe, commit and push your changes to your forked repository.
|
||||
Upgrade the module so it works with version `4` of Silverstripe CMS, commit and push your changes to your forked repository.
|
||||
|
||||
See [Upgrading a module](./upgrading_module) for more information on how to upgrade a SilverStripe module.
|
||||
See [Upgrading a module](./upgrading_module) for more information on how to upgrade a Silverstripe CMS module.
|
||||
|
||||
If you're taking the time to upgrade a third party module, consider doing a pull request against the original project so other developers can benefit from your work. Or you can release your fork as a separate module.
|
||||
|
||||
@ -403,13 +403,13 @@ If you want to keep your fork private, you can include it in your project by add
|
||||
...
|
||||
```
|
||||
|
||||
[Learn about how to publish a SilverStripe module](/developer_guides/extending/how_tos/publish_a_module)
|
||||
[Learn about how to publish a Silverstripe CMS module](/developer_guides/extending/how_tos/publish_a_module)
|
||||
|
||||
##### Integrate the affected module into your project's codebase
|
||||
|
||||
You can add the module codebase to your own project. This is the simplest option, but it increases the complexity of your project, and the amount of code you have to maintain, therefore it is discouraged.
|
||||
|
||||
If you choose this option, the module will be treated as a root module, which is discouraged in SilverStripe 4.
|
||||
If you choose this option, the module will be treated as a root module, which is discouraged in Silverstripe CMS 4.
|
||||
|
||||
1. Remove the module from your dependencies by manually editing your `composer.json` file. Do not use `composer remove` as this will remove your folder.
|
||||
2. Update your `.gitignore` file to track the module.
|
||||
@ -427,7 +427,7 @@ This can be done simply by removing the dependency: `composer remove <package>`
|
||||
|
||||
Once you've resolved all conflicts in your `composer.json` file, `composer update` will be able to run without errors.
|
||||
|
||||
This will install your new dependencies. You'll notice many of the folders in the root of your project will disappear. That's because SilverStripe 4 modules can be installed in the vendor folder like generic PHP packages.
|
||||
This will install your new dependencies. You'll notice many of the folders in the root of your project will disappear. That's because Silverstripe CMS 4 modules can be installed in the vendor folder like generic PHP packages.
|
||||
|
||||
If you've decided to use recipes, some generic files will be copied from the recipe into your project. The `extra` attribute in your `composer.json` file will be updated to keep track of those new files.
|
||||
|
||||
@ -456,7 +456,7 @@ If your `_ss_environment.php` file contains unusual logic (conditional statement
|
||||
|
||||
Create a `.env` file in the root of your project. Replace `define` statements from `_ss_environment.php` with `KEY=VALUE` pairs in `.env`.
|
||||
|
||||
Most SilverStripe 3 environment variables have been carried over to SilverStripe 4. See [Environment Management docs](/getting_started/environment_management/) for the full list of available variables. Your `.env` file can contain environment variables specific to your project as well.
|
||||
Most Silverstripe CMS 3 environment variables have been carried over to Silverstripe CMS 4. See [Environment Management docs](/getting_started/environment_management/) for the full list of available variables. Your `.env` file can contain environment variables specific to your project as well.
|
||||
|
||||
The global array `$_FILE_TO_URL_MAPPING` has been removed and replaced with the `SS_BASE_URL` environment variable. `SS_BASE_URL` expects an absolute url with an optional protocol. The following are values would be valid entries for `SS_BASE_URL`:
|
||||
* `http://localhost/`
|
||||
@ -553,7 +553,7 @@ By default, the same namespace will be applied to all your classes regardless of
|
||||
|
||||
Go through each PHP file under `mysite/code` and add a `namespace` statement at the top, *with the exception of the files for `Page` or `PageController`*.
|
||||
|
||||
Take for example this SilverStripe 3 file located at `mysite/code/Products/ExplosiveTennisBall.php`.
|
||||
Take for example this Silverstripe CMS 3 file located at `mysite/code/Products/ExplosiveTennisBall.php`.
|
||||
```php
|
||||
<?php
|
||||
|
||||
@ -628,15 +628,15 @@ Read the [Composer schema autoload documentation](https://getcomposer.org/doc/04
|
||||
### Finalise your project namespacing
|
||||
All your classes should now be fully namespaced.
|
||||
|
||||
Note that applying a namespace to your project will also affect which template file SilverStripe tries to load when rendering certain objects.
|
||||
Note that applying a namespace to your project will also affect which template file Silverstripe CMS tries to load when rendering certain objects.
|
||||
|
||||
For example, pretend you have a `RoadRunnerPage` class that extends `Page`. In SilverStripe 3, you would define a template for this page in `themes/example/templates/Layout/RoadRunnerPage.ss`. If you decide to move `RoadRunnerPage` to `App\Web\RoadRunnerPage`, you'll need to move the template to `themes/example/templates/App/Web/Layout/RoadRunnerPage.ss`.
|
||||
For example, pretend you have a `RoadRunnerPage` class that extends `Page`. In Silverstripe CMS 3, you would define a template for this page in `themes/example/templates/Layout/RoadRunnerPage.ss`. If you decide to move `RoadRunnerPage` to `App\Web\RoadRunnerPage`, you'll need to move the template to `themes/example/templates/App/Web/Layout/RoadRunnerPage.ss`.
|
||||
|
||||
This is a good point to commit your changes to your source control system before moving on to the next step.
|
||||
|
||||
## Step 4 - Update codebase with references to newly namespaced classes {#step4}
|
||||
|
||||
All core PHP classes in SilverStripe 4 have been namespaced. For example, `DataObject` is now called `SilverStripe\ORM\DataObject`. Your project codebase, config files and language files need be updated to reference those newly namespaced classes. This will include explicit references in your PHP code, but also string that contain the name of a class.
|
||||
All core PHP classes in Silverstripe CMS 4 have been namespaced. For example, `DataObject` is now called `SilverStripe\ORM\DataObject`. Your project codebase, config files and language files need be updated to reference those newly namespaced classes. This will include explicit references in your PHP code, but also string that contain the name of a class.
|
||||
If you've opted to namespace your own code in the previous step, those references will need to be updated as well.
|
||||
|
||||
### Automatically update namespaced references with the `upgrade` command
|
||||
@ -645,7 +645,7 @@ If you've installed the upgrader, you can use the `upgrade` command to update re
|
||||
|
||||
The `upgrade` command will update PHP files, YML configuration files, and YML language files.
|
||||
|
||||
Each core SilverStripe 4 module includes a `.upgrade.yml` that defines the equivalent fully qualified name of each class. Most third party SilverStripe modules that have been upgraded to be compatible with SilverStripe 4, also include a `.upgrade.yml`. If you've namespaced your own project, you'll need to provide your own `.upgrade.yml` file . If you've used the upgrader to namespace your project, that file will have been created for you.
|
||||
Each core Silverstripe CMS 4 module includes a `.upgrade.yml` that defines the equivalent fully qualified name of each class. Most third party Silverstripe CMS modules that have been upgraded to be compatible with Silverstripe CMS 4, also include a `.upgrade.yml`. If you've namespaced your own project, you'll need to provide your own `.upgrade.yml` file . If you've used the upgrader to namespace your project, that file will have been created for you.
|
||||
|
||||
The `upgrade` command will try to update some strings that reference the old name of some classes. In some cases this might not be what you want. You can tell the upgrader to skip specific strings by using the `@skipUpgrade` flag in your PHPDoc comment. For example:
|
||||
|
||||
@ -692,13 +692,13 @@ Add the `--prompt` flag to manually approve ambiguous class renames.
|
||||
|
||||
### Manually update namespaced references
|
||||
|
||||
If you decide to update your namespace references by hand, you'll need to go through the entire code base and update them all from the old non-namespaced SilverStripe classes to the new namespaced equivalent. If you are referencing classes from third party modules that have been namespaced, you'll need to update those as well.
|
||||
If you decide to update your namespace references by hand, you'll need to go through the entire code base and update them all from the old non-namespaced Silverstripe CMS classes to the new namespaced equivalent. If you are referencing classes from third party modules that have been namespaced, you'll need to update those as well.
|
||||
|
||||
#### Update explicit references to classes in your code
|
||||
|
||||
Wherever your code explicitly references a SilverStripe class, it will need to be updated to the new namespaced equivalent. You can either update the reference to use the fully qualified name of the class or you can add a `use` statement to your file.
|
||||
Wherever your code explicitly references a Silverstripe CMS class, it will need to be updated to the new namespaced equivalent. You can either update the reference to use the fully qualified name of the class or you can add a `use` statement to your file.
|
||||
|
||||
For example take the following SilverStripe 3 class. `DataObject` and `FieldList` need to point to their namespace equivalents.
|
||||
For example take the following Silverstripe CMS 3 class. `DataObject` and `FieldList` need to point to their namespace equivalents.
|
||||
|
||||
```php
|
||||
<?php
|
||||
@ -747,7 +747,7 @@ class ExplosiveTennisBall extends SilverStripe\ORM\DataObject
|
||||
|
||||
#### Update string references to classes
|
||||
|
||||
In many cases, SilverStripe expects to be provided the name of a class as a string. Typical scenarios include:
|
||||
In many cases, Silverstripe CMS expects to be provided the name of a class as a string. Typical scenarios include:
|
||||
* defining an `has_one` or `has_many` relationship on a DataObject
|
||||
* requesting an instance of class via the Injector
|
||||
* specifying managed models for a `ModelAdmin`.
|
||||
@ -814,9 +814,9 @@ Alternatively, you can spell out the full qualified name of each class in a stri
|
||||
|
||||
#### Update references to classes in your YML config
|
||||
|
||||
YAML configuration files can reference SilverStripe classes. Those references also need to use the fully qualified name of each class.
|
||||
YAML configuration files can reference Silverstripe CMS classes. Those references also need to use the fully qualified name of each class.
|
||||
|
||||
Take for example the following SilverStripe 3 YAML configuration file.
|
||||
Take for example the following Silverstripe CMS 3 YAML configuration file.
|
||||
|
||||
```yaml
|
||||
Injector:
|
||||
@ -833,7 +833,7 @@ Email:
|
||||
admin_email: no-reply@example.com
|
||||
```
|
||||
|
||||
In SilverStripe 4, this will become:
|
||||
In Silverstripe CMS 4, this will become:
|
||||
```yaml
|
||||
SilverStripe\Core\Injector\Injector:
|
||||
App\Web\ProductService:
|
||||
@ -851,7 +851,7 @@ SilverStripe\Control\Email\Email:
|
||||
|
||||
#### Update references to classes in your language files
|
||||
|
||||
Translation keys are normally tied to classes. If you override SilverStripe's default translation or if you are localising your own project, you'll need to update those references to use the fully qualified name of each class.
|
||||
Translation keys are normally tied to classes. If you override Silverstripe CMS's default translation or if you are localising your own project, you'll need to update those references to use the fully qualified name of each class.
|
||||
|
||||
For example, let's say you had the following translation file in `mysite/lang/eng.yml`.
|
||||
```yaml
|
||||
@ -862,7 +862,7 @@ en:
|
||||
SALUTATION: Beep Beep
|
||||
```
|
||||
|
||||
In SilverStripe 4, it would become:
|
||||
In Silverstripe CMS 4, it would become:
|
||||
```yaml
|
||||
en:
|
||||
SilverStripe\Security\Member:
|
||||
@ -883,10 +883,10 @@ In your PHP code, calls to the `_t()` method should be updated to use the full n
|
||||
```php
|
||||
<?php
|
||||
|
||||
# Old SilverStripe 3 way
|
||||
# Old Silverstripe CMS 3 way
|
||||
$translation = _t('CMSMain.ACCESS', "Access to ''{title}'' section", ['title' => 'Products']);
|
||||
|
||||
# New SilverStripe 4
|
||||
# New Silverstripe CMS 4
|
||||
use SilverStripe\CMS\Controllers\CMSMain;
|
||||
// ...
|
||||
$translation = _t(CMSMain::class . '.ACCESS', "Access to '{title}' section", ['title' => 'Products']);
|
||||
@ -916,16 +916,16 @@ Avoid using `static::class` or `parent::class` to retrieve translated string. It
|
||||
If your template files contain translatable strings, they also need to be updated to referenced the namespaced classes.
|
||||
For example, `<%t Member.SINGULARNAME 'Member' %>` would become `<%t SilverStripe\Security\Member.SINGULARNAME 'Member' %>`.
|
||||
|
||||
Your codebase should now be referencing valid SilverStripe 4 classes. This means that your classes can be loaded at runtime. However, your codebase will still be using an outdated API.
|
||||
Your codebase should now be referencing valid Silverstripe CMS 4 classes. This means that your classes can be loaded at runtime. However, your codebase will still be using an outdated API.
|
||||
This is a good point to commit your changes to your source control system before moving on to the next step.
|
||||
|
||||
## Step 5 - Updating your codebase to use SilverStripe 4 API {#step5}
|
||||
## Step 5 - Updating your codebase to use Silverstripe CMS 4 API {#step5}
|
||||
|
||||
This is the most intricate and potentially time-consuming part of the upgrade. It involves going through your entire codebase to remove references to deprecated APIs and update your project logic.
|
||||
|
||||
### Automatically update deprecated API references with the `inspect` command
|
||||
|
||||
The upgrader has an `inspect` command that can flag deprecated API usage, and in some cases, update your codebase to the SilverStripe 4 equivalent. This does require you to carefully review each change and warning to make sure the updated logic still work as intended. Even so, it is a huge time-saver compared to reviewing your code base manually.
|
||||
The upgrader has an `inspect` command that can flag deprecated API usage, and in some cases, update your codebase to the Silverstripe CMS 4 equivalent. This does require you to carefully review each change and warning to make sure the updated logic still work as intended. Even so, it is a huge time-saver compared to reviewing your code base manually.
|
||||
|
||||
Note that the `inspect` command loads your files with PHP interpreter. So basic syntax errors — for example, extending a class that does not exists — will cause an immediate failure. For this reason, you need to complete [Step 4 - Update codebase with references to newly namespaced classes](#step4) before running the `inspect` command.
|
||||
|
||||
@ -963,47 +963,47 @@ Changes not saved; Run with --write to commit to disk
|
||||
|
||||
### Manually update deprecated API references
|
||||
|
||||
SilverStripe 4 introduces many API changes. To update deprecated API references manually, you have to go through each one of your project files.
|
||||
Silverstripe CMS 4 introduces many API changes. To update deprecated API references manually, you have to go through each one of your project files.
|
||||
Read the changelogs for [4.0.0](/changelogs/4.0.0/) and for [subsequent minor releases](/changelogs)
|
||||
|
||||
### Finalising the deprecated API update
|
||||
At this stage, your site should be using only SilverStripe 4 API logic.
|
||||
At this stage, your site should be using only Silverstripe CMS 4 API logic.
|
||||
|
||||
You still have some minor clean up tasks and configuration tweaks to apply, but you're almost done.
|
||||
|
||||
This is a good point to commit your changes to your source control system before moving on to the next step.
|
||||
|
||||
## Step 6 - Update your entry point {#step6}
|
||||
The location of SilverStripe's _entry file_ has changed. Your project and server environment will need
|
||||
The location of Silverstripe CMS's _entry file_ has changed. Your project and server environment will need
|
||||
to adjust the path to this file from `framework/main.php` to `index.php`.
|
||||
|
||||
### Update your `index.php` file
|
||||
You can get a copy of the SilverStripe 4 `index.php` file at
|
||||
You can get a copy of the Silverstripe CMS 4 `index.php` file at
|
||||
`vendor/silverstripe/recipe-core/public/index.php`.
|
||||
|
||||
If you've created your own `index.php` or modified version of `main.php`,
|
||||
you'll need to reconcile those changes with the `index.php` file you got from `recipe-core`.
|
||||
Otherwise, just use the generic `index.php` file `recipe-core` provides.
|
||||
|
||||
Copy your new `index.php` to your project's web root. Unlike SilverStripe 3, `index.php` must be present in your web root.
|
||||
Copy your new `index.php` to your project's web root. Unlike Silverstripe CMS 3, `index.php` must be present in your web root.
|
||||
|
||||
### Update your server configuration
|
||||
If you're using a `.htaccess` file or `web.config` file to handle your server configuration, you can get the generic SilverStripe 4 version of those file from
|
||||
If you're using a `.htaccess` file or `web.config` file to handle your server configuration, you can get the generic Silverstripe CMS 4 version of those file from
|
||||
`vendor/silverstripe/recipe-core/public`.
|
||||
|
||||
Just like `index.php`, if you've modified your server configuration file from the one that shipped with SilverStripe 3, you'll need to reconcile your changes into the version retrieve from `recipe-core`.
|
||||
Just like `index.php`, if you've modified your server configuration file from the one that shipped with Silverstripe CMS 3, you'll need to reconcile your changes into the version retrieve from `recipe-core`.
|
||||
|
||||
[Refer to the installation instruction for your platform](/getting_started/installation/) if your server configuration is not managed via a `.htaccess` or `web.config` file.
|
||||
|
||||
### Finalising the entry point upgrade
|
||||
|
||||
At this stage, you could in theory run your project in SilverStripe 4.
|
||||
At this stage, you could in theory run your project in Silverstripe CMS 4.
|
||||
|
||||
This is a good point to commit your changes to your source control system before moving on to the next step.
|
||||
|
||||
## Step 7 - Update project structure (optional) {#step7}
|
||||
SilverStripe 4 introduces a new recommended project structure ([details](/changelogs/4.2.0#app-folder-name)).
|
||||
Adopting the recommended project structure is optional, but will become mandatory in SilverStripe 5.
|
||||
Silverstripe CMS 4 introduces a new recommended project structure ([details](/changelogs/4.2.0#app-folder-name)).
|
||||
Adopting the recommended project structure is optional, but will become mandatory in Silverstripe CMS 5.
|
||||
|
||||
[Skip to Step 8](#step8)
|
||||
|
||||
@ -1073,11 +1073,11 @@ This is a good point to commit your changes to your source control system before
|
||||
|
||||
## Step 8 - Switch to public web-root (optional){#step8}
|
||||
|
||||
SilverStripe 4.1 introduces the concept of _public web-root_ this allows you to move
|
||||
Silverstripe CMS 4.1 introduces the concept of _public web-root_ this allows you to move
|
||||
all publicly accessible assets under a `public` folder ([details](/changelogs/4.1.0#public-folder)).
|
||||
This has security benefits as it minimises the possibility that files that are not meant to be access directly get accidentally exposed.
|
||||
|
||||
This step is optional and requires SilverStripe 4.1 or greater. It will become mandatory in SilverStripe 5.
|
||||
This step is optional and requires Silverstripe CMS 4.1 or greater. It will become mandatory in Silverstripe CMS 5.
|
||||
|
||||
[Skip to Step 9](#step9)
|
||||
|
||||
@ -1105,19 +1105,19 @@ If you are using a modified `index.php`, `.htaccess`, or `web.config`, you will
|
||||
* Delete the root `resources` or `_resources` directories if present.
|
||||
* Run the following command `composer vendor-expose` to make static assets files accessible via the `public` directory.
|
||||
|
||||
If you are upgrading from SilverStripe 4.0 to SilverStripe 4.1 (or above), you'll need to update `index.php` before moving it to the public folder. You can get a copy of the generic `index.php` file from `vendor/silverstripe/recipe-core/public`. If you've made modifications to your `index.php` file, you'll need to replicate those into the new `public/index.php` file.
|
||||
If you are upgrading from Silverstripe CMS 4.0 to Silverstripe CMS 4.1 (or above), you'll need to update `index.php` before moving it to the public folder. You can get a copy of the generic `index.php` file from `vendor/silverstripe/recipe-core/public`. If you've made modifications to your `index.php` file, you'll need to replicate those into the new `public/index.php` file.
|
||||
|
||||
### Finalising the web root migration
|
||||
You'll need to update your server configuration to point to the public directory rather than the root of your project.
|
||||
Update your `.gitignore` file so `assets` and `_resources` (or `resources` if using a pre SilverStripe 4.4 release) are still ignored when located under the `public` folder.
|
||||
Update your `.gitignore` file so `assets` and `_resources` (or `resources` if using a pre Silverstripe CMS 4.4 release) are still ignored when located under the `public` folder.
|
||||
Your project should still be functional, although you may now be missing some static assets.
|
||||
|
||||
This is a good point to commit your changes to your source control system before moving on to the next step.
|
||||
|
||||
## Step 9 - Move away from hardcoded paths for referencing static assets {#step9}
|
||||
|
||||
SilverStripe 4 introduces a new way to reference static assets like images and css.
|
||||
This enables innovations like moving the SilverStripe module [vendor folder](/changelogs/4.0.0#vendor-folder) or the [public web root](/changelogs/4.1.0#public-folder).
|
||||
Silverstripe CMS 4 introduces a new way to reference static assets like images and css.
|
||||
This enables innovations like moving the Silverstripe CMS module [vendor folder](/changelogs/4.0.0#vendor-folder) or the [public web root](/changelogs/4.1.0#public-folder).
|
||||
|
||||
This change is mandatory if you've completed either
|
||||
[step 7](#step7) (update project structure) or [step 8](#step8) (switch to public web-root).
|
||||
@ -1187,7 +1187,7 @@ class MyCustomModelAdmin extends \SilverStripe\Admin\ModelAdmin
|
||||
```
|
||||
|
||||
### Referencing static assets in template files
|
||||
SilverStripe template files accept a similar format for referencing static assets. You will need to go through your assets files and remove hardcoded references.
|
||||
Silverstripe CMS template files accept a similar format for referencing static assets. You will need to go through your assets files and remove hardcoded references.
|
||||
|
||||
```html
|
||||
<img src="$resourceURL(app/images/coyote.png)" />
|
||||
@ -1227,7 +1227,7 @@ Run a `dev/build` either on the command line or in your browser.
|
||||
./vendor/bin/sake dev/build
|
||||
```
|
||||
|
||||
This should migrate your existing data (non-destructively) to the new SilverStripe 4 structure.
|
||||
This should migrate your existing data (non-destructively) to the new Silverstripe CMS 4 structure.
|
||||
|
||||
#### Migrating files
|
||||
|
||||
|
@ -1,23 +1,23 @@
|
||||
---
|
||||
title: Upgrading a module
|
||||
summary: Upgrade your module to be compatible with SilverStripe 4 and make it easy for your users to upgrade.
|
||||
summary: Upgrade your module to be compatible with Silverstripe CMS 4 and make it easy for your users to upgrade.
|
||||
---
|
||||
|
||||
# Upgrading a module to be compatible with SilverStripe 4
|
||||
# Upgrading a module to be compatible with Silverstripe CMS 4
|
||||
|
||||
This guide will help you upgrade a SilverStripe 3 module to be compatible with SilverStripe 4.
|
||||
This guide will help you upgrade a Silverstripe CMS 3 module to be compatible with Silverstripe CMS 4.
|
||||
|
||||
You should be familiar with [Upgrading a project to SilverStripe 4](upgrading_project) before reading this guide. The process for upgrading a SilverStripe module is very similar to the process for Upgrading a SilverStripe project. This guide focuses on highlighting ways in which upgrading a module differs from upgrading a regular project.
|
||||
You should be familiar with [Upgrading a project to Silverstripe CMS 4](upgrading_project) before reading this guide. The process for upgrading a Silverstripe CMS module is very similar to the process for Upgrading a Silverstripe CMS project. This guide focuses on highlighting ways in which upgrading a module differs from upgrading a regular project.
|
||||
|
||||
## Improving the upgrade experience of your users with a ".upgrade.yml" file {#upgradeyml}
|
||||
|
||||
Making your module compatible with SilverStripe 4 is only one part of the process. As a module maintainer, you also want to provide a good upgrade experience for your users. Your module can integrate with the [SilverStripe upgrader](https://github.com/silverstripe/silverstripe-upgrader) just like the SilverStripe core modules.
|
||||
Making your module compatible with Silverstripe CMS 4 is only one part of the process. As a module maintainer, you also want to provide a good upgrade experience for your users. Your module can integrate with the [Silverstripe CMS upgrader](https://github.com/silverstripe/silverstripe-upgrader) just like the Silverstripe CMS core modules.
|
||||
|
||||
Your SilverStripe 4 module should ship with a `.upgrade.yml` file. This file is read by the upgrader and will define new APIs introduced by the upgraded version of your module. Each step in this guide details what entry you should add to your module's `.upgrade.yml` file.
|
||||
Your Silverstripe CMS 4 module should ship with a `.upgrade.yml` file. This file is read by the upgrader and will define new APIs introduced by the upgraded version of your module. Each step in this guide details what entry you should add to your module's `.upgrade.yml` file.
|
||||
|
||||
## Step 0 - Branching off your project
|
||||
|
||||
You'll want to run your module upgrade on a dedicated development branch. While it's possible to upgrade a module from within a SilverStripe project, it's usually cleaner and easier to clone your module and work directly on it.
|
||||
You'll want to run your module upgrade on a dedicated development branch. While it's possible to upgrade a module from within a Silverstripe CMS project, it's usually cleaner and easier to clone your module and work directly on it.
|
||||
|
||||
```bash
|
||||
# We're assumming that the default branch of you module is the latest SS3 compatible branch
|
||||
@ -28,9 +28,9 @@ git checkout -b pulls/ss4-upgrade
|
||||
git push origin pulls/ss4-upgrade --set-upstream
|
||||
```
|
||||
|
||||
If you're planning to keep supporting the SilverStripe 3 version of your module, consider creating a dedicated SilverStripe 3 branch.
|
||||
If you're planning to keep supporting the Silverstripe CMS 3 version of your module, consider creating a dedicated Silverstripe CMS 3 branch.
|
||||
|
||||
To require the development branch of your module in a SilverStripe 4 project, you can use composer and prefix the name the name of your branch with `dev-`.
|
||||
To require the development branch of your module in a Silverstripe CMS 4 project, you can use composer and prefix the name the name of your branch with `dev-`.
|
||||
|
||||
```bash
|
||||
composer require example-user/silverstripe-example-module dev-pulls/ss4-upgrade
|
||||
@ -54,15 +54,15 @@ If the development branch is hosted on a different Git remote than the one used
|
||||
}
|
||||
```
|
||||
|
||||
You will not be able to install your development branch in a SilverStripe 4 project until you've adjusted your module's dependencies.
|
||||
You will not be able to install your development branch in a Silverstripe CMS 4 project until you've adjusted your module's dependencies.
|
||||
|
||||
## Step 1 - Upgrade your dependencies
|
||||
|
||||
Before you can install your module in a SilverStripe 4 project, you must update your module's `composer.json` file to require SilverStripe 4 compatible dependencies. In most cases, you'll be better off updating your module's composer file manually, especially if your module only requires a small number of dependencies. You can use upgrader's `recompose` command if you want, but you'll need to carefully validate the resulting `composer.json` file.
|
||||
Before you can install your module in a Silverstripe CMS 4 project, you must update your module's `composer.json` file to require Silverstripe CMS 4 compatible dependencies. In most cases, you'll be better off updating your module's composer file manually, especially if your module only requires a small number of dependencies. You can use upgrader's `recompose` command if you want, but you'll need to carefully validate the resulting `composer.json` file.
|
||||
|
||||
### Update module's type
|
||||
|
||||
SilverStripe 4 modules are now installed inside the vendor directory. To get your module installed in the vendor directory, you'll need to update its `type` to `silverstripe-vendormodule`. You'll also need to add a dependency to `silverstripe/vendor-plugin`.
|
||||
Silverstripe CMS 4 modules are now installed inside the vendor directory. To get your module installed in the vendor directory, you'll need to update its `type` to `silverstripe-vendormodule`. You'll also need to add a dependency to `silverstripe/vendor-plugin`.
|
||||
|
||||
```diff
|
||||
{
|
||||
@ -81,11 +81,11 @@ SilverStripe 4 modules are now installed inside the vendor directory. To get you
|
||||
|
||||
When upgrading a project, it is recommended to require recipes rather than modules. However, when upgrading a module, you want to limit the number of additional packages that gets installed along with your module. You should target specific packages that your module depends on.
|
||||
|
||||
For example, let's say your module adds a ModelAdmin to the SilverStripe administration area without interacting with the CMS directly. In this scenario, the main module you need is `silverstripe/admin` which contains the `ModelAdmin` class and related administration functionality. If you update your `composer.json` file to require `silverstripe/recipe-cms`, you'll force your users to install a lot of modules they may not need like `silverstripe/cms`, `silverstripe/campaign-admin`, `silverstripe/asset-admin`, `silverstripe/versioned-admin`.
|
||||
For example, let's say your module adds a ModelAdmin to the Silverstripe CMS administration area without interacting with the CMS directly. In this scenario, the main module you need is `silverstripe/admin` which contains the `ModelAdmin` class and related administration functionality. If you update your `composer.json` file to require `silverstripe/recipe-cms`, you'll force your users to install a lot of modules they may not need like `silverstripe/cms`, `silverstripe/campaign-admin`, `silverstripe/asset-admin`, `silverstripe/versioned-admin`.
|
||||
|
||||
### Avoid rigid constraints
|
||||
|
||||
Choose constraints based on the minimum version of SilverStripe 4 you are planning on supporting and allow your module to work with future releases.
|
||||
Choose constraints based on the minimum version of Silverstripe CMS 4 you are planning on supporting and allow your module to work with future releases.
|
||||
|
||||
For example, if your module requires an API that got introduced with the 4.1 release of `silverstripe/framework`, then that's the version you should target. You should use the caret symbol (`^`) over the tilde (`~`) so your module works with more recent releases. In this scenario, your constraint should look like `"silverstripe/framework": "^4.1"`.
|
||||
|
||||
@ -99,7 +99,7 @@ While these changes may be useful for testing, they should not be part of the fi
|
||||
|
||||
You should commit the changes to your module's `composer.json` and push them to your remote branch.
|
||||
|
||||
By this point, your module should be installable in a test SilverStripe 4 project. It will be installed under the vendor directory (e.g.: `vendor/example-user/silverstripe-example-module`). However, it will throw exceptions if you try to run it.
|
||||
By this point, your module should be installable in a test Silverstripe CMS 4 project. It will be installed under the vendor directory (e.g.: `vendor/example-user/silverstripe-example-module`). However, it will throw exceptions if you try to run it.
|
||||
|
||||
From this point, you can either work from a test project or you can keep working directly on your module.
|
||||
|
||||
@ -109,7 +109,7 @@ As a module maintainer, you shouldn't be shipping any environment file with your
|
||||
|
||||
## Step 3 - Namespacing your module
|
||||
|
||||
Namespacing your module is mandatory to get it working with SilverStripe 4. You can use the `add-namespace` upgrader command to achieve this.
|
||||
Namespacing your module is mandatory to get it working with Silverstripe CMS 4. You can use the `add-namespace` upgrader command to achieve this.
|
||||
|
||||
```bash
|
||||
# If you are working from a test project, you need to specify the `--root-dir` parameter
|
||||
@ -186,7 +186,7 @@ By this point:
|
||||
* your `composer.json` file should have an autoload definition
|
||||
* you should have a `.upgrade.yml` file.
|
||||
|
||||
However, your codebase is still referencing SilverStripe classes by their old non-namespaced names. Commit your changes before proceeding to the next step.
|
||||
However, your codebase is still referencing Silverstripe CMS classes by their old non-namespaced names. Commit your changes before proceeding to the next step.
|
||||
|
||||
## Step 4 - Update codebase with references to newly namespaced classes
|
||||
|
||||
@ -205,7 +205,7 @@ All references to the old class names will be replaced with namespaced class nam
|
||||
|
||||
By this point, you should be able to load your module with PHP. However, your module will be using deprecated APIs.
|
||||
|
||||
## Step 5 - Updating your codebase to use SilverStripe 4 API
|
||||
## Step 5 - Updating your codebase to use Silverstripe CMS 4 API
|
||||
|
||||
This step will allow you to update references to deprecated APIs. If you are planning on making changes to your own module's API, take a minute to define those changes in your `.upgrade.yml`:
|
||||
* this will help you with updating your own codebase
|
||||
@ -256,7 +256,7 @@ The public web root does not directly affect module. So you can skip this step.
|
||||
|
||||
## Step 9 - Move away from hardcoded paths for referencing static assets
|
||||
|
||||
While SilverStripe 4 projects can get away with directly referencing static assets under some conditions, modules must dynamically expose their static assets. This is necessary to move modules to the vendor folder and to enable the public web root.
|
||||
While Silverstripe CMS 4 projects can get away with directly referencing static assets under some conditions, modules must dynamically expose their static assets. This is necessary to move modules to the vendor folder and to enable the public web root.
|
||||
|
||||
### Exposing your module's static assets
|
||||
|
||||
@ -324,10 +324,10 @@ You've been through all the steps covered in the regular project upgrade guide.
|
||||
|
||||
### Create migration tasks
|
||||
|
||||
Depending on the nature of your module, you might need to perform additional tasks to complete the upgrade process. For example, the `framework` module ships with a file migration task that converts files from the old SilverStripe 3 structure to the new structure required by SilverStripe 4.
|
||||
Depending on the nature of your module, you might need to perform additional tasks to complete the upgrade process. For example, the `framework` module ships with a file migration task that converts files from the old Silverstripe CMS 3 structure to the new structure required by Silverstripe CMS 4.
|
||||
|
||||
Extend [BuildTask](api:SilverStripe/Dev/BuildTask)s and create your own migration task if your module requires post-upgrade work. Document this clearly for your users so they know they need to run the task after they're done upgrading their project.
|
||||
|
||||
### Keep updating your `.upgrade.yml`
|
||||
|
||||
The upgrader can be run on projects that have already been upgraded to SilverStripe 4. As you introduce new API and deprecate old ones, you can keep updating your `.upgrade.yml` file to make it easy for your users to keep their code up to date. If you do another major release of your module aimed at SilverStripe 4, you can use all the tools in the upgrader to make the upgrade process seamless for your users.
|
||||
The upgrader can be run on projects that have already been upgraded to Silverstripe CMS 4. As you introduce new API and deprecate old ones, you can keep updating your `.upgrade.yml` file to make it easy for your users to keep their code up to date. If you do another major release of your module aimed at Silverstripe CMS 4, you can use all the tools in the upgrader to make the upgrade process seamless for your users.
|
||||
|
@ -1,8 +1,8 @@
|
||||
---
|
||||
title: Upgrading
|
||||
summary: The following guides will help you upgrade your project or module to SilverStripe 4.
|
||||
summary: The following guides will help you upgrade your project or module to Silverstripe CMS 4.
|
||||
---
|
||||
|
||||
The following guides will help you upgrade your project or module to SilverStripe 4. Upgrading a module is very similar to upgrading a Project. The module upgrade guide assumes familiarity with the project upgrade guide.
|
||||
The following guides will help you upgrade your project or module to Silverstripe CMS 4. Upgrading a module is very similar to upgrading a Project. The module upgrade guide assumes familiarity with the project upgrade guide.
|
||||
|
||||
[CHILDREN]
|
||||
|
Loading…
Reference in New Issue
Block a user