FAXL3: JavaScript

From fringDocumentation

Jump to: navigation, search

Contents

JavaScript

FAXL 3.0

fring API allows developers to add JavaScript actions running locally inside mobile fring client. The JS code must be wrapped inside the action RunScript. In order to run JS code upon arrival to the client, developer can use this actions inside the onLoad event.

Besides the core JS elements (functions, variables, operators, Math object etc…) fring JS supports the following methods:

  • fringalert(string message) 
fringalert("Hello World");
  • fring.GetParameter(string varName) - Returns a FAXL variable.
  • fring.SetParameter(string varName, string value) - Sets a FAXL parameter with value 
fring.SetParameter("myVar1", "Hello World!");
tmp = fring.GetParameter("myVar1");
fringalert("Content of my FAXL variable : " + tmp);
  • fring.SendToServer(string str1, string str2, ..., string strN) - Sends data to add-on server. See ActionSendToServer 
fring.SetParameter("myVar1", "Hello World!");
fring.SendToServer("sending str1", fring.GetParameter("myVar1"));
  • fring.GetListSelectedID(string guiName, string faxlOutVarName) - Returns the ID of the selected item in list. See ActionGetListSelectedID
  • fring.GetSelectedContact(string faxlOutVarName) - Returns the contact information of a selected contact in contact list. See ActionGetSelectedContact
  • fring.CreateControl(string controlVarName) - Creates a control, similar to ActionCreateControl
  • fring.DeleteControl(string guiName) - Deletes an existing control, similar to ActionDeleteControl
  • fring.PlayMedia(string mediaUrl, bool useSystemPlayer) - See ActionPlayMedia
  • fring.ChangeBrowserData(string guiName, bool isURL, string data) - Change an existing browser control. See ActionChangeBrowserData
  • fring.startGPS(int Interval) - Start collecting GPS information. See ActionStartGPS
  • fring.stopGPS() - Stops collecting GPS information. See ActionStopGPS
  • fring.GetChatTabFreeSpace() - returns the amount of free space (in percents) of the given chat window. Similar to ActionGetChatTabFreeSpace.
    There are two forms of this function:
    • fring.GetChatTabFreeSpace(userinfo, faxlVarNameToStore)
    • fring.GetChatTabFreeSpace(userid, service id, faxlVarNameToStore)
  • fring.RegisterChatTabFreeSpace(string argChatTabID, int argPercentLowerLimit, string argUserHashReturnVarName, string argActions) - Defines an action that will be executed once the free space on a chat tab gets lower then the given percentage. Similar to ActionRegisterChatTabFreeSpace
    • argChatTabID - Faxl variable holding the chat tab ID
    • argPercentLowerLimit - Lower limit of free space (percentage) that once exceed will trigger some action
    • argUserHashReturnVarName - The FAXL variable name containing the userInfo data of the Chat partner
    • argActions - Faxl variable that holds the action that will be performed once argPercentLowerLimit is reached
  • fring.UpdateControlData(string FaxlControlName, string NewFaxlControlName, string NewGuiName, bool Visibility, int Container, string ContainerInfo) - Allows to copy an existing control, change the copy's visibility and place the copy in a new container.
    • Container can be: 2 - chat container, 3 - add-on container.
  • fring.IsTabOpen(string TabType, int TabID) - returns true if addon tab is opened else - false.
    • TabType - type of tab (only "addon" supported)
    • TabID - ID of add-on which tab should be checked 
fring.IsTabOpen("addon", 123);

FAXL 3.1 extensions

Send chat API

  • fring.SendChat(string faxlUserInfoVarName, string Message ) - To send a chat message to the specified contact. Requires admin privileges 
fring.GetSelectedContact("myContact"); 
fring.SendChat("myContact", "Hello!");
  • fring.SendChat(int serviceID, string userID, string Message ) - To send a chat message to the specified contact. Requires admin privileges 
fring.SendChat(3, "fring-test-call", "Hello!");

Activate addon tab API

  • fring.ActivateAddonTab(int AddonId) - To activate (bring to foreground) specified add-on tab. Requires admin privileges

