@soleil-se/app-util 4.2.1 → 5.1.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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).
 
+## [5.1.0] - 2021-05-27
+
+### Changed
+
+- New function `stringifyParams` to stringify query parameters to a Sitevision compatible format.
+- Possible to pass a parameters object to `getRouteUri`.
+- All common constants and functions are now usable in hooks.
+- Deprecate `getViewUri` since it's not used in WebApps 2.
+
+## [5.0.0] - 2021-02-08
+
+### Changed
+
+- Using WebApps 2 for rendering apps.
+
+### Removed
+
+- `getAppData`, use `getAppProps` instead.
+- `server/render`, use `res.agnosticRender` for framework agnostic rendering.
+- `server/renderTemplate`, used for rendering underscore templates.
+
 ## [4.2.1] - 2021-09-06
 
 ### Fixed

package/MIGRATION.md

@@ -1,156 +1,149 @@
 # Migration
 
-Migration from version 2 or 3 to 4.
+Migration from version 4 to 5.
 
 <!-- TOC -->
 
-- [renderApp](#renderapp)
-  - [Export](#export)
-  - [Settings](#settings)
-- [renderTemplate](#rendertemplate)
-- [getRouteUri](#getrouteuri)
-- [AppData](#appdata)
-  - [Get data](#get-data)
-  - [Standard values](#standard-values)
-- [Svelte](#svelte)
-  - [Server](#server)
-  - [Client](#client)
-- [Vue](#vue)
+- [Manifest](#manifest)
+- [index.js](#indexjs)
+  - [Universal app](#universal-app)
+  - [SSR app](#ssr-app)
+  - [CSR app](#csr-app)
+- [main.js](#mainjs)
 
 <!-- /TOC -->
 
-## renderApp
-### Export
-Export moved and renamed.
+## Manifest
 
-Old:
-```js
-import { renderApp } from '@soleil-api/webapp-util';
-```
-New:
-```js
-import { render } from '@soleil-api/webapp-util/server';
-```
+Add `"bundled": true` to the app manifest file.
 
-### Settings
-Selector is moved to client side rendering functions.
+manifest.json
+
+```json
+{
+  "id": "se.soleil.myApp",
+  "version": "1.0.0",
+  "name": "My app",
+  "author": "Soleil AB",
+  "description": "",
+  "helpUrl": "https://soleil.se/support",
+  "type": "WebApp",
+  "bundled": true
+}
 
-Old (index.js):
-```js
-res.send(renderApp(data, { selector: '#mount_app_here' }));
 ```
 
-New (main.js):
-```js
-import { render } from '@soleil-api/webapp-util/client/vue';
-import App from './App.vue';
+## index.js
 
-render(App, { selector: '#mount_app_here' });
-```
+Rendering is now using Webapps 2 render functions.
 
-## renderTemplate
-Export moved.   
+### Universal app
 
-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
 
-Old:
 ```js
-import AppData from '@soleil-api/webapp-util/app-data';
+import router from '@sitevision/api/common/router';
+import { render } from '@soleil-api/webapp-util/server/svelte';
 
-const getItems = async () => {
-  return fetch(AppData.itemsRoute)
-    .then((res) => res.json());
-};
-``` 
-New:
-```js
-import { getRouteUri } from '@soleil-api/webapp-util';
+import App from './App.svelte';
 
-const getItems = async () => {
-  return fetch(getRouteUri('/items'))
-    .then((res) => res.json());
-};
+router.get('/', (req, res) => {
+  const props = { foo: 'bar' };
+  res.send(render(App, props));
+});
 ```
-## AppData
 
-### Get data
-The default export as object and `@soleil-api/webapp-util/app-data` import is removed.
+New
 
-Old:
 ```js
-import AppData from '@soleil-api/webapp-util/app-data';
+import router from '@sitevision/api/common/router';
+import { render } from '@soleil-api/webapp-util/server/svelte';
 
-const { myValue } = AppData;
-```
-New:
-```js
-import { getAppData } from '@soleil-api/webapp-util';
+import App from './App.svelte';
 
-// Get value with key
-const myValue = getAppData('myValue');
-// Or with destructuring
-const { myValue } = getAppData();
+router.get('/', (req, res) => {
+  const props = { foo: 'bar' };
+  const html = render(App, props);
+  res.agnosticRender(html, props);  
+});
 ```
-### Standard values
-Values that was set as sandard are now moved.
 
-Old:
-```js
-import AppData from '@soleil-api/webapp-util/app-data';
+### SSR app
+
+Old
 
-const { isOnline, isOffline, uniqueId } = AppData;
-```
-New:
 ```js
-import { isOffline, isOnline, getNamespace } from '@soleil-api/webapp-util';
+import router from '@sitevision/api/common/router';
+import { renderServer } from '@soleil-api/webapp-util/server/svelte';
 
-const uniqueId = getNamespace();
+import App from './App.svelte';
+
+router.get('/', (req, res) => {
+  const props = { foo: 'bar' };
+  res.send(renderServer(App, props));
+});
 ```
 
-## Svelte
-### Server
-Export moved.   
-Export `renderClient` is removed, use `render` from `'@soleil-api/webapp-util/server`
+New
 
-Old:
-```js
-import { render } from '@soleil-api/webapp-util/svelte-server';
-```
-New:
 ```js
+import router from '@sitevision/api/common/router';
 import { render } from '@soleil-api/webapp-util/server/svelte';
+
+import App from './App.svelte';
+
+router.get('/', (req, res) => {
+  const props = { foo: 'bar' };
+  const html = render(App, props);
+  res.send(html);  
+});
 ```
-### Client
-Export moved.
 
-Old:
+### CSR app
+
+Old
+
 ```js
-import { render } from '@soleil-api/webapp-util/svelte-client';
+import router from '@sitevision/api/common/router';
+import { render } from '@soleil-api/webapp-util/server';
+
+router.get('/', (req, res) => {
+  const props = { foo: 'bar' };
+  res.send(render(props));
+});
 ```
-New:
+
+New
+
 ```js
-import { render } from '@soleil-api/webapp-util/client/svelte';
+import router from '@sitevision/api/common/router';
+
+router.get('/', (req, res) => {
+  const props = { foo: 'bar' };
+  res.agnosticRender('', props)
+});
 ```
 
-## Vue
-Export moved.
+## main.js
+
+Is now expecting a default export containing a function
+
+Old
 
-Old:
 ```js
-import render from '@soleil-api/webapp-util/render-vue';
+import { render } from '@soleil-api/webapp-util/client/svelte';
+import App from './App.svelte';
+
+render(App);
 ```
-New:
+
+New
+
 ```js
-import { render } from '@soleil-api/webapp-util/client/vue';
-```
+import { render } from '@soleil-api/webapp-util/client/svelte';
+import App from './App.svelte';
 
+export default (props, target) => {
+  render(App, { props, target });
+};
+```

package/README.md

@@ -1,16 +1,36 @@
 
-# `@soleil-se/webapp-util@^4.0.0`
+# `@soleil-se/webapp-util@^5.0.0`
 
-Utility functions for Webapps.
+Utility functions for WebApps.
 
-[GitHub](https://github.com/soleilit/server-monorepo/tree/master/packages/webapp-util)
+[GitHub](https://github.com/soleilit/server-monorepo/tree/master/packages/webapp-util)  
 [NPM](https://www.npmjs.com/package/@soleil-se/webapp-util)
 
 
 
 ## Requirements
 
-`@soleil-se/sv-gulp-build` 4 or later (Works best with ^4.3.0).
+* Sitevision 9.1.0 or later.  
+* `@soleil-se/sv-app-build` 1.0.0 or later.
+* WebApps 2 enabled app.
+
+### Manifest
+
+`bundled` needs to be enabled in [WebApp manifest](https://developer.sitevision.se/docs/webapps/webapps-2/manifest) for WebApps 2.
+
+```json
+{
+  "id": "se.soleil.myApp",
+  "version": "1.0.0",
+  "name": "My app",
+  "author": "Soleil AB",
+  "description": "",
+  "helpUrl": "https://soleil.se/support",
+  "type": "WebApp",
+  "bundled": true
+}
+
+```
 
 ## Install
 
@@ -18,52 +38,13 @@ Utility functions for Webapps.
 
 ## Migration
 
-Migrating from version 2 or 3?
+Migrating from version 4?  
 See [MIGRATION](./MIGRATION.md).
 
 ## API
 
 All imports from base package are available both on the server and client.
 
-### Constants
-
-<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>
-
-### Functions
-
-<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.
-</dd>
-<dt><a href="#getViewUri">getViewUri(route)</a> ⇒ <code>String</code></dt>
-<dd><p>Get URI for a view.
-</dd>
-<dt><a href="#getResourceUri">getResourceUri(resource)</a> ⇒ <code>String</code></dt>
-<dd><p>Get URI for a resource.</p>
-</dd>
-<dt><a href="#getAppProps">getAppProps([key])</a> ⇒ <code>*</code> | <code>Object</code></dt>
-<dd><p>Get props that are passed to app when rendering.</p>
-</dd>
-<dt><del><a href="#getAppData">getAppData([key])</a> ⇒ <code>*</code> | <code>Object</code></del></dt>
-<dd><p>Get props that are passed to app when rendering.</p>
-</dd>
-</dl>
-
-<a name="appId"></a>
-
 ### appId : `String`
 
 DOM friendly unique identifier for the WebApp.
@@ -74,8 +55,6 @@ import { appId } from '@soleil-se/webapp-util';
 console.log(appId); // For example: 12_682d461b1708a9bb1ea13efd
 ```
 
-<a name="isOffline"></a>
-
 ### isOffline : `Boolean`
 
 If the WebApp is running in offline mode or not.
@@ -86,8 +65,6 @@ import { isOffline } from '@soleil-se/webapp-util';
 console.log(isOffline);  // true or false
 ```
 
-<a name="isOnline"></a>
-
 ### isOnline : `Boolean`
 
 If the WebApp is running in online mode or not.
@@ -122,9 +99,7 @@ console.log(getNamespace('decoration'));
 // For example: decoration_10_3871c02f1754f3aa8f9d4eb_12_70c3d424173b4900fc550e1c
 ```
 
-<a name="getRouteUri"></a>
-
-### getRouteUri(route) ⇒ `String`
+### getRouteUri(route, [query]) ⇒ `String`
 
 Get URI for a route.
 
@@ -133,35 +108,22 @@ Get URI for a route.
 | Param | Type | Description |
 | --- | --- | --- |
 | route | `String` | A route. |
+| query | `Object` | Object with query string parameters |
 
 ```js
 import { getRouteUri } from '@soleil-se/webapp-util';
 
 console.log(getRouteUri('/items'));
-// URI structure: /appresource/<pageId>/<portletId>/items
+// URI structure: /appresource/{pageId}/{portletId}>/items
 ```
 
-<a name="getViewUri"></a>
-
-### getViewUri(route) ⇒ `String`
-
-Get URI for a view.
-
-**Returns**: `String` - URI for view.
-
-| Param | Type | Description |
-| --- | --- | --- |
-| route | `String` | A route. |
-
 ```js
-import { getViewUri } from '@soleil-se/webapp-util';
+import { getRouteUri } from '@soleil-se/webapp-util';
 
-console.log(getViewUri('/items'));
-// URI structure: ?sv.target=<id>&sv.<id>.route=/items
+console.log(getRouteUri('/items', { foo: 'bar' }));
+// URI structure: /appresource/{pageId}/{portletId}>/items?foo=bar
 ```
 
-<a name="getResourceUri"></a>
-
 ### getResourceUri(resource) ⇒ `String`
 
 Get URI for a resource.
@@ -179,8 +141,6 @@ console.log(getResourceUri('/image.png'));
 // URI structure: /webapp-files/<webappname>/<webappversion>/image.png
 ```
 
-<a name="getAppProps"></a>
-
 ### getAppProps([key]) ⇒ `*` | `Object`
 
 Get props that are passed to app when rendering.
@@ -200,32 +160,28 @@ const myValue = getAppProps('myValue');
 const { myValue } = getAppProps();
 ```
 
-<a name="getAppData"></a>
-
-### getAppData([key]) ⇒ `*` | `Object` (DEPRECATED)
+### stringifyParams(params [, options]) ⇒ `String`
 
-Use [getAppProps](#getAppProps) instead.  
+Stringify an object to a query string compatible with Sitevision.
 
-Get props that are passed to app when rendering.
+**Returns**: `String` - Stringified parameters.
 
-**Returns**: `*` | `Object` - Value or object.
-
-| Param | Type | Description |
-| --- | --- | --- |
-| [key] | `String` | Key for value. |
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| params | `Object` | | Object with parameters to stringify. |
+| [options] | `Object` | `{}` | Settings object. |
+| [options.addQueryPrefix] | `Boolean` | `false` | If a leading `?` should be added to the string. |
 
 ```js
-import { getAppData } from '@soleil-se/webapp-util';
+import { stringifyParams } from '@soleil-se/webapp-util';
 
-// Get value with key
-const myValue = getAppData('myValue');
-// Or with destructuring
-const { myValue } = getAppData();
+const queryString = stringifyParams({ foo: 'bar', num: 1 });
+// foo=bar&num=1
+
+const queryString = stringifyParams({ foo: 'bar', num: 1 }, { addQueryPrefix: true });
+// ?foo=bar&num=1
 ```
 
 ## Rendering
 
-- [Render](./docs/1.render.md)
-- [Svelte](./docs/2.svelte.md)
-- [Vue](./docs/3.vue.md)
-- [Underscore](./docs/4.underscore.md)
+* [Svelte](./docs/1.svelte.md)

package/client/svelte/index.js

@@ -1,22 +1,24 @@
-/* eslint-disable import/prefer-default-export */
-import { appId, getAppProps } from '../../common';
+import { setAppProps } from '../../common';
 
 /**
  * Renders a client side Svelte application.
  * @param {*} App Svelte app root component.
- * @param {Object} [settings={}] Settings object.
- * @param {String} [settings.selector=`#app_mount_${appId}`] Query selector for mount element.
- * @param {String} [settings.intro=false] If true, will play transitions on initial render,
+ * @param {object} [settings={}] Settings object.
+ * @param {string} [settings.target] Target where app should be mounted.
+ * @param {string} [settings.props] Root component props.
+ * @param {string} [settings.intro=false] If true, will play transitions on initial render,
  * rather than waiting for subsequent state changes.
  * @return {*} Initialized Svelte component.
  */
 export function render(App, {
-  selector = `#app_mount_${appId}`,
+  target,
+  props,
   intro = false,
 } = {}) {
-  const target = document.querySelector(selector);
+  setAppProps(props);
+
   const hydrate = target.childElementCount > 0;
-  const props = getAppProps();
+
   return new App({
     hydrate,
     target,