tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-09-28 12:26:23 +02:00
Code Issues Projects Releases Wiki Activity

Docs for resource loading upgrade path

Browse Source 
See https://github.com/silverstripe/silverstripe-framework/pull/7065
This commit is contained in:
Ingo Schommer 2017-06-28 22:04:34 +12:00
parent 977c62a513
commit 24957418ed
1 changed files with 59 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -50,6 +50,7 @@ guide developers in preparing existing 3.x code for compatibility with 4.0
unless explicitly opted out. unless explicitly opted out.
* Themes are now configured to cascade, where you can specify a list of themes, and have the template engine * Themes are now configured to cascade, where you can specify a list of themes, and have the template engine
search programatically through a prioritised list when resolving template and CSS file paths. search programatically through a prioritised list when resolving template and CSS file paths.
* Removed module path constants (e.g. `FRAMWORK_PATH`) and support for hardcoded file paths (e.g. `mysite/css/styles.css`)
* i18n Updated to use symfony/translation over zend Framework 1. Zend_Translate has been removed. * i18n Updated to use symfony/translation over zend Framework 1. Zend_Translate has been removed.
* Replaced `Zend_Cache` and the `Cache` API with a PSR-16 implementation (symfony/cache) * Replaced `Zend_Cache` and the `Cache` API with a PSR-16 implementation (symfony/cache)
* _ss_environment.php files have been removed in favour of `.env` and "real" environment variables. * _ss_environment.php files have been removed in favour of `.env` and "real" environment variables.
@ -108,6 +109,64 @@ Core template locations have moved - if you're including or overriding these
no longer exists, and instead template locations will be placed in paths that match no longer exists, and instead template locations will be placed in paths that match
the `SilverStripe\Forms` namespace. the `SilverStripe\Forms` namespace.
#### Upgrade module paths in file references
You should no longer rely on modules being placed in a deterministic folder (e.g. `/framework`),
and use getters on the [Module](api:SilverStripe\Core\Manifest\Module) object instead.
They expect a module composer name, followed by the module relative path, separated by a double colon.
This prepares SilverStripe for moving modules out of the webroot at a later point.
Usage in templates:
```ss
<!-- before -->
<img src="framework/images/image.png" />
<% require css("framework/css/styles.css") %>
<!-- after -->
<img src="$ModulePath(silverstripe/framework)/image.png" />
<% require css("silverstripe/framework: css/styles.css") %>
```
Usage in Requirements:
```php
// before
Requirements::css('framework/css/styles.css');
// after
Requirements::css('silverstripe/framework: css/styles.css');
```
Usage with custom logic:
```php
// before
$moduleFilePath = FRAMEWORK_DIR . '/MyFile.php';
$baseFilePath = BASE_PATH . '/composer.json';
$mysiteFilePath = 'mysite/css/styles.css';
$themesFilePath = SSViewer::get_theme_folder() . '/css/styles.css';
$themeFolderPath = THEMES_DIR . '/simple';
// after
use SilverStripe\Core\Manifest\ModuleLoader;
use SilverStripe\View\ThemeResourceLoader;
$moduleFilePath = ModuleLoader::getModule('silverstripe/framework')->getRelativeResourcePath('MyFile.php');
$baseFilePath = Director::baseFolder() . '/composer.json';
$mysiteFilePath = ModuleLoader::getModule('mysite')->getRelativeResourcePath('css/styles.css');
$themesFilePath = ThemeResourceLoader::inst()->findThemedResource('css/styles.css');
$themeFolderPath = ThemeResourceLoader::inst()->getPath('simple');
```
To ensure consistency, we've also deprecated support for path constants:
* `FRAMEWORK_DIR` and `FRAMEWORK_PATH`
* `FRAMEWORK_ADMIN_DIR` and `FRAMEWORK_ADMIN_PATH`
* `FRAMEWORK_ADMIN_THIRDPARTY_DIR` and `FRAMEWORK_ADMIN_THIRDPARTY_PATH`
* `THIRDPARTY_DIR` and `THIRDPARTY_PATH`
* `CMS_DIR` and `CMS_PATH`
* `THEMES_DIR` and `THEMES_PATH`
### <a name="upgrading-specifics"></a>API Specific Upgrades ### <a name="upgrading-specifics"></a>API Specific Upgrades
The below sections deal with upgrades to specific parts of various API. Projects which rely on certain The below sections deal with upgrades to specific parts of various API. Projects which rely on certain