Subscribe to addon API

  • fring.SubscribeToAddon(int AddonID) - This action allows opening a subscription view of add-on that is available in client and is visible. In case of add-on with requested ID was not found or was found and is invisible no action will be done. If user has canceled the subscription or approved it and subscription succeeded he will return to the previous view, else if he approved the subscription but it failed we will stay on the subscription screen. See also ActionSubscribeToAddon
    • AddonID – ID of the add-on, whose subscription screen to activate 
fring.SubscribeToAddon(67);

MP3 progressive playback API

This API downloads and playbacks (during a download) mp3 files. The API uses the same connection that fring is using, if that connection will be lost playback will terminate.

  • fring.StartAudioProgressivePlay(string URL, string TransactionIdName, string ActionsName, string EventName, bool Prefetch, int CacheLevel) - To start progressive play of an audio. See also ActionStartAudioProgressivePlay
    • URL - URL to the audio that should be streamed
    • TransactionIdName - name of the FAXL variable where to store the id of the transaction
    • ActionsName - name of the FAXL variable that stores actions executed on an audio event
    • EventName - name of the FAXL variable that will store an audio event. See ActionStartAudioProgressivePlay for details about supported events.
    • Prefetch - notifies if client should first pre-fetch the audio or start streaming at once after buffered enough
    • CacheLevel - Desired level of pre-caching of the audio in Kb 
fring.StartAudioProgressivePlay("http://sample/song.mp3", "ID", "actions", "event", true, 128);

Sample for handling an audio event: 

switch( fring.GetParameter( "event" ) )
{
case 0: fringalert( "Connection lost" );
        break;
case 1: fringalert( "Incorrect URL" );
        fring.SendToServer( "bad url" );
        break;
case 2: fringalert( "Buffering" );
        break;
case 3: fringalert( "Playback active" );
        break;
case 4: fringalert( "Playback finished" );
        fring.SendToServer( "track ended" );
        break;
case 5: fringalert( "Playback suspended by higher priority event" );
        break;
case 6: fringalert( "Prefetch done, buffer level is enought to start playing. Let's start playback!" );
        fring.ContinueAudioProgressivePlay( fring.GetParameter( "ID" ) );
        break;
case 7: fringalert( "Track downloaded 100%" );
        break;
};

View "audio event" final XML

  • fring.StopAudioProgressivePlay(int ID) - To stop the audio streaming. See also ActionStopAudioProgressivePlay
    • ID – id audio streaming transaction that will be stopped 
fring.StopAudioProgressivePlay(fring.GetParameter("ID"));
  • fring.ContinueAudioProgressivePlay(int ID) - To continue the audio streaming after pre-fetch was done. See also ActionContinueAudioProgressivePlay
    • ID – id audio streaming transaction that will be resumed 
fring.ContinueAudioProgressivePlay(fring.GetParameter("ID"));

View events API

  • fring.RegisterOnViewEvents(string Container, string ViewInfo, string Event, string Actions) - registers for a view event (opened/closed/gained or lost focus). See also ActionRegisterOnViewEvents
    • Container - FAXL variable name that will store type of container
    • ViewInfo - FAXL variable name that will store view information (e.g. for Add-on tab - id of the add-on)
    • Event - FAXL variable name that will store event type (e.g. closed)
    • Actions - FAXL variable name that stores actions 
fring.RegisterOnViewEvents("container", "info", "event" ,"actions");

Samples for handling a view event: 

switch( fring.GetParameter( "event" ) )
{
case 0: fringalert( "New view created" );
        fring.SendToServer( "view created", fring.GetParameter("container"), fring.GetParameter("info") );
        break;
case 1: fringalert( "View closed" );
        fring.SendToServer( "view closed", fring.GetParameter("container"), fring.GetParameter("info") );
        break;
case 2: fringalert( "View gained focus" );
        fring.SendToServer( "view gained focus", fring.GetParameter("container"), fring.GetParameter("info") );
        break;
case 3: fringalert( "View lost focus" );
        fring.SendToServer( "view lost focus", fring.GetParameter("container"), fring.GetParameter("info") );
        break;
default: break;
};

fringalert( "container: " + fring.GetParameter("container") + '\n' +
            "info: " + fring.GetParameter("info") + '\n' +
            "event: " + fring.GetParameter("event") );

View "view event" final XML

Touch bar API

