Documentation for a historical release of Infusion: 1.3
Please view the Infusion Documentation site for the latest documentation.
If you're looking for Fluid Project coordination, design, communication, etc, try the Fluid Project Wiki.

fluid.defaults

Owned by Laurel Williams
Last updated: May 15, 2009Version comment
8 min read

The fluid.defaults function

The fluid.defaults function allows you specify options for a component and set their defaults. The Fluid Framework manages the options set in the fluid.defaults function, including merging them when any of the default options are overridden.

The fluid.defaults function signature

fluid.defaults is a function that takes two arguments, the component and an object of key value pairs representing the component options. Typical options include "selectors", "styles", "events", and "strings", however, you are free to create your own options. Options are specified with a meaningful name for the key, and their default value.

fluid.defaults("component.name", {
    selectors: {key: value},
    styles: {key: value, ...},
    strings: {key: value, ...},
    events: {key: value, ...},
    optionName: {key: value, ...},
    ...
}

Default selectors

The selectors option is used to specify the default selectors used to find elements in the DOM. The default selectors can be any "jQueriable" element (a string representing a selector, a DOM element, or a jQuery).

Default selectors for Flutter

Try writing an example using Flutter's Tweets view. Download the fluid:Sample Code. Rename the file to TweetsView.js and place into the "flutter-infused" directory. Start writing the fluid.defaults function on line 115.

fluid.defaults("fluid.flutter.tweetsView", {

//options go here

});

Now add the selectors options, specifying default values for tweets and tweetTemplate. Notice that tweets uses a DOM element and tweetTemplate uses a class as its selector.

fluid.defaults("fluid.flutter.tweetsView", {
    selectors: {
        tweets: "li",
        tweetTemplate: ".flutter-tweet-template"
    }
});

Now that the selectors are defined they can be used in the code. On line 21 the selectableSelector key can be assigned the default value specified for tweets.

selectableSelector: that.options.selectors.tweets

Often you'll want to use the default selectors for finding elements in the DOM. The Fluid Framework simplifies this task for you, by automatically searching within the scope of the container specified in the creator function. All you have to do is pass the name of the selector to that.locate and the Fluid Framework will take care of finding it for you. For example, add the following code on line 32 to remove an element.

that.tweetTemplate = that.locate("tweetTemplate").remove();

When you are done, the fluid:finished code will look like this

Default styles

The styles option is used to specify default CSS classes. It can be used to store all CSS classes that a component uses, but is most useful at storing those classes which are added/removed programmatically. The default values for styles take the name of a CSS class. The specific styling applicable to that CSS class should be defined in a separate CSS style sheet that is linked to by the HTML document.

Default styles for Flutter

Try writing an example using Flutter's Settings view. Download the fluid:Sample Code. Rename the file to SettingsView.js and place into the "flutter-infused" directory. Start writing the fluid.defaults function on line 70. As before, pass in the name of the component, but start with an options object that only has the selectors specified (as shown below).

fluid.defaults("fluid.flutter.settingsView", {
    selectors: {
        usernameField: ".flutter-username-edit",
        passwordField: ".flutter-password-edit"
    }
});

Now add the styles options and specify the the defaults for hidden.

fluid.defaults("fluid.flutter.settingsView", {
    selectors: {
        usernameField: ".flutter-username-edit",
        passwordField: ".flutter-password-edit"
    },

    styles: {
        hidden: "flutter-hidden"
    }
});

Put the styles option to use in the code at line 55. This function checks if the hidden class exists in the container and returns the result.

that.isVisible = function () {
    return !that.container.hasClass(that.options.styles.hidden);
};

When you are done, the fluid:finished code will look like this

Default strings

The strings option is used to specify the defaults for messages, warnings, and other text that is programmatically set by the component. It is useful for localization, by allowing users to replace the default text with that of another language. Adding default strings to Flutter is similar to adding other defaults.

Default events

The events object is used to specify the events used by the component. (fluid:Please see below for how to add listeners via a listeners option)

Defining events is slightly different than other defaults. Most importantly, the events object is included in the defaults for the declaration of events, not as an option. This means that they are not intended to be overriden by a value passed to the creator function, as this would could change behaviour.

The structure of events is different, the key is the name of the event, the value can be one of: null, "unicast", or "preventable". Note that null is not a string value, but the actual value null. null allows the fired event to be heard by all listeners that have registered for it. "preventable" is similar to null, but its propagation can be stopped by a registered listener. "unicast" can be used where one and only one listener should be registered for an event. For more information about what these different values represent, see the Infusion Event System.

Default events for Flutter

Try writing an example for Flutter. Download the fluid:Sample Code. Rename the file to FlutterInfused.js and place into the "flutter-infused" directory. Start adding the events options to the fluid.defaults function on line 162. The initial structure of the fluid.defaults is shown below. Don't worry about the view options here, they will be explained in the #subcomponents section below.

fluid.defaults("fluid.flutter", {
        friendsView: {
            type: "fluid.flutter.friendsView"
        },

        tweetsView: {
            type: "fluid.flutter.tweetsView"
        },

        settingsView: {
            type: "fluid.flutter.settingsView"
        },

        statusView: {
            type: "fluid.flutter.statusView"
        },

        selectors: {
            mainPanel: ".flutter-main-panel",
            settingsPanel: ".flutter-settings-panel",

            statusPanel: ".flutter-status-panel",
            friendsList: ".flutter-friends",
            tweetsList: ".flutter-tweets",

            allTabs: ".flutter-panel-tabs li",
            friendsTab: ".flutter-friends-tab",
            settingsTab: ".flutter-settings-tab",

            errorDialog: ".flutter-error-dialog"
        },

        styles: {
            hidden: "flutter-hidden",
            activeTab: "fl-activeTab"
        }
    });

Now add the events options.

fluid.defaults("fluid.flutter", {
        friendsView: {
            type: "fluid.flutter.friendsView"
        },

        tweetsView: {
            type: "fluid.flutter.tweetsView"
        },

        settingsView: {
            type: "fluid.flutter.settingsView"
        },

        statusView: {
            type: "fluid.flutter.statusView"
        },

        selectors: {
            mainPanel: ".flutter-main-panel",
            settingsPanel: ".flutter-settings-panel",

            statusPanel: ".flutter-status-panel",
            friendsList: ".flutter-friends",
            tweetsList: ".flutter-tweets",

            allTabs: ".flutter-panel-tabs li",
            friendsTab: ".flutter-friends-tab",
            settingsTab: ".flutter-settings-tab",

            errorDialog: ".flutter-error-dialog"
        },

        styles: {
            hidden: "flutter-hidden",
            activeTab: "fl-activeTab"
        },

        events: {
            // View-related events.
            afterFriendSelected: null,
            onSaveSettings: null,

            // Model change events.
            onFriendsFetchSuccess: null,
            onFriendsFetchError: null,
            onTweetsFetchSuccess: null,
            onTweetsFetchError: null,
            onStatusSaveSuccess: null,
            onStatusSaveError: null
        }
    });

Now that the events have been specified we can fire them or listen to them.

Try firing some events. On line 104, as part of the function to fetch friends, add two event firing functions. The first will fire on success, and the other will fire on error.

that.twitter.fetchFriends(that.events.onFriendsFetchSuccess.fire, that.events.onFriendsFetchError.fire);

Notice that both of these events have a null value, therefore all registered listeners will be notified when these events are fired.

Now listen to some events. On line 26 add a couple of event listeners as part of the bindEventHandlers function.

that.events.onSaveSettings.addListener(that.showMainPanel);
that.events.onFriendsFetchError.addListener(that.friendsErrorDialog.open);

The function which is passed in (i.e. that.showMainPanel) is called when the event is fired and detected by the listener.


Alternatively listeners can be specified inside a listeners options object in defaults. In this case, the key is the name of the event to which the listener is bound, and the value is the function to call after the listener detects the event.

Adding a listener to fluid.defaults would look something like this:

fluid.defaults("fluid.flutter", {

    listeners: {
        eventName: function
    }

});

When you are done, the fluid:finished code will look like this