@soleil-se/app-util 3.0.2 → 4.0.0

package/CHANGELOG.md

@@ -4,8 +4,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.0] - 2021-01-27
+A much needed major overhaul of the package.   
+See [MIGRATION](./MIGRATION.md).
+
+### Changed
+- Major refactoring of package.
+- Exports for render functions are moved. 
+- All documented constants and functions from base import (`@soleil-api/webapp-util`) now works both in a server and client context.
+
+### Removed
+- `noScript` option in `render` (formerly `renderApp`) has been removed. If a no script message is needed use the `html` option wrapped in `<noscript>`.
+- `@soleil-api/webapp-util/app-data` has been removed, use [getAppData](./README.md#getAppData) from `@soleil-api/webapp-util`.
+
+## [3.0.3] - 2020-11-03
+- Nothing, Lerna wanted to publish...
+
 ## [3.0.2] - 2020-10-19
-### Added
 - Nothing, Lerna wanted to publish...
 
 ## [3.0.1] - 2020-09-28
@@ -66,21 +81,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `renderApp` is no longer using appName.
 - `render` is now called directly in `./app_src/client/index.js`. 
 - `render` and `App` no longer needs to be exported from `./app_src/client/index.js`. 
-
-## [1.2.4] - 2020-12-12
-### Fixed
-- `TypeError: Cannot call method getIdentifier of null` when app is viewed in Addons. 
-
-## [1.2.2] - 2019-05-20
-### Fixed
-- Removed `_sitePage` from `currentPageId` in `getRouteUri`.
-
-## [1.2.1] - 2019-05-09
-### Added
-- Added timestamp to WebApp script tag to prevent cache when uploading a new version.
-
-## [1.2.0] - 2019-05-07
-### Changed
-- `getRouteUri` now returns the standalone route.
-- HTML comment to not include this.name in `renderApp`.
-

package/MIGRATION.md

@@ -0,0 +1,136 @@
+# Migration
+
+Migration from version 2 or 3 to 4.
+
+<!-- TOC -->
+
+- [renderApp](#renderapp)
+- [renderTemplate](#rendertemplate)
+- [getRouteUri](#getrouteuri)
+- [AppData](#appdata)
+  - [Get data](#get-data)
+  - [Standard values](#standard-values)
+- [Svelte](#svelte)
+  - [Server](#server)
+  - [Client](#client)
+- [Vue](#vue)
+
+<!-- /TOC -->
+
+## renderApp
+Export moved and renamed.
+
+Old:
+```js
+import { renderApp } from '@soleil-api/webapp-util';
+```
+New:
+```js
+import { render } from '@soleil-api/webapp-util/server';
+```
+## renderTemplate
+Export moved.   
+
+Old:
+```js
+import { renderTemplate } from '@soleil-api/webapp-util';
+```
+New:
+```js
+import { renderTemplate } from '@soleil-api/webapp-util/server';
+```
+## getRouteUri
+URIs for routes was previously passed as props when rendering an application. This is no longer needed.   
+Now you can use `getRouteUri` in a client context as well.  
+
+Old:
+```js
+import AppData from '@soleil-api/webapp-util/app-data';
+
+const getItems = async () => {
+  return fetch(AppData.itemsRoute)
+    .then((res) => res.json());
+};
+``` 
+New:
+```js
+import { getRouteUri } from '@soleil-api/webapp-util';
+
+const getItems = async () => {
+  return fetch(getRouteUri('/items'))
+    .then((res) => res.json());
+};
+```
+## AppData
+
+### Get data
+The default export as object and `@soleil-api/webapp-util/app-data` import is removed.
+
+Old:
+```js
+import AppData from '@soleil-api/webapp-util/app-data';
+
+const { myValue } = AppData;
+```
+New:
+```js
+import { getAppData } from '@soleil-api/webapp-util';
+
+// Get value with key
+const myValue = getAppData('myValue');
+// Or with destructuring
+const { myValue } = getAppData();
+```
+### Standard values
+Values that was set as sandard are now moved.
+
+Old:
+```js
+import AppData from '@soleil-api/webapp-util/app-data';
+
+const { isOnline, isOffline, uniqueId } = AppData;
+```
+New:
+```js
+import { isOffline, isOnline, getNamespace } from '@soleil-api/webapp-util';
+
+const uniqueId = getNamespace();
+```
+
+## Svelte
+### Server
+Export moved.   
+Export `renderClient` is removed, use `render` from `'@soleil-api/webapp-util/server`
+
+Old:
+```js
+import { render } from '@soleil-api/webapp-util/svelte-server';
+```
+New:
+```js
+import { render } from '@soleil-api/webapp-util/server/svelte';
+```
+### Client
+Export moved.
+
+Old:
+```js
+import { render } from '@soleil-api/webapp-util/svelte-client';
+```
+New:
+```js
+import { render } from '@soleil-api/webapp-util/client/svelte';
+```
+
+## Vue
+Export moved.
+
+Old:
+```js
+import render from '@soleil-api/webapp-util/render-vue';
+```
+New:
+```js
+import { render } from '@soleil-api/webapp-util/client/vue';
+```
+

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)