Basic Component Creation - Little Components

Regardless of which grade of component you use, the basic structure will be the same. We'll use the simplest grade, a little component, to illustrate what this structure is. In future pages explaining other grades, you'll see the same principles.

The definition of a component involves two things:

1. declare the component grade and any default values for the component's options. Options are used by integrators to customize the behaviour of a component.
2. define a creator function: a public function that is invoked to instantiate the component

Grade and Default Options

A component's grade and any default options are registered with the framework using a call to fluid.defaults, which has two parameters: the component name and an object containing the defaults. The grade name is specified in an array in the defaults called gradeNames. For a little component, specify the grade as fluid.littleComponent:

fluid.defaults("tutorials.simpleComponent", {
    gradeNames: ["fluid.littleComponent"],
    option1: "default value 1",
    ...
});

Options

The options you define for your component will be completely dependent on what your component does. Integrators can override your defaults when they instantiate the component, to customize its appearance or behaviour. The Framework will take care of merging the integrator's values with your defaults.

We'll go through some examples of options, to give you an idea of what they're all about.

Example: Currency Converter Options

Suppose you're creating a currency converter. You might wish to specify a default conversion rate:

fluid.defaults("tutorials.currencyConverter", {
    gradeNames: ["fluid.littleComponent"],
    exchangeRate: 1.035
});

Example: Inline Edit

The Infusion Inline Edit component uses a tooltip and defines (among other things) defaults for the delay before the tooltip appears, the text to display - even whether or not to enable it at all:

fluid.defaults("fluid.inlineEdit", {
    ...
    useTooltip: true,
    tooltipText: "Select or press Enter to edit",
    tooltipDelay: 1000, // in milliseconds
    ...
});

Example: Progress

The Infusion Progress component uses jQuery animations to show and hide a progress bar. The defaults include objects that are passed to jQuery to configure the animations:

fluid.defaults("fluid.progress", {
    ...
    showAnimation: {
        params: {
            opacity: "show"
        }, 
        duration: "slow"
    }, // equivalent of $().fadeIn("slow")
        
    hideAnimation: {
        params: {
            opacity: "hide"
        }, 
        duration: "slow"
    }, // equivalent of $().fadeOut("slow")
    ...
});

The Creator Function

All components have a creator function: a public function that is invoked to instantiate the component. Infusion components have a standardized function signature:

• little, evented and model components accept a single argument: options
• view and renderer components accept two arguments: container and options

(We'll get into what these arguments are soon.)

Creator functions can be defined in one of two ways

1. directly: You write the function yourself
2. using Inversion of Control (IoC): The framework will create the function according to your specifications

NOTE: The IoC system in Infusion is being introduced in version 1.4, and has Sneak Peek status. If you're working with production code, you might wish to use the "old-fashioned" method and write your own creator function, but otherwise, we do recommend that you use IoC.

Writing your own creator function

Creator functions follow a few basic steps:

1. Create an object called that by calling the appropriate Framework component initialization function
2. Attach things to the object and otherwise initialize the component
3. Return the object

Here's what that would look like for a little component:

// The global namespace
var tutorial = tutorial || {};

(function ($, fluid) {

    // a creator function for a little component
    // creator functions are typically named by the component name itself
    tutorials.sampleComponent = function (options) {
        // call the framework component initialization function
        var that = fluid.initLittleComponent("tutorials.sampleComponent", options);

        // attach any public methods to the 'that' object
        that.publicFunction = function () {
            // ...
        };

        return that;
    };

})(jQuery, fluid_1_3);

Example: Currency Converter Creator Function

What would this look like for our currency converter example?

// creator function for the currency converter component
tutorials.currencyConverter = function (options) {
    var that = fluid.initLittleComponent("tutorials.currencyConverter", options);

    // note that component methods have access to the values stored in 'options'
    // - the ones provided in the defaults and possibly overriden by implementors
    that.convert = function (amount) {
        return amount * that.options.exchangeRate;
    }
    return that;
};

Using IoC

Automatic creator function generation

The Inversion of Control (IoC) system can automatically generate a component creator function for you. This is accomplished by added a special grade to the gradeNames property: "autoInit":

fluid.defaults("tutorials.simpleComponent", {
    gradeNames: ["fluid.littleComponent", "autoInit"],
    option1: "default value 1",
    ...
});

With this special grade, you do not need to write a creator function at all.

Public API methods

But wait: What about public methods that we want to be part of the component's API? The Infusion Framework offers a number of hooks into the component creation lifecycle, and you can use one of these hooks to add your public methods. These hooks can be accessed by providing functions that will be executed at these moments in the lifecycle. These functions are speficied in the defaults for the component.

Adding public methods is typically done during the final initialization of a component. The hook for this – the default where you need to specify your function – is called finalInitFunction:

fluid.defaults("tutorials.simpleComponent", {
    gradeNames: ["fluid.littleComponent", "autoInit"],
    option1: "default value 1",
    ...
    finalInitFunction: "tutorials.simpleComponent.finalInit"
});

// the 'final init' function, which adds public methods to the component
tutorials.simpleComponent.finalInit = function (that) {
    that.publicFunction = function () {
        ...
    };
};

The things to note about this:

• the finalInitFunction default takes the string name of the function
• the function accepts the that object as an argument - your function simply adds methods to it

Example: Currency Converter via IoC

So what would our currency converter example look like, create using IoC:

fluid.defaults("tutorials.currencyConverterAuto", {
    gradeNames: ["fluid.littleComponent", "autoInit"],
    exchangeRate: 1.035,
    finalInitFunction: "tutorials.currencyConverterAuto.finalInit"
});

// The final init function
tutorials.currencyConverterAuto.finalInit = function (that) {
    that.convert = function (amount) {
        return amount * that.options.exchangeRate;
    }
};