@soleil-se/app-util 3.0.3 → 4.0.1

package/README.md

@@ -1,329 +1,209 @@
-# Webapp Util
+# `@soleil-se/webapp-util@^4.0.0`
 Utility functions for Webapps.
 
+[GitHub](https://github.com/soleilit/server-monorepo/tree/master/packages/webapp-util)    
+[NPM](https://www.npmjs.com/package/@soleil-se/webapp-util)
+
 <!-- TOC -->
 
+- [Requirements](#requirements)
 - [Install](#install)
-- [Changelog](#changelog)
-- [Migration 1.x.x to 2.x.x](#migration-1xx-to-2xx)
-- [Usage](#usage)
-  - [`renderApp([config], [settings])` ⇒ `String`](#renderappconfig-settings-⇒-string)
-    - [Example](#example)
-      - [**Vue**](#vue)
-  - [`getRouteUri(route)` ⇒ `String`](#getrouteuriroute-⇒-string)
-    - [Example](#example-1)
-  - [`getViewUri(route)` ⇒ `String`](#getviewuriroute-⇒-string)
-    - [Example](#example-2)
-  - [`getResourceUri(resource)` ⇒ `String`](#getresourceuriresource-⇒-string)
-    - [Example](#example-3)
-  - [`renderTemplate(template, [values])` ⇒ `String`](#rendertemplatetemplate-values-⇒-string)
-    - [Example](#example-4)
-  - [`isOffline`](#isoffline)
-  - [`isOnline`](#isonline)
-  - [`uniqueId`](#uniqueid)
-- [AppData](#appdata)
-- [Svelte](#svelte)
-  - [Server](#server)
-    - [`render(App, [data], [settings])` ⇒ `String`](#renderapp-data-settings-⇒-string)
-    - [`renderServer(App, [data])` ⇒ `String`](#renderserverapp-data-⇒-string)
-    - [`renderClient(App, [data], [settings])` ⇒ `String`](#renderclientapp-data-settings-⇒-string)
-  - [Client](#client)
-    - [`render(App)`](#renderapp)
+- [Migration](#migration)
+- [API](#api)
+  - [Constants](#constants)
+  - [Functions](#functions)
+  - [appId : <code>String</code>](#appid--codestringcode)
+  - [isOffline : <code>Boolean</code>](#isoffline--codebooleancode)
+  - [isOnline : <code>Boolean</code>](#isonline--codebooleancode)
+  - [getNamespace([prefix]) ⇒ <code>String</code>](#getnamespaceprefix-⇒-codestringcode)
+  - [getRouteUri(route) ⇒ <code>String</code>](#getrouteuriroute-⇒-codestringcode)
+  - [getViewUri(route) ⇒ <code>String</code>](#getviewuriroute-⇒-codestringcode)
+  - [getResourceUri(resource) ⇒ <code>String</code>](#getresourceuriresource-⇒-codestringcode)
+  - [getAppData([key]) ⇒ <code>\*</code> \| <code>Object</code>](#getappdatakey-⇒-code\code-\-codeobjectcode)
+- [Rendering](#rendering)
 
 <!-- /TOC -->
 
+## Requirements
+`@soleil-se/sv-gulp-build` 4 or later (Works best with ^4.3.0).
+
 ## Install
 `yarn add @soleil-se/webapp-util`
 
-## Changelog
-[See changelog](CHANGELOG.md).
+## Migration
+Migrating from version 2 or 3?   
+See [MIGRATION](./MIGRATION.md).
 
-## Migration 1.x.x to 2.x.x
+## API
+All imports from base package are available both on the server and client.
 
-Now using `currentScript` to reference the script element the app is running in to pass data. 
+### Constants
 
-Remove appName from the `renderApp` call in `./app_src/server/index.js`.   
-Remove export of `App` and `render` and replace with a call to `render(App)` in `./app_src/client/index.js`.   
+<dl>
+<dt><a href="#appId">appId</a> : <code>String</code></dt>
+<dd><p>DOM friendly unique identifier for the WebApp.</p>
+</dd>
+<dt><a href="#isOffline">isOffline</a> : <code>Boolean</code></dt>
+<dd><p>If the WebApp is running in offline mode or not.</p>
+</dd>
+<dt><a href="#isOnline">isOnline</a> : <code>Boolean</code></dt>
+<dd><p>If the WebApp is running in online mode or not.</p>
+</dd>
+</dl>
 
-See [example](#example).
+### Functions
 
-## Usage
-```javascript
-import { renderApp, getRouteUri, getViewUri, getResourceUri, renderTemplate, isOffline, isOnline } from '@soleil-se/webapp-util';
-```
-### `renderApp([config], [settings])` ⇒ `String`
-Get HTML string for rendering a client side application.   
-Can be used together with `@soleil-se/webapp-util/render-vue`, `@soleil-se/webapp-util/svelte-client` or a custom render function in the client code. 
-
-**Returns**: <code>String</code> - HTML for rendering an application.
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| [config] | <code>Object</code> | <code>{}</code> | Server config or data that will be available in the attribute `data-app` on currentScript. In Vue it will also be available in the `$options` object. |
-| [settings] | <code>Object</code> | <code>{}</code> | Settings object. |
-| [settings.noScript] | <code>String</code> | <code>&#x27;&#x27;</code> | HTML that will be rendered when JavaScript is not available. |
-| [settings.selector] | <code>String</code> | <code>&#x60;[data-portlet-id&#x3D;&quot;${portletId}&quot;]&#x60;</code> | Query selector for where the app should be mounted. |
-| [settings.async] | <code>Boolean</code> | <code>false</code> | If the app script should be loaded asynchronously. [Read more about async and defer.](https://flaviocopes.com/javascript-async-defer/) |
-| [settings.defer] | <code>Boolean</code> | <code>true</code> | If the app script should be loaded after DOM is ready. [Read more about async and defer.](https://flaviocopes.com/javascript-async-defer/) |
-| [settings.req] | <code>Object</code> |  | The req object from SiteVision, pass this to optimize browser specific script loading if you have multiple instances of the app. |
-
-#### Example
-In `app_src/server/index.js`.
-```javascript
-router.get('/', (req, res) => {
-  const data = { foo: 'bar' };
-  // Most common usage.
-  res.send(renderApp(data));
-
-  // With all settings.
-  res.send(renderApp(data, {
-    noScript: 'You need JS for this!',
-    selector: '#mount_me_here',
-    async: false,
-    defer: true,
-    req,
-  }));
-});
-```
-##### **Vue**
-In `app_src/client/index.js` or `app_src/main.js`.
-```javascript
-import render from '@soleil-se/webapp-util/render-vue';
-import App from './App.vue';
+<dl>
+<dt><a href="#getNamespace">getNamespace([prefix])</a> ⇒ <code>String</code></dt>
+<dd><p>Get a prefixed namespace unique for app.</p>
+</dd>
+<dt><a href="#getRouteUri">getRouteUri(route)</a> ⇒ <code>String</code></dt>
+<dd><p>Get URI for a route, same as <code>getStandaloneUrl</code> in SiteVision template.</p>
+</dd>
+<dt><a href="#getViewUri">getViewUri(route)</a> ⇒ <code>String</code></dt>
+<dd><p>Get URI for a view, same as <code>getUrl</code> in SiteVision template.</p>
+</dd>
+<dt><a href="#getResourceUri">getResourceUri(resource)</a> ⇒ <code>String</code></dt>
+<dd><p>Get URI for a resource.</p>
+</dd>
+<dt><a href="#getAppData">getAppData([key])</a> ⇒ <code>*</code> | <code>Object</code></dt>
+<dd><p>Get appData value or object.</p>
+</dd>
+</dl>
 
-render(App);
-```
+<a name="appId"></a>
 
-### `getRouteUri(route)` ⇒ `String`
-Get URI for a route, same as `getStandaloneUrl` in SiteVision template.   
-https://developer.sitevision.se/docs/webapps/template#h-Methods
+### appId : <code>String</code>
+DOM friendly unique identifier for the WebApp.
 
-**Returns**: <code>String</code> - URI for route.
+```js
+import { appId } from '@soleil-se/webapp-util';
 
-| Param | Type | Description |
-| --- | --- | --- |
-| route | <code>String</code> | A route. |
+console.log(appId); // For example: 12_682d461b1708a9bb1ea13efd
+```
+
+<a name="isOffline"></a>
+
+### isOffline : <code>Boolean</code>
+If the WebApp is running in offline mode or not.
 
+```js
+import { isOffline } from '@soleil-se/webapp-util';
 
-#### Example
-```javascript
-const routeUri = getRouteUri('/my-route');
+console.log(isOffline);  // true or false
 ```
-### `getViewUri(route)` ⇒ `String`
-Get URI for a view, same as `getUrl` in SiteVision template.   
-https://developer.sitevision.se/docs/webapps/template#h-Methods
 
-**Returns**: <code>String</code> - URI for view.
+<a name="isOnline"></a>
 
-| Param | Type | Description |
-| --- | --- | --- |
-| route | <code>String</code> | A route. |
+### isOnline : <code>Boolean</code>
+If the WebApp is running in online mode or not.
+
+```js
+import { isOnline } from '@soleil-se/webapp-util';
 
-#### Example
-```javascript
-const viewUri = getViewUri('/my-route');
+console.log(isOnline); // true or false
 ```
 
-### `getResourceUri(resource)` ⇒ `String`
-Get URI for a resource.
+### getNamespace([prefix]) ⇒ <code>String</code>
+Get a prefixed namespace unique for app.
 
-**Returns**: `String` - URI for a resource.
+**Returns**: <code>String</code> - Prefixed namespace.
 
-| Param | Type | Description |
+| Param | Type | Default |
 | --- | --- | --- |
-| resource | `String` | A resource. |
+| [prefix] | <code>string</code> | <code>&quot;&#x27;app&#x27;&quot;</code> |
 
+```js
+import { getNamespace } from '@soleil-se/webapp-util';
 
-#### Example
-```javascript
-const resourceUri = getResourceUri('file/in/resource.png');
-```
-### `renderTemplate(template, [values])` ⇒ `String`
-Renders a Underscore template and returns a string.   
-This function is also available inside the template.
-
-**Returns**: `String` - Rendered template
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| template | `String` |  | Underscore template. |
-| [values] | `Object` | `{}` | Values. |
-
-#### Example
-**Simple example**
-```javascript
-const string = renderTemplate('<div><%= foo %></div>', {
-  foo: 'bar',
-});
-```
-**Multiple templates**
-```html
-/* views/item.html */
-<li>
-  <%- name %>
-</li>
-```
-```html
-/* views/main.html */
-<ul>
-  <% items.forEach(function(item) { %>
-    <%= renderTemplate(itemTemplate, item) %>
-  <% }); %>
-</ul>
-```
+console.log(getNamespace());
+// For example: app_12_682d461b1708a9bb1ea13efd
 
-```javascript
-import { renderTemplate } from '@soleil-se/webapp-util';
-import mainTemplate from './views/main.html';
-import itemTemplate from './views/item.html';
+console.log(getNamespace('input'));
+// For example: input_12_682d461b1708a9bb1ea13efd
 
-const items = [{ name: 'Foo' }, { name: 'Bar' }, { name: 'Baz' }];
-const string = renderTemplate(mainTemplate, { items, itemTemplate });
-```
-> **NOTE**   
-> Remember that the second argument must be an object and that objects properties are accessed directly in any child templates!   
-### `isOffline`
-If the webapp is running in offline mode or not.   
-This value is also passed to AppData.
-
-```javascript
-if(isOffline) {
-  // Do something
-}
+// If the app is in a decoration template the Portlet ID is the same for all instances, so the ID of the decorated node is used as well.
+console.log(getNamespace('decoration'));
+// For example: decoration_10_3871c02f1754f3aa8f9d4eb_12_70c3d424173b4900fc550e1c
 ```
 
-### `isOnline`
-If the webapp is running in online mode or not.   
-This value is also passed to AppData.
+<a name="getRouteUri"></a>
 
-```javascript
-if(isOnline) {
-  // Do something
-}
-```
+### getRouteUri(route) ⇒ <code>String</code>
+Get URI for a route, same as `getStandaloneUrl` in SiteVision template.
 
-### `uniqueId`
-A unique ID for the WebApp.    
-This value is also passed to AppData.
+**Returns**: <code>String</code> - URI for route.
 
-## AppData
-`@soleil-se/webapp-util/app-data`   
-Data that is available for the WebApp.   
-```javascript
-import AppData from '@soleil-se/webapp-util/app-data';
+| Param | Type | Description |
+| --- | --- | --- |
+| route | <code>String</code> | A route. |
 
-// These are avaliable per default:
-const { isOffline, isOnline, uniqueId } = AppData;
-```
+```js
+import { getRouteUri } from '@soleil-se/webapp-util';
 
-All data passed to the app is available in AppData:   
-index.js
-```javascript
-res.send(renderApp({ foo: 'bar' }))
+console.log(getRouteUri('/items'));
+// URI structure: /appresource/<pageId>/<portletId>/items
 ```
-In app:
-```javascript
-import AppData from '@soleil-se/webapp-util/app-data';
 
-console.log(AppData.foo);
+<a name="getViewUri"></a>
 
-// Or descructured
-const { foo } = AppData;
-console.log(foo);
-```
+### getViewUri(route) ⇒ <code>String</code>
+Get URI for a view, same as `getUrl` in SiteVision template.
 
-## Svelte
-Functions for rendering a Svelte application.
-
-### Server 
-`@soleil-se/webapp-util/svelte-server`
-#### `render(App, [data], [settings])` ⇒ `String`
-Get HTML string for rendering a universal Svelte application.   
-To be used together with `@soleil-se/webapp-util/svelte-client`. 
-
-**Returns**: <code>String</code> - HTML for rendering an application.
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| [App] | <code>Svelte</code> |  | Svelte application. |
-| [data] | <code>Object</code> | <code>{}</code> | Server data or config that will be available from `@soleil-se/webapp-util/app-data` |
-| [settings] | <code>Object</code> | <code>{}</code> | Settings object. |
-| [settings.async] | <code>Boolean</code> | <code>false</code> | If the app script should be loaded asynchronously. [Read more about async and defer.](https://flaviocopes.com/javascript-async-defer/) |
-| [settings.defer] | <code>Boolean</code> | <code>true</code> | If the app script should be loaded after DOM is ready. [Read more about async and defer.](https://flaviocopes.com/javascript-async-defer/) |
-| [settings.req] | <code>Object</code> |  | The req object from SiteVision, pass this to optimize browser specific script loading if you have multiple instances of the app. |
-
-In `app_src/server/index.js` or `app_src/index.js`.
-```javascript
-import router from 'router';
-import { render } from '@soleil-se/webapp-util/svelte-server';
-
-import App from './App.svelte';
-
-router.get('/', (req, res) => {
-  const data = { foo: 'bar' }; 
-  res.send(renderSvelte(App, data));  
-});
-```
+**Returns**: <code>String</code> - URI for view.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| route | <code>String</code> | A route. |
 
-#### `renderServer(App, [data])` ⇒ `String`
-Get HTML string for a server only rendered Svelte application.   
+```js
+import { getViewUri } from '@soleil-se/webapp-util';
 
-**Returns**: <code>String</code> - HTML for rendering an application.
+console.log(getViewUri('/items'));
+// URI structure: ?sv.target=<id>&sv.<id>.route=/items
+```
 
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| [App] | <code>Svelte</code> |  | Svelte application. |
-| [data] | <code>Object</code> | <code>{}</code> | Server data or config that will be available from `@soleil-se/webapp-util/app-data` |
+<a name="getResourceUri"></a>
+### getResourceUri(resource) ⇒ <code>String</code>
+Get URI for a resource.
 
-In `app_src/server/index.js` or `app_src/index.js`.
-```javascript
-import router from 'router';
-import { renderServer } from '@soleil-se/webapp-util/svelte-server';
+**Returns**: <code>String</code> - URI for a resource.
 
-import App from './App.svelte';
+| Param | Type | Description |
+| --- | --- | --- |
+| resource | <code>String</code> | A resource. |
+
+```js
+import { getResourceUri } from '@soleil-se/webapp-util';
 
-router.get('/', (req, res) => {
-  const data = { foo: 'bar' }; 
-  res.send(renderServer(App, data));  
-});
+console.log(getResourceUri('/image.png'));
+// URI structure: /webapp-files/<webappname>/<webappversion>/image.png
 ```
 
-#### `renderClient(App, [data], [settings])` ⇒ `String`
-Get HTML string for a client only rendered Svelte application.   
-Can be used together with `@soleil-se/webapp-util/svelte-client`. 
+<a name="getAppData"></a>
 
-**Returns**: <code>String</code> - HTML for rendering an application.
+### getAppData([key]) ⇒ <code>\*</code> \| <code>Object</code>
+Get appData value or object that is passed to app when rendering.
 
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| [App] | <code>Svelte</code> |  | Svelte application. |
-| [data] | <code>Object</code> | <code>{}</code> | Server data or config that will be available from `@soleil-se/webapp-util/app-data` |
-| [settings] | <code>Object</code> | <code>{}</code> | Settings object. |
-| [settings.async] | <code>Boolean</code> | <code>false</code> | If the app script should be loaded asynchronously. [Read more about async and defer.](https://flaviocopes.com/javascript-async-defer/) |
-| [settings.defer] | <code>Boolean</code> | <code>true</code> | If the app script should be loaded after DOM is ready. [Read more about async and defer.](https://flaviocopes.com/javascript-async-defer/) |
-| [settings.req] | <code>Object</code> |  | The req object from SiteVision, pass this to optimize browser specific script loading if you have multiple instances of the app. |
+**Returns**: <code>\*</code> \| <code>Object</code> - Value or object.
 
-In `app_src/server/index.js` or `app_src/index.js`.
-```javascript
-import router from 'router';
-import { renderClient } from '@soleil-se/webapp-util/svelte-server';
+| Param | Type | Description |
+| --- | --- | --- |
+| [key] | <code>String</code> | Key for value. |
 
-import App from './App.svelte';
+```js
+import { getAppData } from '@soleil-se/webapp-util';
 
-router.get('/', (req, res) => {
-  const data = { foo: 'bar' }; 
-  res.send(renderSvelte(App, data));  
-});
+// Get value with key
+const myValue = getAppData('myValue');
+// Or with destructuring
+const { myValue } = getAppData();
 ```
 
-### Client
-`@soleil-se/webapp-util/svelte-client`
-#### `render(App)`
-In `app_src/client/index.js` or `app_src/main.js`.
-```javascript
-import { render } from '@soleil-se/webapp-util/svelte-client';
-import App from './App.svelte';
+## Rendering
 
-render(App);
-```
+* [Render](./docs/1.render.md)
+* [Svelte](./docs/2.svelte.md)
+* [Vue](./docs/3.vue.md)
+* [Underscore](./docs/4.underscore.md)
 

package/client/attribute-util/getCurrentScript.js

@@ -0,0 +1,56 @@
+/* Scoped version of https://github.com/amiller-gh/currentScript-polyfill */
+// document.currentScript polyfill by Adam Miller
+// MIT license
+
+export default function getCurrentScript() {
+  if (!('currentScript' in document)) {
+    // IE 8-10 support script readyState
+    // IE 11+ support stack trace
+    try {
+      throw new Error();
+    } catch (err) {
+      // Find the second match for the "at" string to get file src url from stack.
+      // Specifically works with the format of stack traces in IE.
+      let i = 0;
+      const stackDetails = (/.*at [^(]*\((.*):(.+):(.+)\)$/ig).exec(err.stack);
+      const scriptLocation = (stackDetails && stackDetails[1]) || false;
+      const line = (stackDetails && stackDetails[2]) || false;
+      const currentLocation = document.location.href.replace(document.location.hash, '');
+      let pageSource;
+      let inlineScriptSourceRegExp;
+      let inlineScriptSource;
+      const scripts = document.getElementsByTagName('script'); // Live NodeList collection
+
+      if (scriptLocation === currentLocation) {
+        pageSource = document.documentElement.outerHTML;
+        inlineScriptSourceRegExp = new RegExp(`(?:[^\\n]+?\\n){0,${line - 2}}[^<]*<script>([\\d\\D]*?)<\\/script>[\\d\\D]*`, 'i');
+        inlineScriptSource = pageSource.replace(inlineScriptSourceRegExp, '$1').trim();
+      }
+
+      for (; i < scripts.length; i += 1) {
+        // If ready state is interactive, return the script tag
+        if (scripts[i].readyState === 'interactive') {
+          return scripts[i];
+        }
+
+        // If src matches, return the script tag
+        if (scripts[i].src === scriptLocation) {
+          return scripts[i];
+        }
+
+        // If inline source matches, return the script tag
+        if (
+          scriptLocation === currentLocation
+          && scripts[i].innerHTML
+          && scripts[i].innerHTML.trim() === inlineScriptSource
+        ) {
+          return scripts[i];
+        }
+      }
+
+      // If no match, return null
+      return null;
+    }
+  }
+  return document.currentScript;
+}

package/{attribute-util → client/attribute-util}/index.js

@@ -1,3 +1,5 @@
+import getCurrentScript from './getCurrentScript';
+
 /**
  * JSON decode an attribute on the currentScript element.
  * Use if attribute contains a JSON-object.
@@ -5,7 +7,8 @@
  * @returns {Object} Decoded JSON object.
  */
 export const decodeAttribute = (attribute) => {
-  const encoded = document.currentScript.getAttribute(attribute);
+  const currentScript = getCurrentScript();
+  const encoded = currentScript.getAttribute(attribute);
   if (encoded) {
     return decodeURIComponent(encoded);
   }

package/{svelte-client → client/svelte}/index.js

@@ -1,14 +1,9 @@
 /* eslint-disable import/prefer-default-export */
-import 'current-script-polyfill';
-
-import { decodeAttribute, parseAttribute } from '../attribute-util';
-import { setAppData } from '../app-data';
-
-const props = parseAttribute('data-app');
-setAppData(props);
+import { decodeAttribute } from '../attribute-util';
+import { getAppData } from '../../common';
 
 /**
- * Render a Svelte application
+ * Renders a Svelte application
  * @param {Svelte} App Svelte application to be started.
  */
 export function render(App) {
@@ -16,6 +11,7 @@ export function render(App) {
 
   const mountElement = document.querySelector(selector);
   const hydrate = mountElement.childElementCount > 0;
+  const props = getAppData();
   if (mountElement) {
     return new App({
       hydrate,

package/{render-vue → client/vue}/index.js

@@ -1,15 +1,13 @@
-import 'current-script-polyfill';
+/* eslint-disable import/prefer-default-export */
+/* eslint-disable-next-line import/no-unresolved */
 import Vue from 'vue';
 
-import { decodeAttribute, parseAttribute } from '../attribute-util';
-import { setAppData } from '../app-data';
-
-const options = parseAttribute('data-app');
-setAppData(options);
+import { decodeAttribute } from '../attribute-util';
+import { getAppData, isOffline } from '../../common';
 
 const offlineModeMixin = {
   mounted() {
-    if (this.$options.isOffline) {
+    if (isOffline) {
       const $anchors = this.$el.querySelectorAll('a');
       $anchors.forEach(($anchor) => {
         $anchor.addEventListener('click', (e) => {
@@ -24,8 +22,9 @@ const offlineModeMixin = {
  * Render a Vue application
  * @param {Vue} App Vue application to be started.
  */
-export default function render(App) {
+export function render(App) {
   const selector = decodeAttribute('data-selector');
+  const options = getAppData();
 
   Object.assign(App, options, {
     mixins: [offlineModeMixin],