173 lines
8.3 KiB
Markdown
173 lines
8.3 KiB
Markdown
# Standard UI
|
|
|
|
### How to use Standard UI
|
|
There are several pre-built layouts in **layouts** folder. Pick any one of them that's more suitable for your particular project.
|
|
|
|
#### What's included in layouts by default?
|
|
- Components ( sm-button, sm-input, sm-notifications, sm-popup, theme-toggle and optional components specific to respective layout )
|
|
- Main_UI.js - A JS library that includes utility functions and some common functionality.
|
|
- Standard operations - A JS library **created by RanchiMall** to create DAPPs easily.
|
|
|
|
Now that we know what's included in layouts, let's dig a little deeper and know exact functionality of each of these.
|
|
|
|
## Components
|
|
These are the building blocks of modern web development process. We are a frameworkless environment so we decided to go with **native Web Components** as a way to create reusable components. There are lot of these already created and ready to use.
|
|
### Get a hands-on experience and documentation at [our components website](https://ranchimall.github.io/standard-ui/components/).
|
|
|
|
## main_UI.js
|
|
This is a collection of utility and commonly used functions that will help ease the development process.
|
|
|
|
### Global variables
|
|
|
|
| Variable | Description |
|
|
| --- | --- |
|
|
| appPages `array` | Add the IDs of pages that your app contains. This is used by `showPage()` to determine whether the hashchange was caused by a link that traverses pages or not |
|
|
| domRefs `object` | This global object is used by `getRef() ` to store repeatedly used DOM references. You don't have to change anything about it manually |
|
|
|
|
#### Functions
|
|
|
|
### getRef()
|
|
Use this function instead of `document.getElementById()`. It provides reference memoization for repeatedly used DOM references. This negates the need to store DOM references at top of script or inside global variables.
|
|
#### Parameters
|
|
`getRef(elementId)`
|
|
This function has only one parameter.
|
|
| Parameter | Description |
|
|
| --- | --- |
|
|
| elementId `string`| Pass in the ID of the element you want to get reference of exactly like `document.getElementById()`|
|
|
|
|
|
|
### createElement()
|
|
This function let's you create elements with less boilerplate.
|
|
#### parameters
|
|
`createElement(tagName, options = {})`
|
|
This function has only one parameter.
|
|
| Parameter | Description |
|
|
| --- | --- |
|
|
| tagName `string`| Pass in the type of element you want to create. eg. `createElement('div')` |
|
|
| options `object`| Specify different aspects of element you want to create|
|
|
|
|
#### Possible options
|
|
| key | Description |
|
|
| --- | --- |
|
|
| className `string`| Sets class(es) for element. you can pass in multiple classes like `'flex align-center'` |
|
|
| textContent `string`| This is similar to setting `element.textContent`. Pass in string that should be text inside the element|
|
|
| innerHTML `string|template literal`| This is similar to setting `element.innerHTML`. Pass in string that should be rendered as HTML elements|
|
|
| attributes `object`| This is similar to setting `element.setAttribute()`. The advantage being you can pass in multiple attributes at one as key-value pairs. eg. `{attributes: {'data-theme': 'dark', 'id': 'unique_id'}`|
|
|
|
|
|
|
### debounce()
|
|
This function forces a function to wait a certain amount of time before running again.
|
|
#### parameters
|
|
`debounce(callback, wait)`
|
|
| Parameter | Description |
|
|
| --- | --- |
|
|
| callback `function`| The function which needs to wait a certain time before running again |
|
|
| wait `milliseconds`| The time period for which function should wait before re-running |
|
|
|
|
|
|
### throttle()
|
|
This function limits the rate of function execution.
|
|
#### parameters
|
|
`throttle(func, delay)`
|
|
| Parameter | Description |
|
|
| --- | --- |
|
|
| func `function`| The function that will be limited to run once per specified time frame |
|
|
| delay `milliseconds`| The time period for which function will run once |
|
|
|
|
|
|
### showPopup()
|
|
This will display popup of which the ID was passed in. In addition to that this also keeps a track of which popups are open and allows stacking them on top of each other.
|
|
#### parameters
|
|
`showPopup(popupId, pinned = false)`
|
|
This function has only one parameter.
|
|
| Parameter | Description |
|
|
| --- | --- |
|
|
| popupId `string`| ID of popup that needs to be displayed. |
|
|
| pinned `Boolean`| Boolean if set `true`, displayed popup won't closes unless `hide()` is called programatically on the popup. |
|
|
|
|
|
|
### hidePopup()
|
|
The opposite of `showPopup()`. When called, this will close any popup that's currently open and is on the top of popup stack.
|
|
#### parameters
|
|
This function doesn't accept any parameters
|
|
|
|
|
|
### getConfirmation() `Promise`
|
|
This is replacement method for native `confirm()` method. This returns a promise.
|
|
|
|
#### parameters
|
|
`getConfirmation(title, message, cancelText = 'Cancel', confirmText = 'OK')`
|
|
| Parameter | Description |
|
|
| --- | --- |
|
|
| title `string`| Heading or gist of the cofirmation message that will be displayed to user while asking for confirmation. |
|
|
| message `string`| A detailed description of the subject regarding which the confirmation is being asked. |
|
|
| cancelText `string`| Customizes the text of rejecting confirmation button. |
|
|
| confirmText `string`| Customizes the text of accepting confirmation button. |
|
|
|
|
|
|
### getPromptInput() `Promise`
|
|
This is replacement method for native `prompt()` method. This returns a promise.
|
|
|
|
#### parameters
|
|
`getPromptInput(title, message = '', isPassword = true, cancelText = 'Cancel', confirmText = 'OK')`
|
|
| Parameter | Description |
|
|
| --- | --- |
|
|
| title `string`| Heading or gist of the prompt message that will be displayed to user while asking for input. |
|
|
| message `string`| A detailed description of the subject regarding which the prompt is being asked. |
|
|
| isPassword `Boolean`| If set `true`, the input box inside the prompt will hide the input as password. |
|
|
| cancelText `string`| Customizes the text of rejecting prompt button. |
|
|
| confirmText `string`| Customizes the text of accepting prompt button. |
|
|
|
|
|
|
### notify()
|
|
This function add functionality to `sm-notifications` component by adding icons and notification sound to improve the UX.
|
|
** Remember to use notifications only when absolutely needed. Don't overwhelm user with lots of notifications **
|
|
#### parameters
|
|
`notify(message, type, options = {})`
|
|
| Parameter | Description |
|
|
| --- | --- |
|
|
| message `string`| The message that needs to be displayed to user as a notification. |
|
|
| type `string`| Defines the type of notification. eg. `success`, `error` |
|
|
| options `object`| Extra options to customize notification behaviour|
|
|
|
|
#### Possible options
|
|
| key | Description |
|
|
| --- | --- |
|
|
| pinned `Boolean`| If set `true`, the notification won't disappear automatically after timeout. user has to manually dismiss the notification. |
|
|
| sound `Boolean`| If set `true`, notification sounf is played when a new notification arrives. |
|
|
|
|
|
|
### showPage()
|
|
This function is used to change which page is visible to user. It uses `appPages` array to switch between correct page when `hashchange` event is fired.
|
|
#### parameters
|
|
`showPage(padeId)`
|
|
| Parameter | Description |
|
|
| --- | --- |
|
|
| pageId `string`| ID of the page that needs to be displayed. |
|
|
|
|
|
|
### Event listeners
|
|
There are several event listeners added that listen for some basic changes in app life-cycle
|
|
|
|
### `online` and `offline`
|
|
These event listeners listen for changes in internet connectivity. Whenever app is disconnected from internet user will receive a notification displaying status of connection.
|
|
|
|
### `load`
|
|
This event is used to attack further event listeners when page resources are completely loaded. Also if app URL contains a page hash it'll also display that page.
|
|
|
|
### `hashchange`
|
|
This event notices the changes in hash in URL bar. If the changed hash is one of the appPages then that page will be displayed.
|
|
|
|
### `keyup`
|
|
Use this event listener if you want to add some keybinding at document level. By default it has keybinding to hide an open popup when `ESC` key is pressed.
|
|
|
|
### `pointerdown`
|
|
Mostly used to display ripple over the interactive elements. Any element containing `interact` class will receive ripple when clicked by user. You can customize the list of elements which receive ripple inside createRipple callback.
|
|
|
|
### `copy`
|
|
This is a purely UX feature, that shows a notification whenever user copies any content from the web app.
|
|
|
|
|
|
## Standard operations
|
|
### Complete documentation for standard operations can be found [here](https://github.com/ranchimall/Standard_Operations#readme)
|