Priorities

Many elements of an Infusion application (in particular, Listeners, Model Listeners, Options Distributions and Subcomponents) accept a standardised entry named priority which allows the position of that element within a list of similar elements to be adjusted. Depending on what the element is, the effect of the priority will be different — for example, a listener may be notified earlier or later than another listener, or a set of options or grades may take priority over another during options merging.

The priority system is designed to be "open" in the face of evolving application designs that are worked on by different groups. As well as standard fixed priorities (represented by numbers or extremal values such as "first" or "last"), Infusion priorities may be constraint-based in which an element defines its priority only with respect to another element which is identified by namespace. The syntax and idiom for namespaces follows that for event listeners. These constraint-based priorities are much less brittle than the use of fixed priorities, and are recommended whenever a priority directive seems to be required.

Supported values for priorities

Note that the framework's algorithm for sorting by priority uses a stable sorting algorithm so that in the absence of any priorities, any original ordering of the elements will be preserved. Elements without any priority will sort close to those which have been specified with an explicit numeric priority of 0, whilst retaining any original relative ordering. In the case of event listeners, this will be significant since it will respect any procedural order of addition, as well as any order resulting from grade merging. For options distributions, the natural ordering will be derived instead from the tree's topology (distributions which travelled a longer distance will be weaker than those which travelled a shorter distance), and numeric priorities should not be used.

Example of priority resolution for listeners

Here is part of a grade definition from the framework's Uploader component implementation, showing a recommended use of a constraint-based priority:

fluid.defaults("fluid.uploader.errorPanel.section", {
    gradeNames: ["fluid.viewComponent"],
    // ...
    listeners: {
        "onCreate.bindHandlers": {
            funcName: "fluid.uploader.errorPanel.section.bindHandlers",
            priority: "before:refreshView"
        },
        "onCreate.refreshView": "{that}.refreshView"
    }
});

Amongst the two onCreate listeners, the framework guarantees that the bindHandlers listener will always be invoked before refreshView.

Table of supported sites for priorities and namespaces

The following table lists all the locations in component options where priorities are supported, together with some notes about their limitations and interpretation.