Touch bar API allows creation of touch bar buttons. Specific view of the touch bar buttons depends on client type. For example in case of Nokia 9.4 buttons appear in Nokia touch bar. Touch bar support implemented on top of commands mechanism. Commands have additional properties that define touch button position and icon.


  • fring.AddAddonCommand(int CommandID, string CommandName, string ActionsName, int SequenceID, int ToolbarPosition, string Icon) - This action adds Command to addon that initiated action.
    • CommandID - numeric id of command
    • CommandName - string displayed as command label
    • ActionsName - name of the FAXL variable storing command actions
    • SequenceID - optional parameter defining the sequence ID of the command to add
    • ToolbarPosition - optional parameter defining position of the command button (0 - Right, 1 - Center, 2 - Left)
    • Icon - optional parameter defining FAXL variable with icon for the command touch button 
fring.AddAddonCommand( 1, "Addon CMD", "actions", 2, 1, "icon" );
  • fring.RemoveAddonCommand(int CommandID) - This action removes all addon commands with specified ID.
    • CommandID - numeric id of command to remove 
fring.RemoveAddonCommand( 1 );
  • fring.AddControlCommand(string ControlName, int CommandID, string CommandName, string ActionsName, int SequenceID, int ToolbarPosition, string Icon) - This action adds Command to control specified by GUI name.
    • ControlName - the GUI name of the control to add the command
    • CommandID - numeric id of command
    • CommandName - string displayed as command label
    • ActionsName - name of the FAXL variable storing command actions
    • SequenceID - optional parameter defining the sequence ID of the command to add
    • ToolbarPosition - optional parameter defining position of the command button (0 - Right, 1 - Center, 2 - Left)
    • Icon - optional parameter defining FAXL variable with icon for the command touch button 
fring.AddControlCommand( "control", 1, "Control CMD", "actions", 1, 0, "icon" );
  • fring.RemoveControlCommand(string ControlName, int CommandID) - This action removes all control commands with specified ID.
    • ControlName - the GUI name of the control to remove the command
    • CommandID - numeric id of command to remove 
fring.RemoveControlCommand( "control", 1 );
  • fring.AddListItemCommand(string ControlName, string ItemID, int CommandID, string CommandName, string ActionsName, int SequenceID, int ToolbarPosition, string Icon) - This action adds Command to list item specified by list item ID and residing in list specified by GUI name.
    • ControlName - the GUI name of the list to add the command
    • ItemID - the ID of the list item
    • CommandID - numeric id of command
    • CommandName - string displayed as command label
    • ActionsName - name of the FAXL variable storing command actions
    • SequenceID - optional parameter defining the sequence ID of the command to add
    • ToolbarPosition - optional parameter defining position of the command button (0 - Right, 1 - Center, 2 - Left)
    • Icon - optional parameter defining FAXL variable with icon for the command touch button 
fring.AddListItemCommand( "list", "item", 1, "Item CMD", "actions", 1, 0, "icon" )
  • fring.RemoveListItemCommand(string ControlName, string ItemID, int CommandID) - This action provides possibility to remove all list item commands with specified ID.
    • ControlName - the GUI name of the list
    • ItemID - the ID of the list item
    • CommandID - numeric id of command to remove 
fring.RemoveListItemCommand( "list", "item", 1 );
  • fring.GetAddonViewWithToolbarHeigth() - returns the height of addon view with toolbar 
fringalert( fring.GetAddonViewWithToolbarHeigth() );
  • fring.GetAddonViewWithToolbarWidth() - returns the width of addon view with toolbar 
fringalert( fring.GetAddonViewWithToolbarWidth() );

FAXL 3.2 extensions

List control API

List control API allows adding, removing and updating items in list controls.

  • fring.AddListItem(string ControlName, string ItemID, int GroupID, string ItemName, string Icon, string Description) - provides possibility to add an item to the list control. If item was added focus will stay on previously selected item.
    • ControlName - the id of list control that should be updated. If list control created by add-on with such id was not found – no action will be done.
    • ItemID - the unique ID of the item that will be added to the list.
    • GroupID - ID of the group that item belongs to.
    • ItemName - the name of the item that will be displayed in the list.
    • Icon - name of FAXL variable that stores icon that will be displayed in the item. If specified for text list this parameter will not take any effect.
    • Description - relevant only for double line list. The text that will be displayed in second line of the item. If specified for list controls of other type – parameter will not take any effect. 
