From 1fceb74a9d8ba215f23d56db54361ecca1df504f Mon Sep 17 00:00:00 2001
From: Robert-Frampton <ROBERT.FRAMPTON@LIFERAY.COM>
Date: Fri, 6 Oct 2017 10:33:19 -0700
Subject: [PATCH] Document lifecycle changes. Documents metal/metal.js#255

---
 src/pages/docs/guides/component-lifecycle.md | 171 ++++++++++++++++++-
 1 file changed, 170 insertions(+), 1 deletion(-)

diff --git a/src/pages/docs/guides/component-lifecycle.md b/src/pages/docs/guides/component-lifecycle.md
index c7982a29..9b461d9f 100644
--- a/src/pages/docs/guides/component-lifecycle.md
+++ b/src/pages/docs/guides/component-lifecycle.md
@@ -22,10 +22,44 @@ class MyComponent extends Component {
     created() {
     }
 
+    /**
+     * Soy components only.
+     *
+     * Called when state data is about to be passed to the component's renderer.
+     * @param {!object} changes object literal with info on state changes.
+     */
+    willReceiveState(changes) {
+    }
+
+    /**
+     * JSX components only.
+     *
+     * Called when props data is about to be passed to the component's renderer.
+     * @param {!object} changes object literal with info on props changes.
+     */
+    willReceiveProps(changes) {
+    }
+
+    /**
+     * Called before the component will render.
+     * @param {boolean} firstRender Flag indicating if this was the component's
+	 *     first render.
+     */
+    willRender(firstRender) {
+    }
+
     /**
      * Called whenever the component is rendered.
+     * @param {boolean} firstRender Flag indicating if this was the component's
+	 *     first render.
      */
-    rendered() {
+    rendered(firstRender) {
+    }
+
+    /**
+     * Called before the component is about to attach to the DOM.
+     */
+    willAttach() {
     }
 
     /**
@@ -41,6 +75,12 @@ class MyComponent extends Component {
     attached() {
     }
 
+    /**
+     * Called before the component is about to detach from the DOM.
+     */
+    willDetach() {
+    }
+
     /**
      * Called when the component is detached from the
      * DOM. The component will automatically be
@@ -76,4 +116,133 @@ class MyComponent extends Component {
 }
 ```
 
+</article>
+
+<article id="will_receive_state">
+
+## [willReceiveState - Soy](#will_receive_state)
+
+The `willReceiveState` lifecycle method allows for hooking into the state
+lifecycle of Soy components. Let's take the following component for example.
+
+```javascript
+import Component from 'metal-component';
+import Soy from 'metal-soy';
+
+import templates from './MySoyComponent.soy';
+
+class MySoyComponent extends Component {
+    willReceiveState(changes) {
+        if (changes.foo && changes.foo.newVal !== changes.foo.prevVal) {
+            // This will available in the next render
+            this.bar = 'bar1';
+        }
+    }
+}
+
+MySoyComponent.STATE = {
+    foo: {
+        value: 'foo'
+    },
+
+    bar: {
+        value: 'bar'
+    }
+};
+
+Soy.register(MySoyComponent, templates);
+export default MySoyComponent;
+```
+```soy
+&#123;namespace MySoyComponent&#125;
+
+/**
+ *
+ */
+&#123;template. render&#125;
+    {@param foo: string}
+    {@param bar: string}
+
+    <div>{$foo}:{$bar}</div>
+&#123;/template&#125;
+```
+
+If we render this component and change the value of the `foo` state, the
+`willReceiveState` method will be invoked before the component renders allowing
+us to also set the value of other state values that will also be passed to the
+next render.
+
+```javascript
+import MySoyComponent from './MySoyComponent';
+
+const component = new MySoyComponnet();
+
+component.foo = 'foo1';
+
+component.once('rendered', function() {
+    console.log(component.element.innerHTML);
+
+    // component.element.innerHTML === 'foo1:bar1';
+});
+```
+
+</article>
+
+<article id="will_receive_props">
+
+## [willReceiveProps - JSX](#will_receive_props)
+
+The `willReceiveProps` lifecycle method allows for hooking into the props
+lifecycle of JSX components. Let's take the following JSX component for example.
+
+```javascript
+import JSXComponent from 'metal-jsx';
+
+class MyJSXComponent extends JSXComponent {
+    render() {
+        return <div>{this.props.foo}:{this.state.bar}</div>
+    }
+
+    willReceiveProps(changes) {
+        if (changes.foo && changes.foo.newVal !== changes.foo.prevVal) {
+            // This will available in the next render
+            this.state.bar = 'bar1';
+        }
+    }
+}
+
+MyJSXComponent.STATE = {
+    bar: {
+        value: 'bar'
+    }
+};
+
+MyJSXComponent.PROPS = {
+    foo: {
+        value: 'foo'
+    }
+};
+
+export default MyJSXComponent;
+```
+
+If we render this component and change the value of the `foo` prop, the
+`willReceiveProps` method will be invoked before the component renders allowing
+us to also set the value of internal state values that will also be passed to
+the next render.
+
+```javascript
+import MyJSXComponent from './MyJSXComponent';
+
+const component = new MyJSXComponent();
+
+component.props.foo = 'foo1';
+
+component.once('rendered', function() {
+    console.log(component.element.innerHTML);
+
+    // component.element.innerHTML === 'foo1:bar1';
+});
+```
+
 </article>
\ No newline at end of file