Embed Size (px)
Citation preview
TIBCO Spotfire® Deployment Kit for Apple iPad Version 2.0 – User’s Manual
Important Information SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE. USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN LICENSE_TIBCOSPOTFIREMOBILEFRAMEWORK.PDF) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME. This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc. TIBCO and Spotfire are either registered trademarks or trademarks of TIBCO Software Inc. and/or subsidiaries of TIBCO Software Inc. in the United States and/or other countries. All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only. This software may be available on multiple operating systems. However, not all operating system platforms for a specific software version are released at the same time. Please see the readme.txt file for the availability of this software version on a specific operating system platform. THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME. Copyright © 1996 - 2012 TIBCO Software Inc. ALL RIGHTS RESERVED. THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES. TIBCO Spotfire is covered by U.S. Patent No. 6,014,661 and U.S. Patent No. 7, 216,116. Other patent(s) pending. TIBCO Software Inc. Confidential Information Adobe Photoshop are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. Apple, iPad, Xcode, iTunes, Apple App Store, Macintosh, OS X, Snow Leopard, Lion, and Finder are trademarks of Apple Inc., registered in the U.S. and other countries. Intel is a trademark of Intel Corporation in the U.S. and/or other countries. IOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license.
iii
Table of Contents
1 OVERVIEW ...............................................................................................................4 1.1 Major Features of the Framework ..................................................................................... 4
1.2 System Requirements ........................................................................................................ 4
1.3 Deployment Requirements ................................................................................................ 4
2 CUSTOMIZATION .....................................................................................................5 2.1 Step 1: Load the Project in Xcode ..................................................................................... 5
2.2 Step 2: Customize Basic App Information ........................................................................ 6
2.3 Step 3: Customize App Strings ........................................................................................ 12
2.4 Step 4: Customize App Settings ...................................................................................... 14
2.5 Step 5: Configure App Features ...................................................................................... 19
TIBCO Spotfire® Deployment Kit for Apple iPad 2.0 – User’s Manual
4
1 Overview 1.1 Major Features of the Framework
TIBCO Spotfire Deployment Kit for Apple iPad 2.0 is a framework that permits you to create a customized version of the mobile Spotfire application for the iPad, with your unique branding. You can customize the app icon, startup screen, name, the strings presented in the app, as well as the settings exposed to the user. You can also specify how the app behaves at startup, what server connections it uses to populate screens for analysis selection, and what screens in the app should be available to the user. This customization can be done without writing any code, simply by changing string values in the provided Xcode project file. Once you have customized the app, you can build a standard iTunes ready version with your Apple Developer certificate and upload to the Apple App Store. This document details the steps involved in customizing the app using the provided Xcode compatible project. The steps are easy and quick, and all the details are included in this document. Note: It is recommended that you follow the steps in this manual, and that you do not modify any settings other than those mentioned, unless you are an experienced user.
1.2 System Requirements You need an Apple Macintosh computer with an Intel® processor that is running OS X 10.6 Snow Leopard or higher. Although no coding is required, you must have Apple’s development IDE Xcode 4.2 or higher installed on your Macintosh. You can download Xcode 4.2 for OS X 10.7 Lion from Apple’s App Store at: http://itunes.apple.com/us/app/xcode/id448457090?mt=12.
1.3 Deployment Requirements In order to deploy your customized app to the Apple App Store, or to an enterprise, you need to register in the iOS Developer Program or the iOS Developer Enterprise Program. Details about the programs can be found at: http://developer.apple.com/programs/which-program/.
Customization
5
2 Customization The following sections provide step-by-step instructions for customizing the app.
2.1 Step 1: Load the Project in Xcode Open the Xcode project file SpotfireFrameworkClient.xcodeproj with Xcode 4.2 or higher by double-clicking on the file in Finder. When you do, the project window will appear as below:
Project Folders The project file SpotfireFrameworkClient.xcodeproj contains a number of different folders. You can see these folders in the project outline pane on the left-hand side of the Xcode window. The folders group similar files together to make it easy to see what files correspond to the ways you can customize the app. The image below shows the folders in the project outline pane:
TIBCO Spotfire® Deployment Kit for Apple iPad 2.0 – User’s Manual
6
The following folders contain files and values that you may modify when customizing the app: • Artwork: Contains the app icon and app startup images, as well as the icon that
appears in iTunes for the app (iTunesArtwork). See Changing the App Icon and Startup Screens to learn more.
• Metadata: Contains app metadata like the display name of the app that appears below the icon in the iPad home screen.
• Strings: Contains all the string values that appear in the app, like the strings in dialogs and other views.
• Settings: Contains the files that specify what settings are exposed to the user in the Settings app. You can change which settings are available to the user, as well as the names of these settings.
• Configure Features: Contains files that allow you to specify which features are enabled and disabled, as well as other controls over how the app starts up, etc.
Note: The folders named Code, Frameworks, and Products should remain unmodified and should not be removed from the project. They are important for the app to function properly.
First Test Build Everything is set up and ready to build in this project, so without any additional customizations, you can build and test this app now. To do this, make sure that iPad Simulator appears next to the scheme name SpotfireFrameworkClient in the scheme selector at the top left of the Xcode screen, next to the Run and Stop buttons. Open the Product menu and select Build For > Build For Running, or use the shortcut ⇧⌘R:
You can see the completion status of the build in the status display area at the top center of the Xcode window. After the build completes, press the Run button, which looks like a tape recorder play button, at the top left corner of the Xcode window. You have now successfully built a customized version of Spotfire for iPad. Later in this document, you will learn how to completely customize the interface and behavior of this app.
2.2 Step 2: Customize Basic App Information 2.2.1 Customizing the Company Name
The first thing to customize is the company name associated with this app. To do this, click on the project entry at the top of the project outline pane. This is the first entry with a small blue project icon next to the project name SpotfireFrameworkClient:
Customization
7
This project has one target, called MySpotfire, which is listed under the TARGETS heading in the Project and Targets list pane, as seen below:
In case it is not already selected, click on the MySpotfire target and then open the Summary tab in the details pane located in the center of the Xcode window:
The first field in the Summary view is the Identifier field. Select the default MyCompany part of the text in the edit field and replace it with your company name.
TIBCO Spotfire® Deployment Kit for Apple iPad 2.0 – User’s Manual
8
The name should not contain any spaces, and the whole identifier should follow the reverse-URL convention: com.[CompanyName].[ProductName]. To change the default MySpotfire value for the [ProductName] in the reverse-URL field, see Changing the App Target Name below.
2.2.2 Changing the App Target Name The app target name is the app product name. It appears as the file name on disk of the app package. This is the target of building this project. The default value is MySpotfire. You can change this by clicking on the MySpotfire target under the TARGETS heading, and then enter a new name in the field:
2.2.3 Changing the Version and Build Information In the Summary view, you can also change the Version and Build information for the app. The initial defaults are 1.0 for Version, and 0 for Build. The Version field represents the major and minor version of this release of the app. You can enter any major and minor version number in the Version field. The Build field represents the actual build number of this release. You can reset the Build field by entering a number in it at the Summary screen. Then the next time you generate a build, it will be incremented by one. A script is attached to this project in the Build Phases tab view. It automatically increments this Build field by one every time a build is generated. Note: Do not modify this script unless you are an experienced Xcode developer and you want to change the way the Build field is updated.
2.2.4 Other Settings in the Summary View When you are working in the Summary view of Xcode, make sure you do not change any other settings than the ones mentioned above. The TIBCO Spotfire Deployment Kit for Apple iPad does not support modification of any other settings than the ones mentioned. If you make changes to any other settings, your app may cease to work.
2.2.5 Changing the App Icon and Startup Screens The app icon is the image representing the app, and on which you click to start the app. The app startup screen is displayed when the app is starting up but before the interface of the app is ready to display. There is one startup screen for each orientation of the device; portrait and landscape. The default images that we provide have a logo displayed in the center of the image. You may wish to replace this with your unique logo. To change the app icon and startup screens, you need to edit the existing image files that are stored in the Artwork project folder. Expand the Artwork folder in the left-most pane of the Xcode window, right-click on the icon.png file, and select Show in Finder from the menu, as seen in the image below:
Customization
9
A Finder window opens, displaying the app icon file, named icon.png, as well as the files used for the app startup screens; Default-Landscape~iPad.png and Default-Portrait~iPad.png. You can open these files in a graphics editing program to change them the way you like. Be sure to save your changes to the same file name, thus replacing the existing file. Also, make sure that you save the files as PNG files, and that you do not change the number of colors or size of the images when saving new versions.
2.2.6 Editing the Icon Displayed in iTunes The icon that is displayed when the app is copied into iTunes, and the large icon that is displayed next to the app in the iTunes App Store, are controlled by the file iTunesArtwork in the Artwork folder. The iTunesArtwork file is really a PNG format graphics file. However, the file extension has been removed from the file so that the icon will be properly displayed when it is included in the app package file. To modify the icon, expand the Artwork folder in the left-most pane of the Xcode window, right-click on the iTunesArtwork file, and select Show in Finder from the menu. Now duplicate the iTunesArtwork file using Finder, then right-click on the duplicated file, which will get the name iTunesArtwork copy, and select Get Info from the pop-up menu. In the info window that opens, change the Name & Extension field to iTunesArtwork.png. You can now open and edit the icon in a graphics editing program. When you are done editing the icon, make sure you save it to the same file name, and that you do not change the format, color configuration, or size of the file. Then, back in Finder, delete the old iTunesArtwork file without an extension. Note that if you have Xcode open at the time you delete this file, you may receive a warning dialog in Xcode asking you whether you want to save the file or close it. Make sure to close the file in Xcode. When you do, the file iTunesArtwork displayed in the project outline pane is displayed as empty. Next, right-click on the newly saved iTunesArtwork.png file that you edited, and select Get Info from the pop-up menu. Remove the file extension .png from the file name in the Name & Extension field so it reads iTunesArtwork. The file will now reappear in the project outline pane in Xcode.
TIBCO Spotfire® Deployment Kit for Apple iPad 2.0 – User’s Manual
10
2.2.7 Changing the App Display Name The app display name is shown below the app icon in the iPad home screen and in the Settings app category for this app’s settings. To edit the app display name, expand the Metadata folder in the left-most pane of the Xcode window:
The file named InfoPlist.strings contains strings that override those in the built-in app metadata. The built-in app metadata contains such information as the company name, the version information, the build number, as well as other information such as the app name and device capabilities. Each of these metadata values is in the form of a string that may be overridden in the InfoPlist.strings files for your particular language. InfoPlist.strings is localized to English and French by default. That is why there are two entries below the top entry in the project outline. To edit the English version file, click on the file. This will open a text editor for the file in the center of the Xcode window:
You will see the following text string in this text editor: “CFBundleDisplayName” = “My Spotfire”;
Customization
11
Currently the app name is set to “My Spotfire”, but you can change this to any string. However, it is recommended that you keep this string short, preferably twelve characters or less, to avoid the iPad truncating the display name. It is important that you maintain the syntax in this file: The double-quote marks surrounding the values, and the semicolon at the end of the line should not be removed. Comments in this file are specified by text surrounded by a slash and asterisk /* and closed by an asterisk and slash */, much like in C or C++ source code files. Make your changes, and select Save from the File menu.
2.2.8 Adding and Removing InfoPlist.strings Localizations
Adding a Language By default, the InfoPlist.strings file contains localized sub-files for English and for French, but you can easily add more languages. In the Metadata folder in the left-most pane of the Xcode window, select the top-most node called InfoPlist.strings. In the Localization pane on the right-hand side of the Xcode window, press the small plus (+) button at the bottom. In the menu that appears, select the language of interest from the list:
An additional entry for the selected language is now added below InfoPlist.strings in the project outline pane. By default, this new language version file contains copies of all the strings in the English version of the InfoPlist.strings file. You can select this file and in the Xcode editor you can change the strings to the appropriate language.
Removing a Language You can easily remove a localization language from the project. In the Metadata folder in the left-most pane of the Xcode window, select the top-most node called InfoPlist.strings. In the Localization pane on the right-hand side of the Xcode window, select the language you want to remove, then press the small minus (-) button at the bottom. After confirming the operation, the language specific InfoPlist.strings file is removed from the project outline pane.
TIBCO Spotfire® Deployment Kit for Apple iPad 2.0 – User’s Manual
12
2.3 Step 3: Customize App Strings 2.3.1 Overview
Nearly every string that is displayed in the app can be customized by editing the app strings files that are located in the Strings folder in the project outline pane.
There are literally hundreds of strings that make up the messages that are displayed in the app during normal operation.
2.3.2 String Editing Workflow The best way to find the string you want to customize is to make a note of the exact string that appears in the app at the location you want to change, then open the Strings folder and expand the tree to find the Localizable.strings file for your language. Then select that file so it is opened in a text editor in Xcode. Then search for the string in question in the editor window. When found, make your changes and save the file. Then rebuild the project and see your new string at the location you changed in the running app.
2.3.3 Strings Files Organization The strings files are organized by sections based on the name of the screens in the app. There are two major app contexts of operation:
• Explore • Analyze
When you run the app, you use the segmented button in the upper left corner of the app screen to switch the app context from Explore to Analyze and back again. The two contexts represent the two major tasks that a user of the app wants to accomplish: to explore the available analyses from various sources to select one to focus on, and to work with the selected analysis to reveal new information and share with others. In the default non-customized app, there are several action screens associated with the Explore context:
• Servers • Favorites • Most Recent • Featured • Silver
And, likewise, for the Analyze context, there are several action screens associated with it: • Add To Favorites Popup • Annotation Mode • Email Popup
Customization
13
These contexts and actions are used to divide the strings that correspond to them in the Localizable.strings files. In the files, you will find comments that use the context and the action name to mark sections of strings. This makes it easier to locate the string you want to change, based on the context and action screen it was found in.
2.3.4 String Syntax There are important syntax rules that you must follow when you edit string values in the Localizable.strings files. Each line in the files consists of a key value, an equals sign, and an assigned value. Double-quote marks must surround the key value (value on the left side of the equals sign) and the assigned value (value on the right side of the equals sign). Each key-value string line must end with a semi-colon. Comments in this file are specified by text surrounded by a slash and asterisk /* and closed by an asterisk and slash */, much like in C or C++ source code files. Note: Some assigned values in key-value string lines contain special formatting characters, such as %d, %@, etc. Do not remove these formatting characters. Doing so may cause the app to crash. These formatting characters are placeholders for values that the app automatically substitutes in the string when it is displayed in the app.
2.3.5 Adding and Removing Localizations Adding a Language By default, there are localized strings files for English and for French, but you can easily add more languages. Select the top-most node in the Strings folder called Localizable.strings. In the Localization pane on the right-hand side of the Xcode window, press the small plus (+) button at the bottom. In the menu that appears, select the language of interest.
An additional entry for the selected language is now added below Localizable.strings in the project outline pane. By default, this new language version file contains copies of all the strings in the English version of the Localizable.strings file. You can select this file, and in the Xcode editor, you can change the strings to the appropriate language.
TIBCO Spotfire® Deployment Kit for Apple iPad 2.0 – User’s Manual
14
Removing a Language To remove a localization language, select the top-most node in the Strings folder called Localizable.strings. In the Localization pane on the right-hand side of the Xcode window, select the language you want to remove, then press the small minus (-) button at the bottom.
After confirming the operation, the language specific Localizable.strings file is removed from the project outline pane.
2.4 Step 4: Customize App Settings 2.4.1 Overview
The Settings folder contains the app’s settings bundle, which is used to present various preferences and settings to the user in the iPad Settings app. You can customize which settings are exposed to the user, and which are not, by commenting out selected settings in the settings XML file. You can also override the strings used to describe the settings in the Settings app, changing them to strings that better represent the settings in your customized version of the app. Just like all the other customizable strings in the app, these are localized to your language and you can add additional languages.
2.4.2 Organization of the Settings If you expand the Settings folder in the project outline pane in Xcode, you will see the hierarchical layout of the settings files:
By default, there are two localization folders (en.lproj and fr.lproj - one English, and one French). In these folders, files are called Root.strings. These files are like the Localization.strings files you worked with previously for customizing app string values. Any entries you make to these files (which by default are empty) will override the settings titles that appear for settings in the Settings app on the iPad. In addition to these localization folders and files, there is one file called Root.plist, which is an XML file that specifies the settings that are to be exposed for the app in the iPad Settings app. You can edit this file to control which settings are displayed and which are hidden from the user.
Customization
15
2.4.3 Customizing Settings Workflow You can begin customizing the settings by deciding which settings to expose and which to hide. This is done by editing the Root.plist file in the Settings.bundle file within the Settings folder in the project outline. There are two ways to edit this file, either in the built-in editor in Xcode, or in an XML editor.
2.4.3.1 Built-in Editor To open the built-in editor in Xcode, click on the Root.plist file. This will open the built-in editor that allows you to easily specify values and change parameters for settings.
This editor is useful if you want to edit the parameters of each setting in a user-friendly way. However, if you want to hide settings, you should probably rather use an XML editor (see below), since the only way to get rid of settings in the built-in editor is to permanently delete them. Note: If you decide to edit settings using this editor, you should be careful not to change the Identifier or the Type of any setting. The app depends on this information being consistent, and if those settings are changed, it can cause the app to crash. You can safely change the Default Value and Title entries of any of the settings.
2.4.3.2 Multi Value Types For settings that are of Type Multi Value, you can safely change the number of and values of the Titles array and the Values array. Just make sure that the number of title values in the Titles array matches exactly the number of values in the Values array. An example of a Multi Value setting is the Timeout setting:
TIBCO Spotfire® Deployment Kit for Apple iPad 2.0 – User’s Manual
16
Notice that there are a total of nine (9) items for both the Titles array and the Values array. For Multi Value settings, the Titles array is used to specify the strings that appear in the popup list in the iPad Settings app. The Values array is used to specify the actual string or numeric values that are sent to the app when the user selects one of the entries in the Titles array. Each array’s order matches so that if the user selects the third item (named Item 2) from the Titles array (10 Seconds), as an example, then the third entry (named Item 2) from the Values array (10) is sent to the app as the value for this setting. Once again, it is important not to change the data types of any of the Titles or Values array items. If they are specified as String, as in this example, you must leave them all as String. If the type is changed, the app may crash.
2.4.3.3 XML Editor Editing the settings in the Root.plist file as an XML file makes it easier to hide settings, or, for that matter, to quickly edit values without having to select them from select lists, etc. Right-click on the Root.plist file in the project outline pane, and select Open As > Source Code from the pop-up menu:
Customization
17
When you do, a different editor opens in the Xcode window and allows you to directly modify the XML file:
The same care must be exercised to not change data types and to also keep the syntax of changes you make consistent with the basic XML structure of this file. For additional technical information about the structure of a settings file and the possible entry values and syntax, consult the Apple documentation at: http://developer.apple.com/library/IOS/#documentation/Cocoa/Conceptual/UserDefaults/Preferences/Preferences.html#//apple_ref/doc/uid/10000059i-CH6-SW5. You must be a registered Apple developer to access this documentation.
2.4.3.4 Removing a Setting To remove a setting, just comment out one of the <dict></dict> groups in this XML file, as in this example: <!-- <dict> <key>DefaultValue</key> <string>http://spotfire.tibco.com/demo</string> <key>Key</key> <string>featured_url</string> <key>Title</key> <string>Featured List URL</string> <key>Type</key> <string>PSTextFieldSpecifier</string> </dict> -->
The comment markers <!- - and - -> are used to comment out sections of the XML file. Each setting in the file is contained within one of these <dict> … </dict> groups.
TIBCO Spotfire® Deployment Kit for Apple iPad 2.0 – User’s Manual
18
2.4.3.5 Changing Settings Titles In addition to changing the Title property in the Root.plist file for a setting, you can also change the title of a setting in the localized string files that are part of the Settings.bundle file in the Settings folder in the project outline. This is useful when you want a specific string title displayed for a particular language. It is also a lot easier to use to simply change a setting title without having to edit the settings file directly. By default, there are two localization folders (en.lproj and fr.lproj - one English, and one French). In these folders, files are called Root.strings. These files are like the Localization.strings files you worked with previously for customizing app string values. Any entries you make to these files (which by default are empty) will override the settings Title values specified in the Root.plist file. As an example, suppose you want to change the Title value that is displayed for the setting group whose current title is Server Connections in English:
Click on the Root.strings file located in the sub-folder en.lproj for English language. The editor opens and shows a file that is empty except for a comment at the top. You specify string overrides to the Title properties in this file in a similar way to how you specify localizable strings in the app. The syntax of each Title property line in this file is: [Current Settings Title] = [New overridden Title]. So, for our example, we would add the following line: "Server Connections" = "My Server Connections";
Because the existing group setting that we want to change has the Title property value Server Connections, that is what we specify on the left side of the equals sign. On the right side, we specify the new Title value for this setting. Both the key and value in this line must have double-quotes around them. Like before, each line must end with a semi-colon. If you rebuild the app and display the iPad Settings for it, you would see the changed setting title:
Customization
19
2.4.3.6 Adding and Removing Settings Localizations To add and remove localizations in the Settings.bundle, you need to go through a few more steps than was necessary for Localizable.strings in the Strings folder. To add an additional localization to the Settings.bundle file, right-click on Settings.bundle under the Settings folder in the project outline pane in Xcode. Select Show in Finder from the pop-up menu. The file Settings.bundle is an Apple package file, which is a special kind of folder. You can display the contents of this folder in the Finder window by right-clicking again on the Settings.bundle file in Finder and selecting Show Package Contents from the pop-up menu. The structure in the file is similar to what you see in the project outline pane in Xcode. To add a new localization for strings in the settings file, select one of the existing folders (i.e. en.lproj or fr.lproj) and duplicate it. Then rename the new folder to the two letters representing the desired language followed by the .lproj extension. The folder must be named in this way to be found by iOS when the language is changed on the iPad. For more information on the language designations for these folder names, see the Apple developer article at: http://developer.apple.com/library/ios/#documentation/MacOSX/Conceptual/BPInternational/Articles/LanguageDesignations.html#//apple_ref/doc/uid/20002144-BBCEGGFF. You must be a registered Apple developer to view this article. There is a field in the Root.plist file that ties it to the Root.strings file located in each localized language folder in the Settings.bundle. When you add new localized folders, make sure that the strings file in the folder is named Root.strings. To remove a localization, all you need to do is delete the localized folder that corresponds to the language you want to remove.
2.5 Step 5: Configure App Features 2.5.1 Overview
With the TIBCO Spotfire Deployment kit, you can also change how the app behaves when opened, or how the user interface appears. This is accomplished by customizing the entries in the MyConfiguration.plist file located in the Configure Features folder in the project outline pane in Xcode. In particular, you can control which tabs are displayed in the Explore context view of the app, and you can control what tab the app switches to when it starts up. The app can also be instructed to load a particular analysis and immediately display it in the Analyze context view. In addition, you can define your own custom tabs that can display a custom web page given a URL you provide, or a specific Spotfire library page with a URL to the library page that you provide. The MyConfiguration.plist file is an XML file which has entries that control these features and allow you to define the Explore tabs and startup behavior following a specific value syntax which is discussed in this section.
2.5.2 Structure and Syntax of the Configuration File Select the MyConfiguration.plist file from the Configure Features folder in the project outline pane in Xcode to open a property list editor as seen below:
TIBCO Spotfire® Deployment Kit for Apple iPad 2.0 – User’s Manual
20
The file has two configuration entries that control how the app features behave:
• APP_STARTUP_ACTION - string property • EXPLORE_TABS - array of hierarchical values
2.5.2.1 Explore Tabs Property The EXPLORE_TABS property is an array of elements that allow you to override what tabs are displayed in the Explore context view of the app. You may have up to five tabs in the app. Any combination of predefined tabs and custom tabs that you define in this file may be displayed in the app, but only the first five items in this property array are used, extra ones are ignored. Each item in this property array is a dictionary type item. It contains at least one String item with a key value of Type, which may be one of the following predefined type strings:
• SERVERS_TAB • FAVORITES_TAB • RECENTS_TAB • FEATURED_TAB • SILVER_TAB
It may also be the type string CUSTOM_TAB, which indicates that this item defines a custom tab that you create. For CUSTOM_TAB tab types, you must specify additional keys in the dictionary for the tab item:
• Identifier: A user-defined string that can be used to identify this custom tab item. The value for Identifier cannot start with a number and must not contain any special characters other than the dash and underscore. It must also not contain any spaces. Similar rules apply for variable names in Objective-C and other programming languages.
• Title: The tab text that appears in the user interface for this tab item. It is recommended that this text is no longer than 15 characters so that the iPad does not truncate the text when the tab is displayed.
• Url: The fully qualified URL to the custom web page or Spotfire library page to display in this tab view.
• Icon: The file name of an icon file that you have added to your project. The icon should be in the PNG file format. It should be 32 pixels by 32 pixels in width and height, and it can be added to any project group that you wish. You can also create a new group specifically for tab icons in the project outline pane. For instance, in the example image below, a new group called Tab Images has been added to the project, and two tab icon files have been added to that group.
Customization
21
• IconSelected: The file name of an icon used for showing that the tab is selected when
you press it. Like the Icon file, this should be a PNG file that is 32 pixels wide by 32 pixels high. To match the built-in icons for tabs, it should be a solid color mask over the original Icon image. Example Icon and IconSelected Adobe® Photoshop® files are provided for custom tabs with the project, so that you can see how they are created.
In addition to simply specifying the value directly in the Key field, all of these configuration key values (Identifier, Title, Url, Icon, and IconSelected) may contain special keywords that allow the values to reference values that are defined in your Localizable.strings files or in your Settings.bundle file. The following keywords and syntax applies:
• setting: [setting Identifier] The keyword setting: is followed by the Identifier value of a setting to control what value should be used for this tab value. This allows you to specify a setting in your Settings.bundle to use for the value of this parameter for the tab.
• string: [string Identifier] The keyword string: is followed by the Identifier value of a localized string to control what value should be used for this tab value. This allows you to specify a string in your Localizable.strings file to use for the value of this parameter for the tab.
An example can be used to illustrate the proper syntax of entries for predefined and custom tabs in the EXPLORE_TABS section of the configuration file:
In this example, we have five tabs that will be displayed in the Explore context view: The predefined Servers tab, the predefined Featured tab, the predefined Silver tab, followed by two custom tabs. The first custom tab is identified by my_custom_tab1 and entitled My Tab 1 (this title will appear below the tab icon in the user interface). The Title property is from the string my_custom_tab1_title defined in the Localizable.strings file. The Icon and IconSelected
TIBCO Spotfire® Deployment Kit for Apple iPad 2.0 – User’s Manual
22
properties also refer to strings defined in the Localizable.strings file. This tab will use a setting in the Settings.bundle file identified by my_custom_tab1_url to set the fully qualified URL for this tab. The second custom tab is called my_custom_tab2 and has the title My Tab 2, which will display the URL https://myserver.com/mycustomdir/mydxpfile when selected. This tab has an Icon property set to tab2.png, which is in the Tab Images group in the project outline pane. The APP_STARTUP_ACTION specifies that the app will switch to the custom tab called my_custom_tab1 when started up and that tab will show the URL pointed to by the setting my_custom_tab1_url.
2.5.2.2 App Startup Action Property The APP_STARTUP_ACTION property allows you to specify what the app does when it starts up. Possible values are:
• tab: [tab type name or identifier] The keyword tab: is followed by either the Type name of the tab to switch to at startup, or the Identifier of a custom tab (explained above in the section on CUSTOM_TAB type tab items).
• tab: LAST_TAB_DISPLAYED The keyword tab: is followed by the additional predefined symbol LAST_TAB_DISPLAYED to indicate that the app should switch to the tab that was last displayed in the Explore context view when the app was closed.
• tab: setting: [setting Identifier] The keyword tab: is followed by the additional keyword setting:. This is followed by the Identifier of a setting property that will point to the Type name or Identifier of the tab to switch to at app startup.
• tab: string: [string Identifier] The keyword tab: is followed by the additional keyword string:. This is followed by the Identifier of a Localizable.strings file string that will point to the Type name or Identifier of the tab to switch to at app startup.
• analysis: [url to dxp analysis file] The keyword analysis: is followed by the fully qualified URL to a Spotfire DXP file on a server that should be opened and displayed in the Analyze context view at app startup.
• analysis: setting: [setting Identifier] The keyword analysis: is followed by the additional keyword setting:. This is followed by the Identifier of a setting property that will point to the fully qualified URL to a Spotfire DXP file on a server that should be opened and displayed in the Analyze context view at app startup.
• analysis: string: [string Identifier] The keyword analysis: is followed by the additional keyword string:. This is followed by the Identifier of a Localizable.strings file string that will point to the fully qualified URL to a Spotfire DXP file on a server that should be opened and displayed in the Analyze context view at app startup.
