Loading Indicators in Components

This is an ACSS design feature for custom elements.

This section is only applicable to components that have the potential to take a while to load, such as components that depend on ajax calls to fetch their content. If you have a component that is guaranteed to display quickly, you do not need to do this. Loading indicators are a courtesy, or a notification, to your users, to let them know that something is being loaded onto the page. It stops them from double clicking on things and getting confused about why nothing is happening on the page. Obviously, it is best that your users don't wait around at all, but sometimes you may have a situation where a delay of some kind is inevitable.

 

Normally, if you are drawing a custom element component in HTML to fetch a database record from a server, you would do something like this in your HTML:

<address-details data-id="1"></address-details>

That example could imply that whenever the <address-details> element was displayed on the page, it would set off a chain of events that would result in a request to the server for HTML related to a record from a database with an id field value of "1". And the subsequent goal would be to place that returned HTML into the <address-details> element itself.

To use components, you are not limited to fetching database records - you can do a lot of things. But as fetching records is a common use for loading indicators, that is the example we will use.

 

If the component needs to fetch HTML from the server, you have two choices:

1) You can place a loading indicator in the component itself, which disappears when the component finally renders, or

2) You can have a separate loading indicator elsewhere on the page, which is disrelated to the component itself.

 

Let's recap on what a basic "HTML load from the server"-type component looks like.

Say that you want to invent the element <address-details>, and you want it to be filled with dynamic HTML from the server every time it is displayed on the page (or you want to render a view, if you are running an MVC framework back-end). The component may look something like this:

@component address-details
        html("/fetch-address/{$data-id}" get html)
    {
    /* ... events would go here */
}

That is all that you need to do to set up a custom element component in ACSS, if you are only filling it with data from the server. There are a lot more options in the @component syntax itself, but if you just want to display data based on an GET endpoint like the above, that is all you need. Whenever the custom element <address-details> is drawn on the page, the component will call the server and fill it with the returned HTML string, solely by using the above code.

We will cover the first loading indicator option first.

Displaying a loading indicator in the component itself

This is very simple, you just place the HTML that you want for the indicator inside the HTML for the component, like this:

<address-details data-id="1">
    <div class="myFancyLoadingAnimation></div>
</address-details>

You are not limited to one div. Multiple child nodes are ok to use.

All the children of the component, ie. the div tag in the above example, will disappear when the component loads.

That's it.

Note: If you discover the need to re-render the children of any component in the component itself when it is finally drawn, you would place the variable {$CHILDREN} inside the component's HTML, where you want it to be re-rendered when the component loads, and put the accept-vars option on the html option in the @component statement,  like html("/fetch-address" accept-vars ...). But you wouldn't need to worry about that at all, if all you needed was a loading indicator.

 

Displaying a loading indicator elsewhere on the page

This is a bit more fancy. You may have some JavaScript that you need to call, or draw a CSS animation is a specifically place on the page.

If so, this is the method you would use.

As you may have guessed, we need to employ events for this.

Which event gets triggered before a component is first drawn on the page? That event is the draw event. So we can do the following. This example will put a class of "ajaxAnimation" on the body node, so that you could have some CSS that displays a hidden element somewhere on the page which contains loading animation:

address-details:draw {
    body {
        add-class: .ajaxAnimation;
    }
    /* (or trigger some JavaScript or another ACSS event) */
}

Assuming that you've set up your CSS correctly (this isn't a tutorial on how to create loading animation CSS), that code will start the loading indicator. But where to end it? In the component itself, in the componentOpen event. That is the event that is called as soon as the component has finished getting anything from the server and has finished rendering on the page. So we can do this:

@component address-details
        html("/fetch-address/{$data-id}" get html)
    {
    &:componentOpen {
        body {
            remove-class: .ajaxAnimation;
        }
        /* (or trigger some JavaScript or another ACSS event) */
    }
}

So there are two events to populate in your code. The draw event, which is called before the component starts to be analysed by the ACSS core, and the componentOpen event, which is called after the component has finished rendering on the page.