From e2e8a18a9f63e9b95e13d8e42dac7ffc1882eb2d Mon Sep 17 00:00:00 2001 From: sairaj mote Date: Tue, 20 Jul 2021 16:18:08 +0530 Subject: [PATCH] Added documentation for layouts and standard UI --- README.md | 172 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 164 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index fcdcbcd..b3c796a 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,172 @@ # Standard UI -### How to use Standard UI - A summary: -Pick a layout you need, add components.js to it, then use notification sounds if your project has sound based notification +### 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. -#### To start, pick one layout among different layouts we have provided in Layouts folder. Every layout is like approved stand-alone HTML visual template on which UI functionality needs to be added. Then add components.js from Standard UI Components folder. This will give access to functional visual elements in your layout template page. Then you can add the rest of functionality +#### 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. -#### We provide four kinds of layouts: A webpage which is box based, a webpage which is tab based, a webpage which has many sections, and a webpage which has sidebars. Depending upon the web project you are doing, pick one of the layouts. Picking the layout is the first task in usage of RanchiMall Standard Visual Design System. You can customize the base layouts with your own colour scheme. +Now that we know what's included in layouts, let's dig a little deeper and know exact functionality of each of these. -#### To use Standard UI Components, Go to Standard UI Components folder, and link or add components.js to your project. Read the detailed documentation inside the Standard UI Components for instructions on how to use +## 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/). -#### aggregate.js contains all common visual js used in RanchiMall projects. Normally you will not need it. But if you like one of the common UI features in any of RanchiMall apps, it is available here +## main_UI.js +This is a collection of utility and commonly used functions that will help ease the development process. -#### aggregate.svg contains all common visual svg elements used in RanchiMall projects. Users get access to all our SVG that we have actually used from all the projects from aggregate.svg +### Global variables -#### We also provide approved notification sounds for RanchiMall applications. These are available in Notification Sounds folder. +| 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)