nokia.Features

Class Summary

This class provides facilities that allow you to register and load individual functional components (features) of the API.

[ For full details, see nokia.Features ]

Table 1. Method Summary
Methods

static  add (featureName, featureImplName, loadPath, detector, dependencies, overrides, charset)

This method adds a new feature implementation definition to the feature registry.

static  get (featureName, featureImplName)

This method retrieves a feature implementation definition object for the feature specified by the caller.

static  getFeatureMap ()

This method retrieves a map object containing the names of available implementations for each registered feature.

static  getLoadedMap ()

This method retrieves a map of the names of fully loaded implementations for each registered feature.

static  isLoaded (featureName, featureImplName) : {Boolean}

This method checks whether a certain feature implementation has been successfully loaded.

static  load (requested, onSuccess, onError, doc, sync)

This method loads a set of features specified by the caller.

Class Description

This class provides facilities that allow you to register and load individual functional components (features) of the API. It automatically resolves dependencies between features and provides mechanisms to detect the best feature implementation for the current environment. A feature may exist in different implementations for different target environments. A feature implementation is a set of classes that provide certain functionality and can be loaded to enrich the functionality set accessible through the API. The features that can be loaded individually with the help of the methods on this class include such components as "routing" and "search".

By default, the API loads package named "all" (see section "Packages and Detection" in User Guide) which contains features in optimal implementation for the environment in which it runs. However, the loading of packages may be deferred at page-load time. This may reduce the initial page load time by limiting the amount of API code that is transferred and executed before the page contents are fully displayed. To do that loader file jsl.js must be called with blank=true GET parameter (ex. <script src="http://api.maps.nokia.com/2.2.3/jsl.js?blank=true" type="text/javascript"></script>).

Features is a static object that cannot be instantiated, therefore to call one of its methods, you must precede the method name with the namespace and the name of the class, using the dot notation. For example, in case of deferred loading you can call the load() method as follows: 
var featureMap = nokia.Features.getFeaturesFromMatrix(["maps"]); //that will return all features that are included in "maps" package
nokia.Features.load(featureMap, successCallback, errorCallback, document, false); //loads asynchronously all necessary files and
		//invokes successCallback where map instantiation etc. can take place

Method Details

static  add(featureName, featureImplName, loadPath, detector, dependencies, overrides, charset)

This method adds a new feature implementation definition to the feature registry. If the feature does not yet exist in the registry, an entry for it is created, including the feature name and the implementation and the implementation object.

Parameters:
 
featureName

type: {string}

A canonical name of the feature which the implementation provides

featureImplName

type: {string}

A canonical the name of the implementation

loadPath

type: {string}

The load path of the implementation file

detector

type: {function ()}

[optional] 

The detector function that determines whether this feature can be loaded in the current environment; if a detector is not provided, a default function that always returns true is used

dependencies

type: {Array}

[optional, default: null] 

An optional array of the names of the features on which the named implementation depends

overrides

type: {Array}

[optional, default: null] 

An optional array of implementation names (within the same feature) this implementation overrides.

charset

type: {string}

[optional, default: 'utf-8'] 

An optional identifier of the character set for the script

static  get(featureName, featureImplName)

This method retrieves a feature implementation definition object for the feature specified by the caller.

Parameters:
 
featureName

type: {string}

The name of the feature to be retrieved

featureImplName

type: {string}

[optional, default: 'auto'] 

Either the name of the specific implementation or 'auto', which allows the method automatically to detect the optimal implementation for the current environment

Returns:
A feature implementation object, or null if the feature is not supported by the current environment

static  getFeatureMap()

This method retrieves a map object containing the names of available implementations for each registered feature. The map has the following structure: 
		{
		featureA: [featureImplNameA1, featureImplNameA2, ...],
		featureB: [featureImplNameB1, ...]
		...
}
Returns:
A map object listing registered feature implmentations

static  getLoadedMap()

This method retrieves a map of the names of fully loaded implementations for each registered feature. The returned map has the following structure: 
		{
		featureA: [featureImplNameA1, featureImplNameA2, ...],
		featureB: [featureImplNameB1, ...]
		...
		}
Returns:
A map object listing loaded implementations of registered features

static  isLoaded(featureName, featureImplName) : {Boolean}

This method checks whether a certain feature implementation has been successfully loaded. The method returns true if the queried implementation has been successfully loaded (i.e. transmitted AND evaluated). The method throws an exception when either the feature or the implementation is unknown.

Parameters:
 
featureName

type: {Object}

The name of the feature to check

featureImplName

type: {Object}

- the name of the implementation of the feature to check

Returns:
{Boolean} true if the feature has been fully loaded, false otherwise

static  load(requested, onSuccess, onError, doc, sync)

This method loads a set of features specified by the caller. The caller can provide optional callbacks to be invoked on success and on error and also a target document to which the respective script tags should be appended. The caller specifies the features to load in a hash object, where the keys represent the feature names and the values provide the implementation parameters, for example: 
nokia.Features.load({
	"map": "auto",
	"search": "auto"
});
Parameters:
 
requested

type: {Object}

A hash containing the names of the features to load (as keys) and feature implementation parameters (as values)

onSuccess

type: {function ()}

A function to be called on success

onError

type: {function (e)}

A function to be called on error

doc

type: {Document}

The host document

sync

type: {Boolean}

A Booleand indicating whether synchronous loading via document.write is to be enforced (true) or not (false)

Parent topic: nokia