API Design

[SimplGy]

Trying to get my head around the different use cases folks have for deferred directive loading from this ticket.

At first read, I thought most folks were looking to delay the execution of a post-link function and controller associated with a directive until after some dependencies had resolved. I noticed angular-wait's slugline implies a focus on load state:

Angular directive for showing pending ("loading...") content

Another good use case.

I see it's transcluding content. When someone puts a directive inside <wait-done>, do you know which steps would be executed BEFORE the wait resolves? compile? controller? pre-link? post-link? I think it would do the compile but nothing else, right?

If all you need is deferred directive evaluation, a syntax that emphases the optional-ness and composability of the feature might be preferable:

<user-profile-form waits="user"></user-profile-form>

If the focus is on indicating load state, a syntax that emphasizes the either/or-ness of the situation may be better, like what you have now.

Anyway, sort of thinking out loud, but also trying to figure out how many of the steps in the compile process are possible to defer.

[michikono]

Hey, thanks for your feedback. As discussed let's talk architecture. I'm open to making modifications. What you're suggesting is something I thought about, so I hope I'm able to get my point across as to why I designed it this way.

Aside: Answering rendering question

I see it's transcluding content. When someone puts a directive inside , do you know which steps would be executed BEFORE the wait resolves? compile? controller? pre-link? post-link? I think it would do the compile but nothing else, right?

Edit: Writing this answer required me to run some tests. I need to push a fix that adds terminal: true to the wait-done directive. This prevents it from running until it is transcluded in. This fix prevents compile, controller, and link methods from running.

Edit #2: Fix completed. 1.0.2 solves this issue.

Design Goal

• Be explicit about what's loading state and what's done state
• Support loading state views easily
• Handle transcluded content (not just strings)
• Not process directives that are inside the done state until ready
• Optional done state (so it can be used for things like loading page overlays)

Having a load state was a key requirement as the primary purpose for a directive is to dislpay content. A missing feature in directives is to have placeholders without extra custom logic. While a resolve would be half a solution, there would still need bridging logic to then have the delay reflected in the UI. Ultimately, this is what most people were complaining about in that ticket. That's how I came to this idea.

Design Considerations

So the original version of this (pre-first-commit) had the wait as an attribute attached to other directives. While I didn't fully finish it, there were a couple of things that gave me pause:

String-based load states

Using loading-text="message" type of directive for loading content was impractical (this feels like the most obvious solution, but it was actually very restricting).

<custom-directive wait-until-undefined="user" loading-text="loading..."></custom-directive>

Originally, I attached the "loading message" as another directive attribute (scope var), but I found that limiting because now I couldn't put other directives or HTML content in there. And since I saw that showing a spinner or something was a common use case, I felt that was too limiting.

The solution to this problem made me re-think the approach and this is where it started to appear closer to ng-if type solutions where the wrapped directives wouldn't get processed until ready (which is how I got to that thread).

Uncertain Rendering Order

Determining a rendering priority that made sense. A high priority means superceding other directives, which would prevent them from rendering until AFTER my directive applies first. Of course, if it uses data the current directive needs, then you would want the opposite: a low priority. I can best illustrate it with the following example:

<!-- high priority use case-->
<div ng-repeat="entry in entries" wait-until-not-undefined="entries">
    <div>{{entry}}</div>
</div>

Which should come first, ng-repeat (which is a very high priority directive) and then wait, or vice versa (where ng-repeat wouldn't even be seen until there is data)? Well, this might be some-what clear in the ng-repeat case, imagine if an attached custom directive modified a scope variable that you are watching for.

Rather than deal with this uncertainty (for the caller), I decided it was simpler to avoid the entire discussion of priorities and have the HTML structure explain how things should render.

Predictable Behavior

I am preferential to an API that is consistent and predictable. For example, I am opposed to adding a text-loading-message="" type of directive since it would cause confusion or conflicts if used with the wait-done directive. In this example, I would choose one or the other, but not both. Any additions or changes that would cause conflicting behavior (or attributes getting ignored based on other ones being present) is not desirable.

Solutions

Current Solution

<wait until-not-undefined="myAsyncValue">
  <wait-loading>loading...</wait-loading>
  <wait-done>{{myAsyncValue}}</wait-done>
</wait>

Uses HTML/directive nesting to be explicit about what is loading and what is done content.

Pros

• Rendering order is explicit
• Supports usage in directives with or without transclusion (see next solution)

Cons

• Verbose

Assume Use as an Attribute

<custom-directive wait-until-not-undefined="myAsyncValue">
  <wait-loading>loading...</wait-loading>
  <wait-done>{{myAsyncValue}}</wait-done>
</custom-directive>

The problem with this flow is that if custom-directive is just a regular div, this structure makes sense. However, if custom-directive has its own content, do we need a wait-done? What happens if you have both wait-done and a directive that doesn't use transclusion?

Pros

• Support for altering element directives

Cons

• Rendering order ambiguous
• API becomes inconsistent: wait-done is only useful when no transclusion

Follow Angular UI Tab model

<custom-directive wait-until-not-undefined="user">
    <wait-loading>spinner HTML</wait-loading>
    Done content
</custom-directive>

I actually had considered this as the first draft I was giong to publish. Angular UI uses this method for their tabs, however, I'm not the hugest fan for the structure since it implies the outer directive (custom-directive) does its thing before the inner part wait-loading is processed (and as I mentioend earlier, I wasn't sure which was the more designed behavior). In the tab's case, the other content being rendered doesn't matter, but in our case it does.

Pros

• Less verbose

Cons

• Order not clear if attached to a custom element directive (custom-directive)

---

Hope this helps explain things better. Let me know your thoughts.