All files / ima/extension Extension.js

100% Statements 2/2
0% Branches 0/2
50% Functions 6/12
100% Lines 2/2
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177    4x                                                                                                                                                                                                                                                                                                                                                         4x  
import ns from '../namespace';
 
ns.namespace('ima.extension');
 
/**
 * Extensions provide means of extending the page controllers with additional
 * managed state and logic.
 *
 * An extension has access to the current route parameters, specify the
 * resources to load when the page is loading or being updated, may intercept
 * event bus events and modify the state of the page just like an ordinary
 * controller, except that the modifications are restricted to the state fields
 * which the extension explicitly specifies using its
 * {@linkcode getAllowedStateKeys()} method.
 *
 * All extensions to be used on a page must be added to the current controller
 * before the controller is initialized. After that, the extensions will go
 * through the same lifecycle as the controller.
 *
 * @interface
 */
export default class Extension {
  /**
	 * Callback for initializing the controller extension after the route
	 * parameters have been set on this extension.
	 */
  init() {}
 
  /**
	 * Finalization callback, called when the controller is being discarded by
	 * the application. This usually happens when the user navigates to a
	 * different URL.
	 *
	 * This method is the lifecycle counterpart of the {@linkcode init()}
	 * method.
	 *
	 * The extension should release all resources obtained in the
	 * {@codelink init()} method. The extension must release any resources
	 * that might not be released automatically when the extensions's instance
	 * is destroyed by the garbage collector.
	 */
  destroy() {}
 
  /**
	 * Callback for activating the extension in the UI. This is the last
	 * method invoked during controller (and extensions) initialization, called
	 * after all the promises returned from the {@codelink load()} method have
	 * been resolved and the controller has configured the meta manager.
	 *
	 * The extension may register any React and DOM event listeners in this
	 * method. The extension may start receiving event bus event after this
	 * method completes.
	 */
  activate() {}
 
  /**
	 * Callback for deactivating the extension in the UI. This is the first
	 * method invoked during extension deinitialization. This usually happens
	 * when the user navigates to a different URL.
	 *
	 * This method is the lifecycle counterpart of the {@linkcode activate()}
	 * method.
	 *
	 * The extension should deregister listeners registered and release all
	 * resources obtained in the {@codelink activate()} method.
	 */
  deactivate() {}
 
  /**
	 * Callback the extension uses to request the resources it needs to render
	 * its related parts of the view. This method is invoked after the
	 * {@codelink init()} method.
	 *
	 * The extension should request all resources it needs in this method, and
	 * represent each resource request as a promise that will resolve once the
	 * resource is ready for use (these can be data fetched over HTTP(S),
	 * database connections, etc).
	 *
	 * The method must return a plain flat object. The field names of the
	 * object identify the resources being fetched and prepared, each value
	 * must be either the resource (e.g. view configuration or a value
	 * retrieved synchronously) or a Promise that will resolve to the resource.
	 *
	 * The IMA will use the object to set the state of the controller.
	 *
	 * Any returned promise that gets rejected will redirect the application to
	 * the error page. The error page that will be used depends on the status
	 * code of the error.
	 *
	 * @return {Object<string, (Promise|*)>} A map object of promises
	 *         resolved when all resources the extension requires are ready.
	 *         The resolved values will be pushed to the controller's state.
	 */
  load() {}
 
  /**
	 * Callback for updating the extension after a route update. This method
	 * is invoked if the current route has the {@code onlyUpdate} flag set to
	 * {@code true} and the current controller and view match those used by the
	 * previously active route, or, the {@code onlyUpdate} option of the
	 * current route is a callback and returned {@code true}.
	 *
	 * The method must return an object with the same semantics as the result
	 * of the {@codelink load()} method. The controller's state will then be
	 * patched by the returned object.
	 *
	 * The other extension lifecycle callbacks ({@codelink init()},
	 * {@codelink load()}, {@codelink activate()}, {@codelink deactivate()},
	 * {@codelink deinit()}) are not call in case this method is used.
	 *
	 * @param {Object<string, string>=} [prevParams={}] Previous route
	 *        parameters.
	 * @return {Object<string, (Promise|*)>} A map object of promises
	 *         resolved when all resources the extension requires are ready.
	 *         The resolved values will be pushed to the controller's state.
	 */
  update(prevParams = {}) {}
 
  /**
	 * Patches the state of the controller using this extension by using the
	 * provided object by copying the provided patch object fields to the
	 * controller's state object.
	 *
	 * Note that the state is not patched recursively but by replacing the
	 * values of the top-level fields of the state object.
	 *
	 * Note that the extension may modify only the fields of the state that it
	 * has specified by its {@linkcode getAllowedStateKeys} method.
	 *
	 * @param {Object<string, *>} statePatch Patch of the controller's state to
	 *        apply.
	 */
  setState(statePatch) {}
 
  /**
	 * Returns the current state of the controller using this extension.
	 *
	 * @return {Object<string, *>} The current state of the controller.
	 */
  getState() {}
 
  /**
	 * Sets the state manager used to manage the controller's state..
	 *
	 * @param {?PageStateManager} pageStateManager The current state manager to
	 *        use.
	 */
  setPageStateManager(pageStateManager) {}
 
  /**
	 * Sets the current route parameters. This method is invoked before the
	 * {@code init()} method.
	 *
	 * @param {Object<string, string>} [params={}] The current route
	 *        parameters.
	 */
  setRouteParams(params = {}) {}
 
  /**
	 * Returns the current route parameters.
	 *
	 * @return {Object<string, string>} The current route parameters.
	 */
  getRouteParams() {}
 
  /**
	 * Returns the names of the state fields that may be manipulated by this
	 * extension. Manipulations of other fields of the state will be ignored.
	 *
	 * @return {string[]} The names of the state fields that may be manipulated
	 *         by this extension.
	 */
  getAllowedStateKeys() {}
}
 
ns.ima.extension.Extension = Extension;