0.0.11 • Published 2 years ago
web_page_state v0.0.11
Page State Helper for client side websites
Utility hooks to help organize a site's client-side state, and easily change the view according to state through html data attributes. Conceptually combines ideas from Bootstrap & Redux.
Import:
- Web:
<script src="https://unpkg.com/page_state/build/bundle.min.js"></script> - Node:
npm i web_page_state
How to use?
- HTML
| Attribute | Note | Example |
|---|---|---|
| data-ws-show-if | Show element if ANY (ie OR) of the state props specified in the attribute (space separated) is true, otherwise set 'display' style to 'none'. To achieve AND simply nest elements. | - Simple: <button data-ws-show-if="isSignedIn">Sign Out</button> - OR: <div data-ws-show-if="isIOS isAndroid">You are on iOS OR Android</div> - AND: <div data-ws-show-if="isSignedIn"><p data-ws-show-if="isIOS"><Welcome user on iOS</p></div> |
| data-ws-show-if-not | Show element if ANY (ie OR) of the NEGATED state props specified in the attribute (space separated) is true, otherwise set 'display' style to 'none' | <button data-ws-show-if-not="isSignedIn">Sign In</button> |
| data-ws-label | Replaces the element's innerText with the prop's value | <p>Welcome <span data-ws-label="user.name"></span></p> |
- js
| Property | Type | Description |
|---|---|---|
| pageState | Object | Holds the raw state. |
| updatePageStateWithParams | Function | Examples: updatePageStateWithParams({countryName: "Brazil"}) |
| toastNotification | Function | Example: toastNotification("Copied", "Successfully copied to clipboard", false, false); |
| dismissNotification | Function | Remove previously toasted notification |
| setUser | Function | Examples:- On sign in: setUser({name: "Ronen", uid: "987dkjbc987"}); - On sign out: setUser(null); |
| getParam | Function | getParam("user.uid"); |
| toggleParam | Function | toggleParam("isFullScreen"); |
| registerListener | Function | Returns the index / id as number of the new listener. This index can be used to remove the listener. Example: let index = PageState.registerListener(function(newState){/* do something */}); PageState.unregisterListener(index); |
| unregisterListener | Function | Use the index generated when 'registered'. Example: let index = PageState.registerListener(function(newState){/* do something */}); PageState.unregisterListener(index); |
- State's special keys - do not set directly
// TODO: Prohibit direct setting by mistake?
| Key | Type | |
|---|---|---|
| user | Object, set with setUser | |
| isNotification | boolean, semi-automatic: based on 'toastNotification' | |
| notificationTitle | boolean, semi-automatic: based on 'toastNotification' | |
| notificationMsg | boolean, semi-automatic: based on 'toastNotification' | |
| platform | String, automatic | |
| isMobile | boolean, automatic | |
| isIOS | boolean, automatic | |
| isAndroid | boolean, automatic | |
| isOffline | boolean, automatic | |
| isSignedIn | boolean, semi-automatic: based on 'user' |
How to use?
When used in browser:
Place the following at the end of the body tag, and prior to using the wsGlobals.PageState.updateStateWithProps
<script src="https://unpkg.com/page_state/build/bundle.min.js"></script>No need to initialize - it is initialized in code.
When used in a webpack / other node client-side webpage builder:
Use import or require...
// TODO: Do we need to initialize? Check...
Showcases
This is used on the following sites:
TODOs:
- In
data-ws-show-if-notwe let the function - if exists - override the property, which is inconsistent with the non-negateddata-ws-show-if... - Prohibit direct setting of reserved props / functions by mistake?
- Set/get style to the element's html set style prior to setting it to "none"
How to contribute & publish updates to this package?
- This package is published both on GitHub and on npmjs.
- To publish an updated version - simply run
npm publish, it will commit & push updates both to github and npm.