@soleil-se/app-util 5.0.0 → 5.2.0

package/CHANGELOG.md

@@ -5,7 +5,22 @@ 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.0.0] - 2021-xx-xx
+## [5.2.0] - 2023-01-31
+
+### Changed
+
+- New function `parseParams` to parse query parameters from an URL, URI or query string.
+
+## [5.1.0] - 2022-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] - 2022-02-08
 
 ### Changed
 

package/README.md

@@ -3,7 +3,7 @@
 
 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)
 
 
@@ -29,58 +29,33 @@ Utility functions for WebApps.
   "type": "WebApp",
   "bundled": true
 }
-
 ```
 
 ## Install
 
-`yarn add @soleil-se/webapp-util`
+```sh
+> npm install @soleil-se/webapp-util
+> yarn add @soleil-se/webapp-util
+```
+
+:::details Integrity check failed
+If the following error occurs when installing with Yarn run `yarn install --update-checksums`.
+
+```
+Integrity check failed for "@soleil-se/webapp-util" (computed integrity doesn...
+```
+
+:::
 
 ## Migration
 
-Migrating from version 4?
+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>
-</dl>
-
-<a name="appId"></a>
-
 ### appId : `String`
 
 DOM friendly unique identifier for the WebApp.
@@ -91,8 +66,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.
@@ -103,8 +76,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.
@@ -139,9 +110,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.
 
@@ -150,35 +119,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.
@@ -196,8 +152,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.
@@ -217,7 +171,45 @@ const myValue = getAppProps('myValue');
 const { myValue } = getAppProps();
 ```
 
+### stringifyParams(params [, options]) ⇒ `String`
+
+Stringify an object to a query string compatible with Sitevision.
+
+**Returns**: `String` - Stringified parameters.
+
+| 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 { stringifyParams } from '@soleil-se/webapp-util';
+
+const queryString = stringifyParams({ foo: 'bar', num: 1 });
+// foo=bar&num=1
+
+const queryString = stringifyParams({ foo: 'bar', num: 1 }, { addQueryPrefix: true });
+// ?foo=bar&num=1
+```
+
+### parseParams(url) ⇒ `Object`
+
+Parse an URL, URI or query string to an object containing its query parameters.
+
+**Returns**: `Object` - Parsed parameters.
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| url | `String` | | URL, URI or query string to be parsed, must start with or contain "?" |
+
+```js
+import { parseParams } from '@soleil-se/webapp-util';
+
+const params = parseParams('?foo=bar&arr[]=1&arr[]=2');
+// { foo: 'bar', arr: [1, 2] }
+```
+
 ## Rendering
 
 * [Svelte](./docs/1.svelte.md)
-* [Vue (DEPRECATED)](./docs/2.vue.md)

package/common/index.js

@@ -1,14 +1,21 @@
-/* global document */
+/* global document console */
 /* eslint-disable global-require */
-
 import router from '@sitevision/api/common/router';
 import app from '@sitevision/api/common/app';
 
+import getLegacyRouteUri from './legacy/getRouteUri';
+
 /**
  * Get an ID for the app.
  * @return {String} ID
  */
-const getAppId = () => app.portletId.replace('.', '_');
+const getAppId = () => {
+  const id = (process.server
+    ? require('PortletContextUtil')?.getCurrentPortlet()?.getIdentifier()
+    : app?.portletId) || 'preview';
+
+  return id.replace('.', '_');
+};
 
 /**
  * Regex for selecting leading slashes
@@ -51,24 +58,88 @@ export function getNamespace(prefix = 'app') {
   return `${prefix}_${appId}`;
 }
 
+/**
+ * Stringify an object to a query string compatible with Sitevision.
+ * @param {Object} params Object with parameters to stringify.
+ * @param {Object} [options] Optional options.
+ * @param {Boolean} [options.addQueryPrefix = false] If a leading ? should be added to the string.
+ * @returns Stringified parameters.
+ */
+export function stringifyParams(params = {}, { addQueryPrefix = false } = {}) {
+  const qs = Object.keys(params).map((key) => {
+    const value = params[key];
+    if (!value) return undefined;
+    if (Array.isArray(value)) {
+      return value.map((v) => `${encodeURIComponent(`${key}[]`)}=${encodeURIComponent(v)}`).join('&');
+    }
+    return `${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
+  }).filter((value) => !!value).join('&');
+
+  if (!qs) return '';
+  return addQueryPrefix ? `?${qs}` : qs;
+}
+
+/**
+ * Parse an URL or URI to an object containing its query parameters.
+ * @param {String} url URL or URI to be parsed, must start with or contain "?".
+ * @returns Object with parsed parameters.
+ */
+export default function parseParams(url = '') {
+  const hasQuestion = url.indexOf('?') > -1;
+  if (!hasQuestion) return {};
+
+  let query = url.split('?')[1];
+  const hasHash = url.indexOf('#') > -1;
+  query = hasHash ? url.split('#')[0] : query;
+
+  return query.split('&').reduce((params, part) => {
+    let [key, value] = part.split('+').join(' ').split('=');
+    key = decodeURIComponent(key);
+    value = decodeURIComponent(value);
+
+    const isArray = key.endsWith('[]');
+    if (isArray) {
+      key = key.replace('[]', '');
+      value = params[key] ? [...params[key], value] : [value];
+    }
+
+    return {
+      ...params,
+      [key]: value,
+    };
+  }, {});
+}
+
 /**
  * Get URI for a route, same as `getStandaloneUrl` in Sitevision router.
  * @param {string} route A route.
- * @param {object} query Query parameters.
+ * @param {object} params Query parameters.
  * @returns {string} URI for route.
  */
