Update and modernise README (#127)

* docs: update supported versions of Ember.js * docs: update supported versions of Node.js * docs: limit lines at 100 characters maximum * docs: set better language context to code blocks * docs: update and modernise code examples * docs: reword section about `ember-export-application-global` * docs: add a new example when `APP` gets altered * docs: update section about test environment * docs: reword section of introduction
DazzlingFugu · Sep 10, 2021 · 37c2e03 · 37c2e03
1 parent 1e6e320
commit 37c2e03
Showing 1 changed file with 133 additions and 48 deletions.
diff --git a/README.md b/README.md
@@ -4,109 +4,194 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 
-Makes it easier to embed your Ember application in another
-(non-Ember) app.
+Makes it easier to embed your Ember application in another (non-Ember) app.
 
-This addon gives you more control over how and when your
-Ember app will boot and also allows to add/override some
-configuration, so that the Ember app can boot with some
-context-dependent config.
+This addon gives you more control over how and when your Ember app will boot and also allows to 
+add/override some configuration, so that the Ember app can boot with some context-dependent config.
 
 We found it especially useful, for example, when migrating an existing app to Ember part by part.
 
 
 ## Compatibility
 
-- Ember.js v3.16 or above
-- Ember CLI v2.13 or above
-- Node.js v10 or above
+- Ember.js v3.20 or above
+- Ember CLI v3.20 or above
+- Node.js v12 or above
 
 
 ## Usage
 
 ### Installation
 
-```
+```console
 ember install ember-cli-embedded
 ```
 
 
 ### Configuration
 
-This plugin is opt-in by default, it does nothing to your app unless
-you configure it.
+This plugin is opt-in by default, it does nothing to your app unless you configure it.
 
 In your `config/environment.js`, add the following config to the `ENV`:
 
 ```js
-  modulePrefix: 'my-app' // name of your application
-  exportApplicationGlobal: true, // exposes your application in production builds 
-  ...
-  embedded: {
-    delegateStart: true,
-    config: { // `config` is optional
-      // Default values for the config passed at boot
-    }
-  }
+  let ENV = {
+    ...
+    embedded: {
+      delegateStart: true,
+      config: { // optional
+        // Default values for the config passed at boot
+      },
+    },
+    ...
+  };
 ```
 
-> For compatibility reasons, as long as the value for `embedded` is truthy, your app will hold
-until you start it. This behaviour will be removed in future versions.
-Please stick to the config format above.
+Doing so will make your application hold, until your manually start it. (read on to lear more)
+
+> For compatibility reasons, this behaviour will work as long as the value of `embedded` is truthy
+> but we plan to remove it in a future version.  
+> Please stick to the config format above.
 
 
 ### Start your app
 
 This addon relies on [ember-export-application-global](https://github.com/ember-cli/ember-export-application-global)
-to expose a global variable. By default, it exposes your app under
-its capitalized name, _eg._ `MyApp`. See its documentation for
-more configuration information.
+to get your application globally exposed. See its documentation for more information.
 
-In your JS code, just execute `MyApp.start(/* optionalConfig */)` to resume
-the boot of your application. As per the example, it takes an optional
-configuration as its first argument.
+In your JS code, just execute `MyApp.start(/* optionalConfig */)` to resume the boot of your 
+application. As per the example, it takes an optional configuration as its first argument.
 
-Remember: Your app __will not start__ unless you call the `MyApp.start(/* optionalConfig */)`
-method.
+Remember:
+Your app __will not start__ unless you call the `MyApp.start(/* optionalConfig */)` method.
 
 
-### Access the config from your app
+### Access the config from your application
 
-You can inject the `embedded` service to access the config:
+#### Via the Service `embedded`
 
+Consider the following `config/environment.js` file:
+
+```js
+  let ENV = {
+    ...
+    embedded: {
+      config: {
+        option1: 'value-1',
+      },
+    },
+    ...
+  };
+```
+
+And the application is started that way:
+
+```js
+<script>
+  MyApp.start({ option2: 'value-2' });
+</script>
 ```
-EmberObject.extend({
-  embedded: service(),
 
+Then in your Services, Components, Controllers...
+
+```js
+class MyService extends Service {
+  @service embedded;
+
+  @action
   logSomeConfigKey() {
-    const value = this.get('embedded.myKey')
-    console.log(value)
+    // Will log 'value-1'
+    console.log(this.embedded.option1);
   }
-})
+}
 ```
 
-Note: It is sometimes more convenient to access the data from the container directly:
+
+#### Via the container itself
+
+Sometimes it can be more convenient to access the data directly from the container.
+
+Following the previous example:
 
 ```js
+import { getOwner } from '@ember/application';
+
+...
+
 // Returns the raw config
-let embeddedConfig = Ember.getOwner(this).lookup('config:embedded')
+let embeddedConfig = getOwner(this).lookup('config:embedded');
+
+// Will log 'value-2'
+console.log(embeddedConfig.option2);
 ```
 
 
 ### Override your `APP` configuration
 
-The passed configuration will be merged in your `APP` configuration key,
-which is very useful, for instance, if you want to change the `rootElement`
-of your application and other context-sensitive values.
+The startup object will be merged into your `APP` configuration key, which is very useful, for 
+instance, if you want to change the `rootElement` of your application and other context-sensitive
+values.
+
+Consider the following `config/environment.js` file:
+
+```js
+  let ENV = {
+    APP: {
+      rootElement: `#some-element`,
+    },
+
+    embedded: {
+      config: {
+        option1: 'value-1',
+      },
+    },
+  };
+```
+
+And the application is started that way:
+
+```js
+<script>
+  MyApp.start({ option2: 'value-2' });
+</script>
+```
+
+This would result in:
+
+```js
+import APP_ENV_CONFIG from 'my-app/config/environment'
+
+assert.deepEqual(
+  APP_ENV_CONFIG,
+  {
+    APP: {
+      option2: 'value-2',
+      rootElement: `#some-element`,
+    },
+
+    embedded: {
+      config: {
+        option1: 'value-1',
+      },
+    },
+  }
+);
+```
+
 
+### About the test environment
 
-### Testing in Ember 3.x
+In your tests suite, you will probably want to let your application start automatically without this
+addon interfering.
 
-Make sure that, in your `config/environment.js`, you disable the addon for the
-`test` environment, with the following:
+To do that, make sure to disable the addon for the `test` environment:
 
 ```js
-ENV.embedded.delegateStart = false
+// file `config/environment.js`
+
+if (environment === 'test') {
+  ENV.embedded.delegateStart = false;
+}
 ```