fring.AddListItem("list", "item5", 0, "item 5", "icon", "fifth item description");
  • fring.RemoveListItem(string ControlName, string ItemID) - provides possibility to remove an item to the list control.
    • ControlName - the id of list control that should be updated. If list control created by add-on with such id was not found – no action will be done.
    • ItemID - the unique ID of the item that will be removed from the list. If item with such ID was not found or ID is empty – no action will be done. 
fring.RemoveListItem("list", "item5");
  • fring.UpdateListItemName(string ControlName, string ItemID, string ItemName) - provides possibility to update name of the item in the list control.
    • ControlName - the id of list control that should be updated. If list control created by add-on with such id was not found – no action will be done.
    • ItemID - the unique ID of the item that will be updated in the list. If item with such ID was not found or ID is empty – no action will be done.
    • ItemName - the text that will be displayed in the first line of the item in the list. 
fring.UpdateListItemName("list", "item2", "new name");
  • fring.UpdateListItemDescription(string ControlName, string ItemID, string Description) - provides possibility to update description of the item in the list control. It’s relevant only for double line list.
    • ControlName - the id of list control that should be updated. If list control created by add-on with such id was not found – no action will be done.
    • ItemID - the unique ID of the item that will be updated in the list.
    • Description - the text that will be displayed in the second line of item of double line list. 
fring.UpdateListItemDescription("list", "item4", "new description");
  • fring.UpdateListItemIcon(string ControlName, string ItemID, string Icon) - provides possibility to update icon in the item of the list control. Not relevant for plain text list.
    • ControlName - the id of list control that should be updated. If list control created by add-on with such id was not found – no action will be done.
    • ItemID - the unique ID of the item that will be updated in the list.
    • Icon - name of FAXL variable that stores icon that will be displayed in the item. If specified for text list this parameter will not take any effect. 
fring.UpdateListItemIcon("list", "item4", "icon");
  • fring.ClearListItems(string ControlName) - provides possibility to remove all items from the list.
    • ControlName - the id of list control that will be cleared from items. 
fring.ClearListItems("list");
  • fring.ChangeListItemGroupID(string ControlName, string ItemID, int GroupID) - provides possibility to change the group ID of the list item.
    • ControlName - the id of list control that should be updated. If list control created by add-on with such id was not found – no action will be done.
    • ItemID - the unique ID of the item that will be updated in the list.
    • GroupID - new group ID. 
fring.ChangeListItemGroupID("list", "item3", -1);
  • fring.ClearListItemCommands(string ControlName, string ItemID) - provides possibility to remove all commands from the list item.
    • ControlName - the id of list control that should be updated. If list control created by add-on with such id was not found – no action will be done.
    • ItemID - the unique ID of the item that will be updated in the list. 
fring.ClearListItemCommands("list", "item4");
  • fring.SetListSortType(string ControlName, int SortType) - provides possibility to define the algorithm of list sorting or disable sorting at all. By default no sorting for list items is applied.
    • ControlName – the id of list control that should be updated. If list control created by add-on with such id was not found – no action will be done.
    • SortType – constant defining sort algorithm. Available:
  1. noSort – turns off automatic sorting
  2. sortGrpAsc – by group ascending
  3. sortGrpDsc – by group descending
  4. sortNameAsc – by name ascending
  5. sortNameDsc – by name descending
  6. sortGrpNameAsc – by group and name ascending
  7. sortGrpNameDsc – by group and name descending
  8. sortGrpAscNameDsc – by group ascending & name descending
  9. sortGrpDscNameAsc – by group descending & name ascending 
fring.SetListSortStrategy("list", sortGrpNameDsc);

View events API extention

  • fring.UnregisterViewEvents() - Allows add-on developer to unregister view events notification. No parameters required. 
fring.UnregisterViewEvents();

Chat tab opened event

  • fring.RegisterOnChatTabOpen(string Container, string Actions) - Defines an action that will be executed once chat tab was opened.
    • Container - Faxl variable name that will store informaion about opened chat
    • Actions - Faxl variable that holds the action that will be performed once chat tab was opened 
fring.RegisterOnChatTabOpen("container", "actions");

Sample for handling chat opened event: 

fringalert("chat opened: " + fring.GetParameter( "container" ));

View "chat opened" final XML

Retrieved from "http://www.fringcall.com/index.php?title=FAXL3:_JavaScript"
Personal tools