My IC Customizer: Descriptors of Skins and Webapps for third party User Guide

Transcription

1 User Guide 8AL USAA ed01 09/2013

2 Table of Content 1. About this Document Who Should Read This document What This Document Tells You Terminology and Definitions Description of a webapp or a skin by extra data Skin: How to get the data for skin parameters PARAMETERS OF THE SKIN USAGE OF THE PARAMETERS OF THE SKIN DECLARATION RULES MY IC CUSTOMIZER HELP Homepage: How to get the parameters for buttons of webapp PARAMETERS OF THE BUTTONS USAGE OF THE PARAMETERS OF THE BUTTONS DECLARATION RULES Homepage: How to get the parameters for preview of a webapp PARAMETERS OF THE PREVIEW USAGE OF THE PARAMETERS OF THE PREVIEW DECLARATION RULES Homepage: How to get the parameters for custom buttons from a webapp PARAMETERS OF ACTIONS FOR THE CUSTOM BUTTONS USAGE OF THE PARAMETERS FOR THE CUSTOM BUTTONS DECLARATION RULES SDK and My IC Customizer Help FOR SKIN FOR WEBAPP Legal notice: Alcatel, Lucent, Alcatel-Lucent and the Alcatel-Lucent logo are trademarks of Alcatel-Lucent. All other trademarks are the property of their respective owners. The information presented is subject to change without notice. Alcatel-Lucent assumes no responsibility for inaccuracies contained herein. Copyright 2013 Alcatel-Lucent. All rights reserved. 8AL USAA ed01 2 /16

3 1. About this Document 1.1 Who Should Read This document This document is intended for developers who develop webapps or skins. The objective is to add a file giving information relative to the buttons, actions and previews which are exported to the homepage webapp. This information in a third party webapp or skins will be extracted by My IC Customizer tool and facilitate the customization of the 8082 My IC Phone. 1.2 What This Document Tells You This document describes in details all the metadata or comments to be added in the sources of a third party webapp or skin, in order to declare to My IC Customizer tool, the data exported to the homepage webapp. Without these declarations, it is not possible to parse simply the code to retrieve them. These metadata or comments are mandatory for My IC Customizer. For a Skin, the tool needs to know the name, the author and the identifier. For a webapp, all data exported to the homepage webapp, useful for the customization of the views of the homepage in both modes standard and preview. They concern the button identifier, the class of the associated icon, its coded English label, also if a preview frame is managed and the method to use to display it on the homepage view in Preview mode, and the exported actions which can be associated to any programmed custom keys. 1.3 Terminology and Definitions HTTP HTTPS I18n IC Touch L10n URI URL Webapp XML DM Hypertext Transport Protocol Secure Hypertext Transfer Protocol Internationalization Acronym for Instant Communication Touch Localization Universal Resource Indicator Uniform Resource Locator Web application extensible Markup Language Device Manager 8AL USAA ed01 3 /16

4 2. Description of a webapp or a skin by extra data My IC Customizer tool needs extra data extracted from packages. This chapter is going to detail what are they used for, how they look like and how to declare them. Notes: In this document we are talking only about webapps or skins made by a third party. The generic Alcatel-Lucent webapps or skins are not concerned by the rules of declaration of the extra data. 2.1 Skin: How to get the data for skin parameters PARAMETERS OF THE SKIN - Skin identifier: This identifier is the name of the repositories where are stored the changes in the CSS files and images regarding to the skin Challenger. This identifier is not seen usually by the user of the phone. - Skin label (name): This name is a label visible by the user. It is a more user friendly way to identify the skin with the user point of view. It is a string. I.e. The skin called Challenger, gets the name Challenger and the identifier Default. All the skins done by third party are relative regarding to the reference skin Challenger - Skin author and date creation: These are the name of the author of the skin and the last date of the upgrading. Both are strings without any format USAGE OF THE PARAMETERS OF THE SKIN It is possible to see these parameters with My IC Customizer when a package containing skins are imported. They are visible in the following window launched by the menu Resources->Skins. My IC Customizer Packages->Skins 8AL USAA ed01 4 /16

5 These parameters are used when you want to set a new skin on your phone. To do that, select the setting SkinsList and call the browser to add a new skin to the list: My IC Customizer: edit setting SkinsList When the browser is open, select the wanted skin. My IC Customizer: browser of extracted Skins You obtain: My IC Customizer: Selected skin is added as allowed value 8AL USAA ed01 5 /16

6 Then, identifier and name of the skin are displayed and can be used to configure the settings My IC Customizer: Selected skin populates the setting Skinslist DECLARATION RULES These parameters are extracted from the file providedfiles.json located in repository <Installation path>/library/ictouchapi/config/themes/<skin identifier>/providedfiles.json Directory of file providedfiles.json In this file the extra data are written in comments located at the top of the file: //Name=<label of the skin> //Author=<Name of the author if the skin> //CreationDate=<date of the last update of the Skin> { name : "<skin identifier>", 8AL USAA ed01 6 /16

