extensions/structure - Document the big E

docs/extensions/structure.md

@@ -31,3 +31,50 @@ reminiscent of the directory structure in CiviCRM core:
 When adding files into these directories it is advisable to follow similar patterns to that in CiviCRM Core
 e.g. BAO files should go in "CRM\_Myextension\BAO\", likewise with Form and Page. This ensures that for developers
 that seek to modify or improve the extension files can be found in standard locations.
+
+## The Big `E`
+
+There are many times when you need to reference something from the
+extension -- e.g.  its name, its file-path, or its translated messages.
+
+For example, this code displays a translated message (using the translation
+data for this extension):
+
+```php
+if ($welcoming) {
+  CRM_Core_Session::setStatus(ts('Hello world!', array(
+    'domain' => 'org.civicrm.myextension',
+  )));
+} else {
+  CRM_Core_Session::setStatus(ts('Goodbye cruel world!', array(
+    'domain' => 'org.civicrm.myextension',
+  )));
+}
+```
+
+Repeatedly entering the name of the extension is a bit tiresome.
+
+For code generated by `civix` v17.08.0+ (or suitably
+[upgraded](https://github.com/totten/civix/blob/master/UPGRADE.md)), `civix`
+includes the `E` helper which provides easier access:
+
+```php
+use CRM_Mymodule_ExtensionUtil as E;
+
+if ($welcoming) {
+  CRM_Core_Session::setStatus(E::ts('Hello world!'));
+} else {
+  CRM_Core_Session::setStatus(E::ts('Goodbye cruel world!'));
+}
+```
+
+Note that `E` is an alias.  It stands for "extension" -- as in "the current
+extension that I'm writing".  It's a very thin class that provides small
+helpers for looking up your extension's resources, e.g.
+
+ * `E::ts($text)` -- Translate a string (using the extensions' translation file)
+ * `E::path($file)` -- Get the path to a resource file (within this extension)
+ * `E::url($file)` -- Get the URL to a resource file (within this extension)
+ * `E::findClass($suffix)` -- Get the full name of a class (within this extension)
+ * `E::LONG_NAME` -- The full length key for this extension (eg `org.example.myextension`)
+ * `E::SHORT_NAME` -- The abbreviated key for this extension (eg `myextension`)