From 24957418ed2dc79a3968b558ef5efd05b33231a3 Mon Sep 17 00:00:00 2001
From: Ingo Schommer <me@chillu.com>
Date: Wed, 28 Jun 2017 22:04:34 +1200
Subject: [PATCH] Docs for resource loading upgrade path

See https://github.com/silverstripe/silverstripe-framework/pull/7065
---
 docs/en/04_Changelogs/4.0.0.md | 59 ++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/docs/en/04_Changelogs/4.0.0.md b/docs/en/04_Changelogs/4.0.0.md
index 119ee95af..3ddb4fda4 100644
--- a/docs/en/04_Changelogs/4.0.0.md
+++ b/docs/en/04_Changelogs/4.0.0.md
@@ -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