7 For example: //Name=myhotel //Author=John Doe //CreationDate=2011/10/13 { name : "myhotel", type : "Partial", associatedfullskin : "Default", "ICTouchAPI" : ["main.css","icons.css"], "UIElements" : { "AppBar" : ["base.css","8082.css"], "AppButton" : ["base.css","8082.css"], } } "minifiedcss" : ["myhotel_mini8082.css"] MY IC CUSTOMIZER HELP When the tool generates the sources for a skin it fills in these extra data when the providedfiles.json is composed. 2.2 Homepage: How to get the parameters for buttons of webapp This concerns the declaration of buttons of a webapp which is registered in the homepage. All other buttons belonging to the webapp, which are not included in the homepage, do not need to be declared. These buttons have been foreseen to be configured in the settings HomepageKeys or HomepageButtons PARAMETERS OF THE BUTTONS - Button identifier: This identifier is a string which has to be unique for the whole system. The naming rule declares that it should end with _BTN and be composed with uppercase characters. - Button label: This label will be displayed below the button. It is a string. - Class of icon: In order to manage different size and states of the button with the same picture, the 8082 My IC Phone software manages a CSS class representing a set of.png files referring to the picture seen differently according to the situation. The button is associated to a class of icon. Notes: My IC Customizer uses only the pictures referring to button sized 64x64 pixels and in state normal. The same parameters will represent the button in the homepage in standard mode and in preview mode. These parameters are mainly used to help the user to visualize what he is being configuring. The most important parameter is the Button identifier. Only this parameter will be written in the settings HomepageKeys or HomepageButtons. The other parameters are needed just to have a simulated overview for help. 8AL USAA ed01 7 /16

8 2.2.2 USAGE OF THE PARAMETERS OF THE BUTTONS When the parameters of the button are extracted from the package, the button is managed like any button of the generic webapps. My IC Customizer: Button of webapp belongs to generic buttons list Then it can be selected to customize the homepage, and displayed for visualization and configuration. My IC Customizer: Button of webapp in Homepage 8AL USAA ed01 8 /16

9 My IC Customizer: Button of webapp configured in setting DECLARATION RULES To declare these parameters, a new file is needed which will contain all the information My IC Customizer needs. This file is parsed and data extracted when the package of the webapp is imported by the tool. The file is named customizerdata.xml and contains the following information: <?xml version="1.0" encoding="utf-8"?> <customizerdata> <metadata> <version> </version> <creation-date> </creation-date> <application-data> <keys> <key id= "> <values> <value> </value> </values> </key> </keys> </application-data> </metadata> </customizerdata> Content of customizerdata.xml Where: - Node <version> is a string - Node <creation-date> is formatted like Thu Aug 25 16:30:52 CEST Node <key> is a key for My IC Customizer to recognize the different parameters - Node <value> depends on the key id In our case key id = HomepageProgKeys 8AL USAA ed01 9 /16

10 Format of value is: Example: For key id= HomepageProgKeys, the format of the tag <value> is: <value>{ id :, label :, icon : }</value> <key id="homepageprogkeys"> <values> <value>{ 'id': 'MYWEBAPP_BTN', 'label': 'MyWebapp', 'icon': 'mywebapp-application' }</value> </values> </key> 2.3 Homepage: How to get the parameters for preview of a webapp This concerns the declaration of the data related to the preview of a webapp displayed on the homepage in preview mode PARAMETERS OF THE PREVIEW - Method: This method is used by the homepage to display the content of the preview. This method is usually called webapp.<name of the webapp>.get<name of the webapp>preview. Example: the method webapp.contacts.getcontactpreview is called to display the Preview Favorites In the homepage. - Title: This string represents the title displayed on top of the preview. Example: Favorites. - Setting: The value of this setting enables or not the display the preview. It is usually named Enable<Nameof the webapp>preview. Example: EnableContacsPreview USAGE OF THE PARAMETERS OF THE PREVIEW When the parameters of the preview of a webapp are declared and extracted from the package, the preview is managed like any preview of the generic webapps. Then it can be selected to customize the homepage and displayed for visualization and configuration. 8AL USAA ed01 10 /16

11 My IC Customizer: add imported preview DECLARATION RULES To declare these parameters, a new key is defined in the file customizerdata.xml. See previous chapter. In this case key id = HomepagePreviews Format of value is: For key id= HomepagePreviews, the format of the tag <value> is: <value>preview displayer;title;setting enabling </value> Example: <key id="homepagepreviews"> <values> <value> webapp.mywebapp.getmywebapppreview;my webapp;enablemywebapppreview </value> </values> </key> 8AL USAA ed01 11 /16

