@soleil-se/app-util 5.2.1 → 5.3.0

package/CHANGELOG.md

@@ -5,23 +5,25 @@ 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.2.1] - 2023-01-31
+## [5.3.0] - 2023-07-06
+
+- Added helper functions for managing parameters in the URL-field.
+
+## [5.2.2] - 2023-01-31
 
-### Changed
+- Fix `parseParams` export.
+
+## [5.2.1] - 2023-01-31
 
 - Fix homepage url.
 - More lenient with peerDependency `@sitevision/api`.
 
 ## [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.
@@ -29,74 +31,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [5.0.0] - 2022-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.
+- Removed `getAppData`, use `getAppProps` instead.
+- Removed `server/render`, use `res.agnosticRender` for framework agnostic rendering.
+- Removed `server/renderTemplate`, used for rendering underscore templates.
 
 ## [4.2.1] - 2021-09-06
 
-### Fixed
-
 - Underscore is misspelled in `renderTemplate`.
 
 ## [4.2.0] - 2021-08-20
 
-### Added
-
-- `getAppProps` for getting props passed to the app when rendering.
-
-### Changed
-
+- Added `getAppProps` for getting props passed to the app when rendering.
 - `getAppData` deprecated due to confusion, use `getAppProps` instead.
 
 ## [4.1.4] - 2021-05-25
 
-### Fixed
-
 - Return empty object instead of undefined when app data isn't set.
-
-### Removed
-
 - Remove `vue` as optional dependency.
 
 ## [4.1.3] - 2021-03-31
 
-### Fixed
-
 - Consistent rendering when using `serverServer` and `render` for Svelte.
-
-### Added
-
 - Docs for Svelte `renderServer` function.
 
 ## [4.1.2] - 2021-02-24
 
-### Fixed
-
 - Escape tags when parsing data to prevent closure of script tags.
 
 ## [4.1.1] - 2021-02-17
 
-### Fixed
-
 - Validation error for `id` on script tags, even though it's allowed.
 
 ## [4.1.0] - 2021-02-17
 
-### Changed
-
 - Put app data and metadata in script elements instead of data attributes.
 
 ## [4.0.1] - 2021-01-28
 
-### Fixed
-
 - Crashes when no data is passed to app and then trying to call `getAppData`.
 
 ## [4.0.0] - 2021-01-27
@@ -104,17 +76,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 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.
 - Settings for selector is moved from server to client rendering functions.
-
-### 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`.
+- Removed `noScript` option in `render` (formerly `renderApp`) has been removed. If a no script message is needed use the `html` option wrapped in `<noscript>`.
+- Removed `@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
 
@@ -126,86 +93,56 @@ See [MIGRATION](./MIGRATION.md).
 
 ## [3.0.1] - 2020-09-28
 
-### Added
-
 - Homepage link
 
 ## [3.0.0] - 2020-09-28
 
-### Added
-
 - Svelte support.
 - New exports:
   - `uniqueId` - A unique id for the app instance.
 
 ## [2.4.1] - 2020-09-01
 
-### Fixed
-
 - App data with single quotes crashes app in edit mode, use double quotes instead.
 
 ## [2.4.0] - 2020-05-26
 
-### Fixed
-
 - `getViewUri` returns correct URI when in offline mode and in the Addons view.
 
 ## [2.3.0] - 2020-05-22
 
-### Added
-
 - `renderApp` now accepts `req` as a setting to opimize script loading when multiple instances of the app exists. If `req` is present the script will only be loaded once in all browsers except IE11 that needs a unique script src for the currentScript polyfill to work.
-
-### Fixed
-
 - `noScript` in `renderApp` was not wrapped in a `<noscript>` tag.
 
 ## [2.2.0] - 2020-05-20
 
-### Added
-
 - `renderTemplate` function is now available inside templates rendered by the function.
 
 ## [2.1.4] - 2020-04-07
 
-### Fixed
-
 - `getViewUri` had incorrect portlet ID.
 
 ## [2.1.3] - 2020-02-25
 
-### Fixed
-
 - Add timestamp to script url in edit mode as well.
 
 ## [2.1.2] - 2020-02-21
 
-### Fixed
-
 - Wrapped `renderApp` script in svDocReady in edit mode to be sure it executes when other bundles are loaded.
 
 ## [2.1.1] - 2020-02-14
 
-### Changed
-
 - Updated readme, heading levels and examples.
 
 ## [2.1.0] - 2020-02-14
 
-### Added
-
 - App data import in client, `@soleil-api/webapp-util/app-data`.
 - `getViewUri` to get the URI that also renders the page.
 - `isOnline` to see if the app is online.
-
-### Changed
-
 - `vue` is now an optional depedency.  
 
 ## [2.0.0] - 2020-02-12
 
-### Changed
-
 - Now using `currentScript` to reference the script element the app is running in to pass data when using `renderApp`.
 - `renderApp` is no longer using appName.
 - `render` is now called directly in `./app_src/client/index.js`.

package/README.md

@@ -52,7 +52,7 @@ Integrity check failed for "@soleil-se/webapp-util" (computed integrity doesn...
 Migrating from version 4?  
 See [MIGRATION](./MIGRATION.md).
 
-## API
+## Common
 
 All imports from base package are available both on the server and client.
 
@@ -210,6 +210,78 @@ const params = parseParams('?foo=bar&arr[]=1&arr[]=2');
 // { foo: 'bar', arr: [1, 2] }
 ```
 
