Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mercmobily/hot-network

Add network resilience to widgets using iron-ajax
https://github.com/mercmobily/hot-network

Last synced: 2 days ago
JSON representation

Add network resilience to widgets using iron-ajax

Awesome Lists containing this project

README 

        
[![Published on webcomponents.org](https://img.shields.io/badge/webcomponents.org-published-blue.svg)](https://www.webcomponents.org/element/mercmobily/hot-form)



Too many applications today have AJAX calls that are made without proper error checking. This leads to applications with strangely empty select widgets, and requiring a hard reloads in order to (hopefully) display properly. Network resiliance code is boilerplate, and it's often repeated for each call.



`hot-network` is used to wrap another element that makes AJAX calls, in order to make it Unclickable/gray while the AJAX call is going on

It will also (optionally) manage errors so that it will:

  * Give a differently themed overlay if the call didn't work

  * Give the option to retry a failed AJAX call by clicking on the overlay

  * Communicate to the user in case of problems



The overlay is fully themable with CSS mixins.



# How decorated elements are dealt with



In order to function, hot-network must know the status of the decorated element in order to change its status. This is the rundown of the requirements:



* The decorated element is always the first child of `hot-network`

* `hot-network` will listen to the events `submit`, `request`, `response`, `error` from the decorated element

* You can set `event-prefix` if the element emits the events listed above with a prefix beforehand

* IRON-FORM is a special case: the prefix `iron-form-` is added automatically

* In order to reload in case of loading error, the decorated element's `reload()` or `generateRequest()` is called.

* You can set `reload-method` to something else if your decorated element exposes a different method to reload



# Basic use: make contained element unclickable while AJAX is going on



All you have to do in order to get a contained element unclickable while the AJAX call is going, is wrap it with ``. Make sure the widget making the AJAX call is the first child of ``:



    

      

        

        Click!

      

    



`` will only ever have two states: "loading" (widget is overlayed) or "loaded" (no AJAX call is happening).



# Error management



You can use `` for widgets that are build to display data after making an AJAX call. In this case, you will want to turn on ``'s error management:



    

      

    



In this case, `` will be in one of three states: "loading", "loaded", "error".



When in "error" state, `` will still be overlayed and unreachable. However, when tapping on the overlay, the AJAX call will be attempted again when overlay is tapped.



If `manage-error` is on, in case of error `` will fire a `user-message-error` event with the message in the detail, like this: `{ message: "Error!" }`. The error message can be customised by setting the `user-message-error` attribute:



    

      

    



A UI widget should pick up this message event and display it to the user.



Note that `manage-errors` doesn't make sense in a form context because 1) A form that has an error will likely emit its own user message event 2) A form that fails doesn't need to be overlayed to retry: the user will be able to click on the "Submit" button again.



# Usage with ``



The `` element should be wrapped by `` if it's configured to load data. So, when using a form with ``, you should to use two `` elements:



* one decorating `hot-form`, in order to gray the form while loading initial data _and_ give users a chance to re-run the request in case of errors

* one decorating `iron-form`, to gray out the form while the data is being submitted (errors won't be managed since it wouldn't make sense here).



So:



    

      

        

          

            

            

            

            Active?

            Click!

          

        

      

    



Voila': you have a form that pre-loads and submits data, and that is 100% network-aware:



* During data-loading, the form will be gray

* If data-loading fails, users will be able to re-attempt it (and view an error message)

* While submitting data to the server, the form will be gray



Note that with just one small decorating elements, you end up with a network-aware form.