Page Comparison

{include:sneak peek warning}
{div:class=floatRight}
{panel:title= On This Page| borderStyle=solid| borderColor=#ccc| bgColor=#fff}
{toc:minLevel=2|maxLevel=5}
{panel}
{div}

h2. Overview

The core of the Infusion IoC is the ability for a function call to resolve differently in a particular context. One way of thinking of this resolution is in terms of [Aspect-Oriented Programming|http://en.wikipedia.org/wiki/Aspect-oriented_programming] \- the matching of the context specification could be seen as a kind of _joinpoint_, and the transformation of the original caller's function call, to resolve as the execution of a different function call, as a form of _advice_. One can set up configuration for this resolution by making calls to the function [{{fluid.demands()}}|fluid.demands], which accepts three parameters:

{code:javascript}
fluid.demands(demandingName, context, spec);
{code}

|| Name || Type || Description ||
| demandingName | String | The name of the function requested by the original caller of the function, which is to be advised |
| context | String or Array of String | The name of the context(s) which need to match in order for this demands specification to be active |
| demandSpec | Object \[Demands specification\] | A record describing the modification to be performed when a dispatch to the original function is requested ("advice") |

# The name of the function which the original caller uses (the "demanding/demanded name")
# The name of the context(s) for which the demand specification is valid, and
# The demand specification ("demands block") itself.

The following sections describe the demands specification format, and several examples are provided below.

h2. The Demands Specification Object

The demands specification object can occur in a few forms. The fullest form is described here, and then an abbreviated format is defined in terms of this full form.

| {{funcName}} | the string name of the creator function for the demanding subcomponent. \\
NOTE: If this property is not present, the original function name (agreeing with the first argument to [{{fluid.demands()}}|fluid.demands]) is to be used instead |
| {{args}} | array of parameters to the function, or a single argument. |
|| OR ||
| {{options}} | an object specifying how the {{options}} argument to a component's creator function (identified as a [pseudoargument] is to be assembled |
| {{mergeOptions}} | an array of objects composing the {{options}} argument to a component's creator function is to be assembled by merging several different IoC-resolved records together |
| {{container}} | an IoC-resolved reference (most likely of the form {{\{parentComponent\}.dom.selectorName}} expressing where the {{container}} argument to a [Infusion13:View] is to be taken from |
| any pseudoargument name | The name of any [pseudoargument] defined by the grade of the component which is to be created, representing the slot of a positional argument in the transformed argument list |

Note that if the {{args}} record is used, NONE of the other mentioned elements can be present (none of {{options}}, {{mergeOptions}}, {{container}}, etc.). Also, ONLY ONE element may be used out of {{options}}, {{mergeOptions}}.

The demands specification may also simply consist of an array. In this case, the array is interpreted as being the array {{args}} above, and the {{funcName}} entry is interpreted as being empty.

h2. Context references

The demands specification allows contextualised access to state which is held in locations around the component tree which are in scope from the site where the demands block is matched. That is, at the time the demands block is matched against the caller's use of the function, the _caller's_ environment will be searched in order to _resolve_ the references in the demands block. These references take the form of contextualised EL strings, where the context name is held in braces at the start of the string. The rest of the string consists of path segments which are a query into the object which matches the context name. For example: 
{code:javascript}
    "{componentName}.model"
    "{componentName}.options.strings"
{code}

These contextualised values are resolved whenever a demands block is matched. The complete set of times when [demands resolution|docs:Demand Resolution] occurs consists of i) a call to {{[fluid.initDependents()|fluid.initDependents]}} or {{fluid.initDependent}}, used to construct a subcomponent, ii) a function call dispatched at an [invoker|docs:Invokers], and iii) resolution of a [boiled event|docs:Event injection and boiling]. Demands resolution is also known as _function resolution_, which always involves this process of resolving contextualised EL references, which is itself known as _value resolution_. Value resolution also occurs by itself, without function resolution, during [expansion and merging of options|Infusion13:Options Merging for Infusion Components] in an IoC tree. 

h2. Examples

{code:javascript}
fluid.demands("cspace.autocomplete.popup", "cspace.autocomplete",  {
    args: {
        resources: {
            template: {
                url: "../../html/AutocompleteAddPopup.html"
            }
        }
    }
});
{code}

In this example, the {{demandSpec}} does not include a {{funcName}}, so when the demand is resolved, the creator function will be assumed to be {{cspace.autocomplete.popup}}, the first argument to {{fluid.demands()}}, which is the same function the user originally requested.

{code:javascript}
fluid.demands("fluid.pager", "cspace.search.searchView",
                  ["{searchView}.dom.resultsContainer"]);
{code}

In this example, the demands specification (the third argument to {{fluid.demands()}}) does not include a {{funcName}}, so when the demand is resolved, the creator function will be assumed to be unchanged as {{fluid.pager}}, the function the user originally requested. The pager is dispatched a single argument, its container node, resolved through the DOM binder of the {{searchView}} component.

{code:javascript}
fluid.demands("cspace.autocomplete.closeButton", "cspace.autocomplete",
    ["{autocomplete}.autocompleteInput", "{options}"]
);
{code}

This example shows the use of the special contextual value {{\{options\}}} \- this is a special value which does not match a component, but instead represents the block of options that were originally targetted at the subcomponent whose instantiation is matched by the demands specification, in the {{fluid.defaults()}} block entry for that subcomponent. This demands block is completely equivalent to the following simpler demands block which shows the use of the pseudoargument name {{container}}:

{code:javascript}
fluid.demands("cspace.autocomplete.closeButton", "cspace.autocomplete", {
    container: "{autocomplete}.autocompleteInput"
});
{code}
Note that in this case, both the {{funcName}} and {{options}} entries, through not appearing, cause the matching of the demands block to default to leaving the original behaviour that would be expected from the creator function call unchanged in these respects. The only change caused by resolution of this demands block is to cause the first argument of the creator function to be filled with the value drawn from the {{autocomplete}} component.

h2. A note on "tricks"

It is important not to play "tricks" with demands blocks. That is, they should not be combined with any code whatsoever - that is, they should not be invoked from inside functions (except the global closure used to guard the scope of a file), they should not contain function calls or variable references from the Javascript language, but should be written exactly as they appear here - with three, literal concrete arguments taken from the JSON dialect of JavaScript. This is essential in order to enable interpretation of the structure of demands blocks throughout an file or entire application by development support tools (which are currently yet to be written). Demands blocks should never be "conditionally included" - except through either including or not including the files in which they appear into an application or web page. They should be properly scoped to appear in the same files as the components and functions they refer to - that is, they should not violate dependency rules by appearing in unrelated files.
{html}
<center style="font-size:1.4em"><b>TNT</b> - Try No Tricks!</center>
{html}