-export function getRouteUri(route = '', query) {
+export function getRouteUri(route = '', params) {
   const path = route.replace(leadingSlashes, '');
-  return router.getStandaloneUrl(path !== '' ? `/${path}` : path, query).replace(trailingSlashes, '');
+  const qs = stringifyParams(params, { addQueryPrefix: true });
+  if (router?.getStandaloneUrl) {
+    return router.getStandaloneUrl((path !== '' ? `/${path}` : path).replace(trailingSlashes, '')) + qs;
+  }
+  /* Import of @sitevision/api/common/router is not avaliable in hooks, need to build the route URI
+   * manually instead of using router.getStandaloneUri */
+  return getLegacyRouteUri(path).replace(trailingSlashes, '') + qs;
 }
 
 /**
  * Get URI for a view, same as `getUrl` in Sitevision router.
+ * @deprecated Not used in WebApps 2.
  * @param {string} route A route.
  * @returns {string} URI for view.
  */
-export function getViewUri(route = '') {
-  return router.getUrl(route);
+export function getViewUri(route = '', query) {
+  if (!router?.getUrl) {
+    console.warn('[@soleil-api/webapp-util] getViewUri requires router.getUrl support.');
+    return undefined;
+  }
+
+  return router.getUrl(route, query);
 }
 
 /**
@@ -77,9 +148,17 @@ export function getViewUri(route = '') {
  * @returns {string} URI for a resource.
  */
 export function getResourceUri(resource = '') {
-  const { webAppId, webAppVersion } = app;
+  let id;
+  let version;
+
+  if (process.server) {
+    ({ appIdentifier: id, appVersion: version } = require('appInfo'));
+  } else {
+    ({ webAppId: id, webAppVersion: version } = app);
+  }
+
   const path = resource.replace(leadingSlashes, '');
-  return `/webapp-files/${webAppId}/${webAppVersion}/${path}`;
+  return `/webapp-files/${id}/${version}/${path}`;
 }
 
 let appProps = {};

package/common/legacy/getRouteUri.js

@@ -0,0 +1,12 @@
+/* eslint-disable global-require */
+export default function getRouteUri(route) {
+  const PortletContextUtil = require('PortletContextUtil');
+  const currentPage = PortletContextUtil.getCurrentPage();
+  const currentPortlet = PortletContextUtil.getCurrentPortlet();
+  if (currentPage && currentPortlet) {
+    const currentPageId = currentPage.getIdentifier().replace('_sitePage', '');
+    const currentPortletId = currentPortlet.getIdentifier();
+    return `/appresource/${currentPageId}/${currentPortletId}/${route}`;
+  }
+  return '/';
+}

package/package.json

@@ -1,13 +1,9 @@
 {
   "name": "@soleil-se/app-util",
-  "version": "5.0.0",
+  "version": "5.2.0",
   "description": "Utility and rendering functions for WebApps.",
   "main": "./common/index.js",
   "author": "Soleil AB",
-  "contributors": [
-    "Kimmy Monassar",
-    "Jonas Gällman"
-  ],
   "license": "UNLICENSED",
   "private": false,
   "homepage": "https://docs.soleilit.se/03.packages/@soleil-api&app-util",
@@ -18,5 +14,6 @@
   "peerDependencies": {
     "@sitevision/api": "^1.0.10"
   },
+  "gitHead": "903884ec52e502707ab62483d5f01b739a8f33c9",
   "dependencies": {}
 }