classes.js

/**
 * Class stubs for documentation purposes
 * @main F2
 */
F2.extend('', {
	/**
	 * The App Class is an optional class that can be namespaced onto the 
	 * {{#crossLink "F2\Apps"}}{{/crossLink}} namespace.  The 
	 * [F2 Docs](../../app-development.html#app-class)
	 * has more information on the usage of the App Class.
	 * @class F2.App
	 * @constructor
	 * @param {F2.AppConfig} appConfig The F2.AppConfig object for the app
	 * @param {F2.AppManifest.AppContent} appContent The F2.AppManifest.AppContent
	 * object
	 * @param {Element} root The root DOM Element for the app
	 */
	App: function(appConfig, appContent, root) {
		return {
			/**
			 * An optional init function that will automatically be called when
			 * F2.{{#crossLink "F2\registerApps"}}{{/crossLink}} is called.
			 * @method init
			 * @optional
			 */
			init:function() {},
      /**
       * An optional destroy function that will automatically be called when
       * F2.{{#crossLink "F2\removeApp"}}{{/crossLink}} and subsequently
       * the {{#crossLink "F2.Constants.AppHandlers\APP_DESTROY"}} AppHandler.
       */
      destroy:function() {}
		};
	},
	/**
	 * The AppConfig object represents an app's meta data
	 * @class F2.AppConfig
	 */
	AppConfig: {
		/**
		 * The unique ID of the app. More information can be found
		 * [here](../../app-development.html#f2-appid)
		 * @property appId
		 * @type string
		 * @required
		 */
		appId: '',
		/**
		 * An object that represents the context of an app
		 * @property context
		 * @type object
		 */
		context: {},
		/**
		 * True if the app should be requested in a single request with other apps.
		 * @property enableBatchRequests
		 * @type bool
		 * @default false
		 */
		enableBatchRequests: false,
		/**
		 * The height of the app. The initial height will be pulled from
		 * the {{#crossLink "F2.AppConfig"}}{{/crossLink}} object, but later
		 * modified by calling
		 * F2.UI.{{#crossLink "F2.UI/updateHeight"}}{{/crossLink}}. This is used
		 * for secure apps to be able to set the initial height of the iframe.
		 * @property height
		 * @type int
		 */
		height: 0,
		/**
		 * The unique runtime ID of the app.
		 *
		 * **This property is populated during the
		 * F2.{{#crossLink "F2/registerApps"}}{{/crossLink}} process**
		 * @property instanceId
		 * @type string
		 */
		instanceId: '',
		/**
		 * True if the app will be loaded in an iframe. This property
		 * will be true if the {{#crossLink "F2.AppConfig"}}{{/crossLink}} object
		 * sets isSecure = true. It will also be true if the
		 * [container](../../container-development.html) has made the decision to
		 * run apps in iframes.
		 * @property isSecure
		 * @type bool
		 * @default false
		 */
		isSecure: false,
		/**
		 * The language and region specification for this container 
		 * represented as an IETF-defined standard language tag,
		 * e.g. `"en-us"` or `"de-de"`. This is passed during the 
		 * F2.{{#crossLink "F2/registerApps"}}{{/crossLink}} process.
		 *
		 * @property containerLocale
		 * @type string
		 * @default null
		 * @since 1.4.0
		 */
		containerLocale: null,
		/**
		 * The languages and regions supported by this app represented
		 * as an array of IETF-defined standard language tags,
		 * e.g. `["en-us","de-de"]`. 
		 *
		 * @property localeSupport
		 * @type array
		 * @default []
		 * @since 1.4.0
		 */
		localeSupport: [],
		/**
		 * The url to retrieve the {{#crossLink "F2.AppManifest"}}{{/crossLink}}
		 * object.
		 * @property manifestUrl
		 * @type string
		 * @required
		 */
		manifestUrl: '',
		/**
		 * The recommended maximum width in pixels that this app should be run.
		 * **It is up to the [container](../../container-development.html) to
		 * implement the logic to prevent an app from being run when the maxWidth
		 * requirements are not met.**
		 * @property maxWidth
		 * @type int
		 */
		maxWidth: 0,
		/**
		 * The recommended minimum grid size that this app should be run. This
		 * value corresponds to the 12-grid system that is used by the
		 * [container](../../container-development.html). This property should be
		 * set by apps that require a certain number of columns in their layout.
		 * @property minGridSize
		 * @type int
		 * @default 4
		 */
		minGridSize: 4,
		/**
		 * The recommended minimum width in pixels that this app should be run. **It
		 * is up to the [container](../../container-development.html) to implement
		 * the logic to prevent an app from being run when the minWidth requirements
		 * are not met.
		 * @property minWidth
		 * @type int
		 * @default 300
		 */
		minWidth: 300,
		/**
		 * The name of the app
		 * @property name
		 * @type string
		 * @required
		 */
		name: '',
		/**
		 * The root DOM element that contains the app
		 *
		 * **This property is populated during the
		 * F2.{{#crossLink "F2/registerApps"}}{{/crossLink}} process**
		 * @property root
		 * @type Element
		 */
		root: undefined,
		/**
		 * The instance of F2.UI providing easy access to F2.UI methods
		 *
		 * **This property is populated during the
		 * F2.{{#crossLink "F2/registerApps"}}{{/crossLink}} process**
		 * @property ui
		 * @type F2.UI
		 */
		ui: undefined,
		/**
		 * The views that this app supports. Available views
		 * are defined in {{#crossLink "F2.Constants.Views"}}{{/crossLink}}. The
		 * presence of a view can be checked via
		 * F2.{{#crossLink "F2/inArray"}}{{/crossLink}}:
		 * 
		 *     F2.inArray(F2.Constants.Views.SETTINGS, app.views)
		 *
		 * @property views
		 * @type Array
		 */
		views: []
	},
	/**
	 * The assets needed to render an app on the page
	 * @class F2.AppManifest
	 */
	AppManifest: {
		/**
		 * The array of {{#crossLink "F2.AppManifest.AppContent"}}{{/crossLink}}
		 * objects
		 * @property apps
		 * @type Array
		 * @required
		 */
		apps: [],
		/**
		 * Any inline javascript tha should initially be run
		 * @property inlineScripts
		 * @type Array
		 * @optional
		 */
		inlineScripts: [],
		/**
		 * Urls to javascript files required by the app
		 * @property scripts
		 * @type Array
		 * @optional
		 */
		scripts: [],
		/**
		 * Urls to CSS files required by the app
		 * @property styles
		 * @type Array
		 * @optional
		 */
		styles: []
	},
	/**
	 * The AppContent object
	 * @class F2.AppManifest.AppContent
	 **/
	AppContent: {
		/**
		 * Arbitrary data to be passed along with the app
		 * @property data
		 * @type object
		 * @optional
		 */
		data: {},
		/**
		 * The string of HTML representing the app
		 * @property html
		 * @type string
		 * @required
		 */
		html: '',
		/**
		 * A status message
		 * @property status
		 * @type string
		 * @optional
		 */
		status: ''
	},
	/**
	 * An object containing configuration information for the
	 * [container](../../container-development.html)
	 * @class F2.ContainerConfig
	 */
	ContainerConfig: {		
		/**
		 * Allows the [container](../../container-development.html) to override how
		 * an app's html is inserted into the page. The function should accept an
		 * {{#crossLink "F2.AppConfig"}}{{/crossLink}} object and also a string of
		 * html
		 * @method afterAppRender
		 * @deprecated This has been replaced with {{#crossLink "F2.AppHandlers"}}{{/crossLink}} and will be removed in v2.0
		 * @param {F2.AppConfig} appConfig The F2.AppConfig object
		 * @param {string} html The string of html representing the app 
		 * @return {Element} The DOM Element surrounding the app
		 */
		afterAppRender: function(appConfig, html) {},
		/**
		 * Allows the [container](../../container-development.html) to wrap an app
		 * in extra html. The function should accept an
		 * {{#crossLink "F2.AppConfig"}}{{/crossLink}} object and also a string of
		 * html. The extra html can provide links to edit app settings and remove an
		 * app from the container. See
		 * {{#crossLink "F2.Constants.Css"}}{{/crossLink}} for CSS classes that
		 * should be applied to elements.
		 * @method appRender
		 * @deprecated This has been replaced with {{#crossLink "F2.AppHandlers"}}{{/crossLink}} and will be removed in v2.0
		 * @param {F2.AppConfig} appConfig The F2.AppConfig object
		 * @param {string} html The string of html representing the app
		 */
		appRender: function(appConfig, html) {},
		/**
		 * Allows the container to render html for an app before the AppManifest for
		 * an app has loaded. This can be useful if the design calls for loading
		 * icons to appear for each app before each app is loaded and rendered to
		 * the page.
		 * @method beforeAppRender
		 * @deprecated This has been replaced with {{#crossLink "F2.AppHandlers"}}{{/crossLink}} and will be removed in v2.0
		 * @param {F2.AppConfig} appConfig The F2.AppConfig object
		 * @return {Element} The DOM Element surrounding the app
		 */
		beforeAppRender: function(appConfig) {},
		/**
		 * True to enable debug mode in F2.js. Adds additional logging, resource cache busting, etc.
		 * @property debugMode
		 * @type bool
		 * @default false
		 */
		debugMode: false,
		/**
		 * The default language and region specification for this container 
		 * represented as an IETF-defined standard language tag,
		 * e.g. `"en-us"` or `"de-de"`. This value is passed to each app
		 * registered as `containerLocale`.
		 *
		 * @property locale
		 * @type string
		 * @default null
		 * @since 1.4.0
		 */
		locale: null,
		/**
		 * Milliseconds before F2 fires callback on script resource load errors. Due to issue with the way Internet Explorer attaches load events to script elements, the error event doesn't fire.
		 * @property scriptErrorTimeout
		 * @type milliseconds
		 * @default 7000 (7 seconds)
		 */
		scriptErrorTimeout: 7000,
		/**
		 * Tells the container that it is currently running within
		 * a secure app page
		 * @property isSecureAppPage
		 * @type bool
		 */
		isSecureAppPage: false,
		/**
		 * Allows the container to specify which page is used when
		 * loading a secure app. The page must reside on a different domain than the
		 * container
		 * @property secureAppPagePath
		 * @type string
		 * @for F2.ContainerConfig
		 */
		secureAppPagePath: '',
		/**
		 * Specifies what views a container will provide buttons
		 * or links to. Generally, the views will be switched via buttons or links
		 * in the app's header.
		 * @property supportedViews
		 * @type Array
		 * @required
		 */
		supportedViews: [],
		/**
		 * An object containing configuration defaults for F2.UI
		 * @class F2.ContainerConfig.UI
		 */
		UI: {
			/**
			 * An object containing configuration defaults for the 
			 * F2.UI.{{#crossLink "F2.UI/showMask"}}{{/crossLink}} and
			 * F2.UI.{{#crossLink "F2.UI/hideMask"}}{{/crossLink}} methods.
			 * @class F2.ContainerConfig.UI.Mask
			 */
			Mask: {
				/**
				 * The backround color of the overlay
				 * @property backgroundColor
				 * @type string
				 * @default #FFF
				 */
				backgroundColor: '#FFF',
				/**
				 * The path to the loading icon
				 * @property loadingIcon
				 * @type string
				 */
				loadingIcon: '',
				/**
				 * The opacity of the background overlay
				 * @property opacity
				 * @type int
				 * @default 0.6
				 */
				opacity: 0.6,
				/**
				 * Do not use inline styles for mask functinality. Instead classes will
				 * be applied to the elements and it is up to the container provider to
				 * implement the class definitions.
				 * @property useClasses
				 * @type bool
				 * @default false
				 */
				useClasses: false,
				/**
				 * The z-index to use for the overlay
				 * @property zIndex
				 * @type int
				 * @default 2
				 */
				zIndex: 2
			}
		},
		/**
		 * Allows the container to fully override how the AppManifest request is
		 * made inside of F2.
		 * 
		 * @method xhr
		 * @param {string} url The manifest url
		 * @param {Array} appConfigs An array of {{#crossLink "F2.AppConfig"}}{{/crossLink}}
		 * objects
		 * @param {function} success The function to be called if the request
		 * succeeds
		 * @param {function} error The function to be called if the request fails
		 * @param {function} complete The function to be called when the request
		 * finishes (after success and error callbacks have been executed)
		 * @return {XMLHttpRequest} The XMLHttpRequest object (or an object that has
		 * an `abort` function (such as the jqXHR object in jQuery) to abort the
		 * request)
		 *
		 * @example
		 *     F2.init({
		 *         xhr: function(url, appConfigs, success, error, complete) {
		 *             $.ajax({
		 *                 url: url,
		 *                 type: 'POST',
		 *                 data: {
		 *                     params: F2.stringify(appConfigs, F2.appConfigReplacer)
		 *                 },
		 *                 jsonp: false, // do not put 'callback=' in the query string
		 *                 jsonpCallback: F2.Constants.JSONP_CALLBACK + appConfigs[0].appId, // Unique function name
		 *                 dataType: 'json',
		 *                 success: function(appManifest) {
		 *                     // custom success logic
		 *                     success(appManifest); // fire success callback
		 *                 },
		 *                 error: function() {
		 *                     // custom error logic
		 *                     error(); // fire error callback
		 *                 },
		 *                 complete: function() {
		 *                     // custom complete logic
		 *                     complete(); // fire complete callback
		 *                 }
		 *             });
		 *         }
		 *     });
		 *
		 * @for F2.ContainerConfig
		 */
		//xhr: function(url, appConfigs, success, error, complete) {},
		/**
		 * Allows the container to override individual parts of the AppManifest
		 * request.  See properties and methods with the `xhr.` prefix.
		 * @property xhr
		 * @type Object
		 *
		 * @example
		 *     F2.init({
		 *         xhr: {
		 *             url: function(url, appConfigs) {
		 *                 return 'http://example.com/proxy.php?url=' + encocdeURIComponent(url);
		 *             }
		 *         }
		 *     });
		 */
		xhr: {
			/**
			 * Allows the container to override the request data type (JSON or JSONP)
			 * that is used for the request
			 * @method xhr.dataType
			 * @param {string} url The manifest url
			 * @param {Array} appConfigs An array of {{#crossLink "F2.AppConfig"}}{{/crossLink}}
			 * objects
			 * @return {string} The request data type that should be used
			 *
			 * @example
			 *     F2.init({
			 *         xhr: {
			 *             dataType: function(url) {
			 *                 return F2.isLocalRequest(url) ? 'json' : 'jsonp';
			 *             },
			 *             type: function(url) {
			 *                 return F2.isLocalRequest(url) ? 'POST' : 'GET';
			 *             }
			 *         }
			 *     });
			 */
			dataType: function(url, appConfigs) {},
			/**
			 * Allows the container to override the request method that is used (just
			 * like the `type` parameter to `jQuery.ajax()`.
			 * @method xhr.type
			 * @param {string} url The manifest url
			 * @param {Array} appConfigs An array of {{#crossLink "F2.AppConfig"}}{{/crossLink}}
			 * objects
			 * @return {string} The request method that should be used
			 *
			 * @example
			 *     F2.init({
			 *         xhr: {
			 *             dataType: function(url) {
			 *                 return F2.isLocalRequest(url) ? 'json' : 'jsonp';
			 *             },
			 *             type: function(url) {
			 *                 return F2.isLocalRequest(url) ? 'POST' : 'GET';
			 *             }
			 *         }
			 *     });
			 */
			type: function(url, appConfigs) {},
			/**
			 * Allows the container to override the url that is used to request an
			 * app's F2.{{#crossLink "F2.AppManifest"}}{{/crossLink}}
			 * @method xhr.url
			 * @param {string} url The manifest url
			 * @param {Array} appConfigs An array of {{#crossLink "F2.AppConfig"}}{{/crossLink}}
			 * objects
			 * @return {string} The url that should be used for the request
			 *
			 * @example
			 *     F2.init({
			 *         xhr: {
			 *             url: function(url, appConfigs) {
			 *                 return 'http://example.com/proxy.php?url=' + encocdeURIComponent(url);
			 *             }
			 *         }
			 *     });
			 */
			url: function(url, appConfigs) {}
		},
		/**
		 * Allows the container to override the script loader which requests
		 * dependencies defined in the {{#crossLink "F2.AppManifest"}}{{/crossLink}}.
		 * @property loadScripts
		 * @type function
		 *
		 * @example
		 *     F2.init({
		 *			loadScripts: function(scripts,inlines,callback){
		 *				//load scripts using $.load() for each script or require(scripts)
		 *				callback();
		 *			}
		 *     });
		 */
		loadScripts: function(scripts,inlines,callback){},
		/**
		 * Allows the container to override the stylesheet loader which requests
		 * dependencies defined in the {{#crossLink "F2.AppManifest"}}{{/crossLink}}.
		 * @property loadStyles
		 * @type function
		 *
		 * @example
		 *     F2.init({
		 *			loadStyles: function(styles,callback){
		 *				//load styles using $.load() for each stylesheet or another method
		 *				callback();
		 *			}
		 *     });
		 */
		loadStyles: function(styles,callback){}
	}
});