Class: CommonUtils

var isList = mmir.CommonUtils.isArray(list);

Requires

• module:Constants
• module:mmir.SemanticInterpreter
• module:util/isArray
• module:util/deferred
• module:util/loadFile

Classes

setToCompatibilityModeExtension

Members

regexHTMLCommentString RegExp

Regular Expression for matching HTML comments.
This RegExp also matches multi-line comments. Note upon using the RegExp that it does not consider if a HTML comment is specified within a String or data-definition (i.e. the comment is matched regardless were its defined).

Example

Methods

checkNetworkConnection(){Boolean}

tools/commonUtils.js, line 875

This function is used check whether a network connection is enabled.
This version of checking the network connection is based on the cordova 2.3.0 API. TODO implement with HTML5 functions (in addition to / instead of cordova)?

Returns:

if a network connection is enabled

concatArray(){string}

tools/commonUtils.js, line 196

extracts all the strings from a String-Array into a single string

getCompiledGrammarPath(generatedGrammarsPath, grammarId, isFileNameOnly){String}

tools/commonUtils.js, line 241

Get the file path/name for a compiled grammar (executable JavaScript grammars).

Name	Type	Description
generatedGrammarsPath	String	Path of the grammars which should be loaded, e.g. gen/grammar/
grammarId	String	the ID (e.g. language code) for the grammar
isFileNameOnly	Boolean	optional OPTIONAL if TRUE then only the file name will be returned, otherwise the full path is returned

Returns:

path / name for the compiled grammar (returns an empty string, if there is no compile grammar for the specified grammar ID)

getDirectoryContents(pathname, filter){Array}

tools/commonUtils.js, line 603

This function returns an array of strings (file names) with the contents of the directory pathname. The pathname must be one of the directories (or sub-directories) of the framework's parsed folders, see directoriesToParse. If a filter is use, only files which's names match the filter are included in the returned list.

Name	Type	Description
pathname	String	Path of the directory which's contents should be returned
filter	String | RegExp | function	optional Filter for file-names: if String the file-name may contain the wildcard * (comparison is not case-sensitive), e.g.: *.js, * or *.ehtml if RegExp the file-name must match the regular expression, e.g.: /.*\.js/ig or /^.*\.ehtml$/ig if Function the file-name is included, if the function returns true, where the function signature is function(fileName: String) : Boolean, note that argument fileName will have been transformed to lower-case characters

Deprecated

• use listDir instead

Returns:

of Strings which contains the contents of the directory. Or null, if pathname is not one of the framework's parsed folders.

getDirectoryContentsWithFilter(pathname, filter){Array}

tools/commonUtils.js, line 618

This function returns an array of strings (file names) with the contents of the directory pathname. The pathname must be one of the directories (or sub-directories) of the framework's parsed folders, see directoriesToParse. If a filter is use, only files which's names match the filter are included in the returned list.

Name	Type	Description
pathname	String	Path of the directory which's contents should be returned
filter	String | RegExp | function	optional Filter for file-names: if String the file-name may contain the wildcard * (comparison is not case-sensitive), e.g.: *.js, * or *.ehtml if RegExp the file-name must match the regular expression, e.g.: /.*\.js/ig or /^.*\.ehtml$/ig if Function the file-name is included, if the function returns true, where the function signature is function(fileName: String) : Boolean, note that argument fileName will have been transformed to lower-case characters

Deprecated

• use listDir with RegExp for filter instead (see example for converting pseudo-wildcard string to RegExp)

Returns:

of Strings which contains the contents of the directory. Or null, if pathname is not one of the framework's parsed folders.

Example

//convert pseudo-wildcard string to RegExp
var filterStr = '^' + filter.replace('.', '\\.').replace('*', '.*').replace('\$', '\\$') + '$'; // e.g.,// '^.*\.js$'
var regexpr = new RegExp(filterStr, 'gi');
mmir.CommonUtils.listDir(pathname, regexpr); 

getDirectoryStructure(){Object}

tools/commonUtils.js, line 185

Returns:

structure as json object

asyncgetLocalScript(scriptUrl, success, fail)

tools/commonUtils.js, line 574

Note: On Android 4.0 jQuery.getScript() is not working properly - so use this function instead!

Similar to the jQuery.getScript() function - appending a url of a javascript-source to the header of the main document.
This function also calls a success-callback if the script was successfully loaded or a fail-callback.

Name	Type	Description
scriptUrl	String	source of javascript-file
success	function	success callback function
fail	function	fail callback function

getPartialsPrefix(){String}

tools/commonUtils.js, line 175

Returns:

Prefix for the file names of partial-files

isArray(object){Boolean}

tools/commonUtils.js, line 812

Checks if an object is an Array.