12 2.4 Homepage: How to get the parameters for custom buttons from a webapp This concern the declaration of parameters related to actions exported by the webapp to the webapp progkeys, which is in charge to manage the custom buttons. This webapp provides methods onprogkeyconfig, onprogkeyconfigreturn, onprogkeyactions, onprogkeydisplay, onprogkeyclick. These actions can be then associated to custom buttons (also called Programmable Keys) and then placed in the homepage PARAMETERS OF ACTIONS FOR THE CUSTOM BUTTONS - Button Identifier: This identifier is computed by the tool My IC Customizer and cannot be modified. It starts with the value BTN_ID and continues with BTN_ID #2, then BTN_ID #3. - Button label: This label will be displayed below the button. It is a string. This label and only that one associated to a Custom button can be localized by My IC Customizer tool. - Action: This is a string defined and dedicated to the webapp. It is hardcoded and the associated code is processed reacting to a click on the custom button. - webappname: It is the name of the webapp where the action is coded. - Default Class of icon: In order to manage different sizes and states of the button with the same picture, the 8082 My IC Phone software manages a CSS class representing a set of.png files referring to the picture seen differently according to the situation. When a custom button is created by My IC Customizer, it is possible to associate a class of icon to it. This parameter is the class of icon to be associated to the button by default, when the action is selected. - Arguments: (optional) this is a string containing a list of label of parameters, separated by the character ;. The field is not to be declared. My IC Customizer tool offers a field arguments to be written if necessary. If there are several arguments, it is recommended to separate them with the character ;. It is a string formatted like this: value 1;value 2;value 3;value 4;value 5;. Notes: The tool My IC Customizer uses only the pictures referring to button sized 64x64 pixels and in state normal. The same parameters will represent the button in the homepage in standard mode and in preview mode. These parameters are mainly used to help the user to visualize what he is being configuring. In the case of custom buttons, the button identifier is created automatically by the tool. These button identifiers and the other associated parameters are stored in the setting HomepageProgKeys. The button identifier of such a custom button is managed like any other button (generic or defined in a webapp third party and available on homepage). It can be used in homepage in both modes. It is written in the settings HomepageKeys or HomepageButtons. The other parameters are used to have a simulated overview for help and are also stored in the settings HomepageProgKeys. The label associated to a custom Button can be localized by filling in the setting HomepageProgKeysLocalisation with My IC Customizer tool. It defines the identifier of the strings which are the translations of the label. The translation can have a value totally distinct from the label. My IC Customizer displays the label, not the English or the French translation of the label. To have a better understanding, it is recommended to define the label as its English translation. 8AL USAA ed01 12 /16

13 2.4.2 USAGE OF THE PARAMETERS FOR THE CUSTOM BUTTONS The webapp has to declare only the parameters action, default class of icon and arguments. The button identifier and the label belong to the process of customization of a custom button, by following the steps: - Step 1: Create a button (button identifier) - Step 2: Define its label - Step 3: Associate to it an action (may be that one extracted from the webapp and its parameters) - Step 4: Change the icon if default does not suit My IC Customizer: creation of a custom button. Step 1 to 4 - Step 5: Then place the created button on the homepage. My IC Customizer: creation of a custom button. Step 5 8AL USAA ed01 13 /16

14 - Step 6: And finally, localize the label. My IC Customizer: creation of a custom button. Step 6 This supposes that the package of the webapp has been declared in the properties of the project in order to request the tool to extract the declarations of the available custom actions DECLARATION RULES To declare these parameters, a new key is defined in the file customizerdata.xml. See chapter above. In this case key id = HomepageProgKeysActions Format of value is: For key id= HomepageProgKeysActions, the format of the tag <value> is : <value>{ action :, webappname :, icon : }</value> Example: <key id= "HomepageProgKeysActions "> <values> <value>{ 'action': 'my-action', 'webappname': 'mywebapp' 'mywebapp-myaction' }</value> </values> </key>, 'icon': 8AL USAA ed01 14 /16

15 2.5 SDK and My IC Customizer Help FOR SKIN My IC Customizer helps you generating source codes and filling appropriately the comments in the file providedfiles.json FOR WEBAPP SDK helps you preparing template of webapp that you have to fill in according to your coding. The webapp creator tool creates the file customizerdata.xml in the repository config/ of your webapp project. The content of this template is: <?xml version="1.0" encoding="utf-8"?> <customizerdata> <metadata> <version></version> <creation-date></creation-date> <application-data> <! Declare Buttons visible in Homepage. <key id= HomepageProgKeys"> <values> <! Format: <value>{ id :, label :, icon : }</value> Example: <value>{ 'id': 'MYWEBAPP_BTN', 'label': 'MyWebapp', 'icon': 'mywebapp-application' }</value> --> </values> </key> 8AL USAA ed01 15 /16

16 <! Declare Preview visible in Homepage. <key id= HomepagePreviews"> <values> <! Format: <value>preview displayer;title;setting enabling </value> Example: <value> webapp.mywebapp.getmywebapppreview;my webapp;enablemywebapppreview </value> --> </values> </key> </keys> <! Declare Actions which can be programmed in a programmed key. <key id= HomepageProgKeys"> <values> <! Format: <value>{ action :, webappname :, icon : }</value> Example: <value>{ 'action': 'my-action', 'webappname': 'mywebapp', 'icon': 'mywebapp-myaction' }</value> --> </values> </key> </keys> </application-data> </metadata> </customizerdata> Template of customizerdata.xml It is the responsibility of the developer to fill in the different fields according to the activity of the webapp. Only the button which is given as parameter with the wizard is declared in the file. The others are not and should be added manually. 8AL USAA ed01 16 /16