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.

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`
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