tonyair
/
silverstripe-framework
mirror of https://github.com/silverstripe/silverstripe-framework
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #7076 from open-sausages/pulls/4.0/resource-loading-upgrade-docs 

Docs for resource loading upgrade path
This commit is contained in:
Damian Mooyman 2017-06-30 09:27:29 +12:00 committed by GitHub
parent ad9d4e6820 24957418ed
commit ac4a6c06a7
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.
* 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.
* 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.
* 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.
@ -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
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
The below sections deal with upgrades to specific parts of various API. Projects which rely on certain