+## Client
+
+Following API:s are available in a client context.
+
+### URL Parameters
+
+Helper functions setting, getting, updating and clearing query parameters in the URL-field.
+
+#### getUrlParams() ⇒ `Object`
+
+Get parameters from the URL-field.
+
+**Returns**: `Object` - Parameters in URL-field.
+
+```js
+import { getUrlParams } from '@soleil-se/webapp-util/client';
+
+const params = getUrlParams();
+```
+
+#### getUrlParam() ⇒ `String|Array[String]`
+
+Get single parameter from the URL-field.
+
+**Returns**: `String|Array[String]` - Parameter value.
+
+```js
+import { getUrlParam } from '@soleil-se/webapp-util/client';
+
+const param = getUrlParam('name');
+```
+
+#### setUrlParams(params)
+
+Set parameters in the URL-field, overwriting other parameters.
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| params | `Object` | | Object with parameters to set in the URL-field. |
+
+```js
+import { setUrlParams } from '@soleil-se/webapp-util/client';
+
+setUrlParams({ foo: 'bar', arr: [1, 2] });
+```
+
+#### updateUrlParams(params)
+
+Update parameters in the URL-field, merging with existing parameters
+
+**Returns**: `String` - Stringified parameters.
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| params | `Object` | | Object with parameters to add to the URL-field. |
+
+```js
+import { updateUrlParams } from '@soleil-se/webapp-util/client';
+
+updateUrlParams({ foo: 'bar', arr: [1, 2] });
+```
+
+#### clearUrlParams()
+
+Clear parameters in the URL-field
+
+```js
+import { clearUrlParams } from '@soleil-se/webapp-util/client';
+
+clearUrlParams();
+```
+
 ## Rendering
 
 * [Svelte](./docs/1.svelte.md)

package/client/index.js

@@ -0,0 +1,7 @@
+export {
+  getUrlParam,
+  getUrlParams,
+  setUrlParams,
+  updateUrlParams,
+  clearUrlParams,
+} from './url-params';

package/client/url-params/index.js

@@ -0,0 +1,52 @@
+import { stringifyParams, parseParams } from '../../common';
+
+const isEmpty = (obj) => Object.keys(obj).length === 0 && obj.constructor === Object;
+
+/**
+ * Set query parameters in the url-field.
+ * @param {Object} obj - Values to be set.
+ * @param {Object} [options] Optional options.
+ * @param {Boolean} [options.scoped = false] If parameter keys should be scoped to current app.
+ */
+export function setUrlParams(params) {
+  window.history.replaceState({}, '', (isEmpty(params) ? window.location.pathname : `?${stringifyParams(params)}`));
+}
+
+/**
+ * Get query parameter from the url-field.
+ */
+export function getUrlParam(key) {
+  const params = parseParams(window.location.search.substring(1));
+  return params[key];
+}
+
+/**
+ * Get query parameters from the url-field.
+ */
+export function getUrlParams() {
+  const params = parseParams(window.location.search.substring(1));
+  return params;
+}
+
+/**
+ * Clear query parameters in the url-field.
+ */
+export function clearUrlParams() {
+  window.history.replaceState({}, '', window.location.pathname);
+}
+
+/**
+ * Updates query parameters in the url-field.
+ * @param {Object} params - Values to be updated.
+ */
+export function updateUrlParams(params) {
+  setUrlParams(Object.assign(getUrlParams(), params));
+}
+
+export default {
+  getUrlParam,
+  setUrlParams,
+  getUrlParams,
+  clearUrlParams,
+  updateUrlParams,
+};

package/common/index.js

@@ -1,4 +1,3 @@
-/* global document console */
 /* eslint-disable global-require */
 import router from '@sitevision/api/common/router';
 import app from '@sitevision/api/common/app';
@@ -84,7 +83,7 @@ export function stringifyParams(params = {}, { addQueryPrefix = false } = {}) {
  * @param {String} url URL or URI to be parsed, must start with or contain "?".
  * @returns Object with parsed parameters.
  */
-export default function parseParams(url = '') {
+export function parseParams(url = '') {
   const hasQuestion = url.indexOf('?') > -1;
   if (!hasQuestion) return {};
 
@@ -116,7 +115,7 @@ export default function parseParams(url = '') {
  * @param {object} params Query parameters.
  * @returns {string} URI for route.
  */
-export function getRouteUri(route = '', params) {
+export function getRouteUri(route = '', params = undefined) {
   const path = route.replace(leadingSlashes, '');
   const qs = stringifyParams(params, { addQueryPrefix: true });
   if (router?.getStandaloneUrl) {
@@ -133,13 +132,13 @@ export function getRouteUri(route = '', params) {
  * @param {string} route A route.
  * @returns {string} URI for view.
  */
-export function getViewUri(route = '', query) {
+export function getViewUri(route = '', params = undefined) {
   if (!router?.getUrl) {
     console.warn('[@soleil-api/webapp-util] getViewUri requires router.getUrl support.');
     return undefined;
   }
 
-  return router.getUrl(route, query);
+  return router.getUrl(route, params);
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soleil-se/app-util",
-  "version": "5.2.1",
+  "version": "5.3.0",
   "description": "Utility and rendering functions for WebApps.",
   "main": "./common/index.js",
   "author": "Soleil AB",
@@ -14,6 +14,6 @@
   "peerDependencies": {
     "@sitevision/api": "*"
   },
-  "gitHead": "ed8ed7ee555f004e3b712c868cf095aab1c9a804",
+  "gitHead": "1928f2e710e25b16b0e3a792bb8d6b9254d72084",
   "dependencies": {}
 }

package/client/.eslintrc.js

@@ -1,4 +0,0 @@
-module.exports = {
-  extends: '@soleil/eslint-config-sitevision/client',
-  root: true,
-};