ember-loading

ember-loading
==============================================================================

!CI

A simple Ember.js addon to capture and expose the loading state of your app,
so you can show that to the user with e.g. a loading indicator.

*But Ember has loading substates
so why do I even need it?*

This is true, and works basically like this: when the user transitions from
/foo to /bar, the DOM previously rendered through foo.hbs will be removed,
the loading.hbs template renders while loading of the bar route is in progress,
after which bar.hbs is rendered. That's fine, if it is what you need.

But another UX approach would be to keep foo.hbs rendered and add any kind of
loading indicator on top of it (e.g. an overlay over the existing content) or
somewhere else on the page while loading, and replace the rendered foo.hbs
with bar.hbs only when loading has finished.

What else?

This addon helps you also to show the loading state for async processes
besides transitioning between routes, e.g. when you load or save data in a
controller/component.

How does it look like?

It is completely agnostic of any looks. It merely provides some basic
infrastructure to capture and expose the loading state. To actually render
your loading indicator, you can use your own custom styled component or any of
the existing loading indicator addons.

Compatibility
------------------------------------------------------------------------------

* Ember.js v3.20 or above
* Ember CLI v3.20 or above
* Node.js v12 or above

Installation
------------------------------------------------------------------------------

``
ember install ember-loading
`


Usage
------------------------------------------------------------------------------

The addon's central piece is the loading service, which captures and exposes
the app's loading state.

$3

#### Using the service

The loading service exposes the following properties, which you can use to
render your loading indicator in any way:

| Property | Description |
|------------------------|-----------------------------------------------------------------------|
| isLoading: Boolean | Will be true if any captured async processes (see below) are pending. |
| showLoading: Boolean | Will be true based on isLoading, but will take optional preDelay and postDelay into account, to optimize for the visual appearance. See Configuration below. |

#### Using while-loading

Rather than explicitly injecting the loading service and using an {{#if}}
block in your template, you can more conveniently use the while-loading
component to wrap any content that should be shown only while loading:

`hbs
{{#while-loading}}

{{/while-loading}}
`

$3

#### Route transitions

The service will automatically recognize route transitions (i.e. async model
hooks) and set the service's loading state accordingly.

#### Custom actions

Whenever you kick off async processes that you want to show to the user, and
which are not part of any of a route's model hooks, you can use the service's
run() function, which will call your own async function, and set the
services's loading properties accordingly.

`js
import Controller from '@ember/controller';
import { inject as service } from '@ember/service';

export default Controller.extend({
loading: service(),

actions: {
save(model) {
return this.loading.run(() => model.save());
}
}
})
`

The run() method has the following signature, similar to many of Ember's
runloop functions:

| Arguments / Return value | Description |
|----------------------------|----------------------------------------------------------------------|
| target: any | optional target of method to call |
| method: Function\|string | Async method to invoke. May be a function or a string. If you pass a string then it will be looked up on the passed target. |
| ...args: any[] | Any additional arguments you wish to pass to the function. |
| returns | Promise that resolves with the return value of the invoked function. |

#### Decorator

If you use native classes and decorators, you can use the supplied @loading decorator to wrap any native method.

> The decorator uses stage 1 syntax, meant to be used with TypeScript and/or ember-cli-babel V7.7.0+

`js
import Controller from '@ember/controller';
import { action } from '@ember-decorators/object';
import { loading } from 'ember-loading';

export default class Foo extends Controller {

@action
@loading
save(model) {
return model.save();
}
}
`

$3

The addon supports the following configuration options in your config/environment.js, under the
ember-loading key:

| option | Default | Description |
|-------------------------------|---------|------------------------------------------------------------|
| preDelay: number | 0 | Amount of milliseconds to delay the showLoading property (see above) going from false to true. This allows you to suppress the loading indicator appearing for very short loading times. |
| postDelay: number | 0 | Amount of milliseconds to delay the showLoading property (see above) going from true to false. This can help you with aggregating multiple async processes happening in succession, to prevent flickering of the loading indicator. |
| watchTransitions: Boolean | true | If false, async transitions do not affect the isLoading` property. |

Contributing
------------------------------------------------------------------------------

See the Contributing guide for details.

License
------------------------------------------------------------------------------

This project is licensed under the MIT License.