Child pages
  • Expansion of Component Options

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3
{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. Expanders Infusion component option defaults now go through a process called "expansion" during the component creation process. An expander is essentially a function that is called at component-creation time to create the value of the default. This can be useful when static definition of a default option is not possible. Expanders are specified using the keyword "expander:" in the component defaults: {code:javascript}
Wiki Markup
Div
classfloatRight
Panel
borderColor#ccc
bgColor#fff
borderStylesolid
titleOn This Page
Table of Contents
maxLevel5
minLevel2

Expanders

Infusion component options, as written in fluid.defaults blocks, go through a process called expansion when they are used to instantiate a component. Two kinds of expansion happen during this process -

  • Expansion of IoC references, written as strings in the form "{context}.path" as a result of the Value Resolution process, and
  • Expansion of expanders, which are blocks of JSON occurring in the options with the key expander

The standard use of an expander is to designate a function to be called when instantiating the component options, which produces a value based on processing the expander arguments. This can be useful when static definition of a default option is not possible.

Expanders are specified using the keyword "expander" in the component defaults:

Code Block
javascript
javascript
fluid.defaults("component.name", {
    optionName: {
        expander: {
            ...
        }
    }
});
{code}
The format of an expander object varies slightly depending on the particular expander type, but in general, the object will have some of the following properties:

||Name||Description||
|{{type}}|this is the string name of the expander. Currently, several expanders are provided by the framework, and are described below.|
|{{func}}| Some expanders call user-provided function. In these cases, this property is the string name of the user-provided function.|
|{{args}}| This is an array of arguments to be passed to the user-provided function|
|{{href}}| |
|{{options}}| |
|{{resourceSpecCollector}}| |
|{{fetchKey}}| |

h2. Supported Expanders
Two expanders are currently provided by the framework, and component creators can specify these expanders in their default options:

h3. fluid.deferredCall

The {{fluid.deferredCall}} expander will call the specified function, passing it the arguments provided. The return value will be assigned to the default option. For example:

{section}
{column}
{code:javascript}

The basic form of an expander record is very similar to that of an Invoker - it contains entries func/funcName together with args to designate the function call which will produce the required options values.

Name

Description

func/funcName

Either an IoC reference to a function (an invoker or other function member) or else a global function name holding the function to be invoked

args

An array of arguments (or single argument) to be passed to the user-provided function specified in func/funcName.

Examples

This example locates the global function named "cspace.search.modelFilter" and calls it with the arguments given by resolving the context "{searchView}" - in this case, most likely the top-level component defined in defaults itself. The return value from this function is then placed in the options of the instantiated component (the "fluid.pager") at the path modelFilter:

Section
Column
width50%
Code Block
javascript
javascript
fluid.defaults("cspace.search.searchView", {
    components: {
        resultsPager: {
            type: "fluid.pager",
            options: {
                modelFilter: {
                    expander: {
                        
type: "fluid.deferredCall",
func: "cspace.search.makeModelFilter",
                        args: ["{searchView}"]
                    }
                }
            }
        }
   }
});
{code} {column} {column} In this example, the {{resultsPager}} is specified as an instance of the Infusion Pager component. When this subcomponent is created, the {{deferredCall}} expander will call the function {{
Column

Tthe resultsPager is specified as an instance of the Infusion Pager component. When this subcomponent is created, the expander will call the function cspace.search.makeModelFilter

}}

,

passing

it

the

parent

{{

searchView

}}

component

as

an

argument.

The

return

value

will

be

used

as

the

default

{{

modelFilter

}}

option

to

the

Pager.

{column} {section} h3. fluid.deferredInvokeCall The {{fluid.deferredInvokeCall}} expander is essentially the same as {{fluid.deferredCall}}, but it will actually perform resolution of the client's demanded name. That is, it will look up the function name in the registered demands to determine what function will actually be called. For example: {section} {column} {code:javascript}

The fluid.noexpand expander

The fluid.noexpand expander is a very specialised expander that normal users of the framework should not require to use. It has been retained in the framework for completeness, but its effects should normally be obtained using a mergePolicy of "noexpand". This expander simply dumps its literal argument (held at a path named value or tree) into the component's options without expansion.

 

NameDescription
type"fluid.noexpand" (the type field must hold this literal value)

value/tree

This property holds some literal component configuration (either a primitive value or larger tree of JSON values) which will be inserted without expansion into the component options

Example:

 

Section
Column
width50%
Code Block
javascript
javascript
fluid.defaults("cspace.
specBuilderImpl
specBuilder", {
    
urlRenderer
components: {
        
expander
specBuilderImpl: {
            type: "
fluid
cspace.
deferredInvokeCall
specBuilderImpl",
            
func
options: 
"cspace.urlExpander"
{
        
}
     
}
   
}); cspace.urlExpander = function (options) {
unexpanded: {
        
...
     
return
 
function
 
(url)
 
{
    expander: {
   
...
     
};
 
};
 
fluid.demands("cspace.urlExpander",
 
"cspace.test",
      
{
     
args
  type: 
{
"fluid.noexpand",
        
vars:
 
{
             
webapp
  value: "
../../main/webapp
{specBuilder}.urlExpander"
        
}
     
}
 
});
 
{code}
 
{column} {column
    }
In
 
this
 
example,
 
the
 
function
 
name
 
{{cspace.urlExpander}}
 
will
 
be
 
resolved
 
before
 
being
 
invoked.
 
In
 
a
 
production
 
setting,
}
no
 
arguments
 
will
 
be
 
passed
 
(since
 
none
 
are
 
specified
 
in
 
the
 
{{expander
 }
}

object.
 
But
 
in
 
a
 
test
 
environment
 
(i.e
 
when
 
{{"cspace.test"
}
}

has
 
been
 
registered
 
as
 
an
}
environment), the demands specification be resolved and the specified arguments will be passed to the function. {column} {section}
});
Column

In this example, the function name {specBuilder}.urlExpander will NOT be resolved as an IoC reference. The value {specBuilder}.urlExpander will be assigned to the option named unexpanded.