This function can be safely run in arbitrary contexts, e.g.

 var checkArray = mmir.CommonUtils.isArray;
 if( checkArray(someObject) ){
  ...

Name	Type	Description
object	Object	the Object for checking if it is an Array

Returns:

if object is an Array, otherwise false.

isRunningOnAndroid(){Boolean}

tools/commonUtils.js, line 510

Detects via the user-agent-string if the application is running on Android.

Returns:

if application is running on Android, False otherwise

isRunningOnSmartphone(){Boolean}

tools/commonUtils.js, line 534

Should detect - via the user-agent-string - if the application is running on Android, Symbian or iOS; in other words: on a smartphone.

Returns:

if application is running on smartphone, False otherwise

listDir(pathname, filter){Array}

tools/commonUtils.js, line 661

This function returns an array of strings (file names) with the contents of the directory pathname. The pathname must be one of the directories (or sub-directories) of the framework's parsed folders, see directoriesToParse. If a filter is use, only files which's names match the filter are included in the returned list.

Name	Type	Description
pathname	String	Path of the directory which's contents should be returned
filter	String | RegExp | function	optional Filter for file-names: if String the file-name may contain the wildcard * (comparison is not case-sensitive), e.g.: *.js, * or *.ehtml if RegExp the file-name must match the regular expression, e.g.: /.*\.js/ig or /^.*\.ehtml$/ig if Function the file-name is included, if the function returns true, where the function signature is function(fileName: String) : Boolean, note that argument fileName will have been transformed to lower-case characters

Returns:

of Strings which contains the contents of the directory. Or null, if pathname is not one of the framework's parsed folders.

asyncloadCompiledGrammars(generatedGrammarsPath, cbFunction, ignoreGrammarIds){Promise}

tools/commonUtils.js, line 278

Load all compiled grammars (executable JavaScript grammars).

Name	Type	Description
generatedGrammarsPath	String	Path of the grammars which should be loaded, e.g. gen/grammar/
cbFunction	function	The function that should be executed after the plugins are loaded. If the execution of following functions is dependent on the presence of the grammars, they should be triggered from inside the callback-function.
ignoreGrammarIds	Array.<String>	optional OPTIONAL grammar IDs that should be ignored, i.e. not loaded, even if there is a file available

Returns:

deferred promise (see loadImpl())

asyncloadDirectoryStructure(success, errorFunc)

tools/commonUtils.js, line 925

Parses the directory structure and stores the result in the class-property mmir.CommonUtils-directoryStructure

Name	Type	Description
success	function	optional The function that should be executed after the diretories are parsed - it's best to include all following functions inside the callback-function.
errorFunc	function	optional callback function that is invoked if an error occured during initialization.

asyncloadImpl(librariesPath, isSerial, completedCallback, checkIsAlreadyLoadedFunc, statusCallback){Promise}

tools/commonUtils.js, line 379

Load implementation files (i.e. JavaScript files) from a directory (if librariesPath is a String) or or a list of files-names (if librariesPath is an Array of Strings).

Name	Type	Description
librariesPath	String | Array.<String>	Path (or list of of the plugins which should be loaded, e.g. mmirf/plugins/ NOTE: The (String) path must be an entry in directories.json! (directories.json is used to generate/"query" the file-list for the path)
isSerial	Boolean	Set true if the libraries should be loaded serially, i.e. synchronously, that is "one after the other" (later ones may depend on earlier ones). set false if libraries should be loaded in parallel, i.e. "asychronously" (NOTE in this case, the libraries must not depend on each other). NOTE: The loading process as a hole is asynchronous (regardless of parameter isSerial), i.e. loading is completed when completedCallback() is invoked, NOT when this function returns!
completedCallback	function	optional The function that should be executed after the libraries are loaded. If the execution of following functions is dependent on the presence of the libraries, they should be capsuled inside this callback-function.
checkIsAlreadyLoadedFunc	function	optional If provided, this function checks (based on the file-name), if the library is already loaded. The signature for the callback is checkIsAlreadyLoadedFunc(String fileName) return [true|false], i.e. the function may check - based on the file-name - if the library is already loaded. If the function returns true, the library will not be loaded, and loading continues with the next library-file. NOTE: if isSerial is false, libraries with lower indices in the list may still be loading, when later entries are checked with this callback. In consequence, the "is already loaded"-check may not be accurate, in case parallel loading is used and the library-list contains "duplicate" entries.
statusCallback	function	optional If provided, this function is invoked, when a library was loaded loaded (INFO) or an error occurs. The signature for the callback is statusCallback(String statusLevel, String fileName, String message) where statusLevel is one of info, warning, error, fileName is the file-name for the library that this status message concerns, and message is a message text with details concerning the status

Returns:

deferred promise that will be fulfilled when loadImpl() has finished.

loadScript()

tools/commonUtils.js, line 222

Same as getLocalScript

See:

• getLocalScript

parseParamsToDictionary(urlParamsPartStrings){Object}

tools/commonUtils.js, line 857

IMPORTED FROM paramsParseFunc.js

Convert parameter-part of an URL to a "dictionary", containing the parameter keys and values

?id=5&name=heinz&name=kunz →

	{
	  id: "5",
	  name: ["heinz", "kunz"],
   
	  //utility functions
	  has: function(key) : Boolean,
	  isMultiple: function(key) : Boolean,// is entry an Array of values
	  getKeys: function() : String[],     // get list of all keys
	}
	

The returnd "dictionary" has the following functions:

• has(String key): returns true if the dictionary contains an entry for key
• isMultiple(String key): returns true if the entry for key is an Array (i.e. the URL contained multiple values for this key)
• getKeys(): returns an Array with the keys (String) for all entries

Name	Type	Description
urlParamsPartStrings	String	the parameter-part of the URL, i.e. &...

Returns:

"dictionary" for the parameters

parseParamsToDictionary(urlParamsPartStrings){Object}

tools/paramsParseFunc.js, line 43

Convert parameter-part of an URL to a "dictionary", containing the parameter keys and values

?id=5&name=heinz&name=kunz →

	{
	  id: "5",
	  name: ["heinz", "kunz"],
   
	  //utility functions
	  has: function(key) : Boolean,
	  isMultiple: function(key) : Boolean,// is entry an Array of values
	  getKeys: function() : String[],     // get list of all keys
	}
	

The returned "dictionary" has the following functions:

• has(String key): returns true if the dictionary contains an entry for key
• isMultiple(String key): returns true if the entry for key is an Array (i.e. the URL contained multiple values for this key)
• getKeys(): returns an Array with the keys (String) for all entries

Name	Type	Description
urlParamsPartStrings	String	the parameter-part of the URL, i.e. &...

Returns:

"dictionary" for the parameters