Best Practices

Overview

This page summarizes the best recommendations found in the Palm® webOS SDK documentation.

Installing the Palm® webOS SDK

Consider the following recommendations for installing the SDK:

• RAM: Min. 1 GB, but 2-4 GB is recommended.

• Upgrading the SDK: Before upgrading to a new version, first uninstall the old version.

• Release Notes: Check regularly for updates on the known issues and what is new in the SDK.

General Design Information

This section provides recommendations for the following topics:

• JavaScript and JSON
• Optimizing Battery Power
• Optimizing Performance
• Errors
• Events
• Response Handling
• Saving Data
• Saving Memory

JavaScript and JSON

Consider the recommendations in the following table. For more info, see appinfo.json and Wikipedia®.

Topic	Recommendation
JSON syntax	Do not include comments (/* or //) in the .json files. Use quotation marks around properties and strings, instead of single quotes. Use a reverse domain naming system (DNS) convention, but you can use other schemes if the ID is guaranteed to be unique.
Strings	Do not use concatenations, and include your variables inside the localizable strings. The reason is that when translated they can change their location and order relative to the rest of the localizable text.

Optimizing Battery Power

Consider the recommendations in the following table. For more info, see Services API.

Topic	Recommendation
Card, operating mode	You can detect if a card is running in the foreground (full screen) or background (card view). Depending on the application, it may be necessary to change the behavior when the card is inactive in the background with no user interaction. Adjust application behavior as follows: When active, it should efficiently use the system resources. When inactive (triggered by the user or system) and minimized to a card, it should run conservatively.
Card, launching	See Launching New Cards.
Internet connections	Use the Internet sparingly. Make intelligent network requests (e.g., connections that are at least 15 minutes apart, which is the default polling rate for Palm Internet applications) to avoid quick battery drains. It may not be obvious to the user that the application uses a lot of battery power. If possible, adjust the polling rates according to the anticipated change in data. Only check for updated data when necessary.
Location service	Use the least power-intensive position fix needed for the application because higher-accuracy fixes take more power and time.
Notifications	Limit the use of notifications, which temporarily turns on the screen and keeps the system out of Sleep mode.
Palm® Mojo™ Messaging service	Use this service, which does not use Internet polling, to save battery life.
Wakeup feature	Limit the use of this feature. There is overhead associated with waking up the device and then going back into Sleep mode. Even running a simple operation, like checking the clock, can have a considerably higher real processing time and battery consumption, regardless of whether you use the Internet or notify the user in some way.

Optimizing Performance

Consider the recommendations in the following table. For more info, see Initialization and Allocations.

Topic	Recommendation
Image Picker	Move this into the System UI so that it is there from the launch.
List code	Set renderLimit to be high (e.g., 200), but when the list code asks for data just give it 10-20 at a time. It renders that and then asks for more so we can get a quicker initial bring-up time and it works faster overall for scrolling. This is a hybrid version of timeslicing.
Objects, allocating	If allocating objects in initialize() and setup(), do the equivalent clean up in cleanup().
Objects, properties	To improve general performance: Initialize the object properties (i.e., fields and methods) in the classes' initialize() method. Avoid allocations in critical code paths.
Timing	Improve the scene switch timing with the following: Use aboutToActivate when transitioning to allow all data to show before switching scenes, which makes perceived performance better. Pass info from the list scene to the detail scene so there is no wait for the service to retrieve the data to show something on the screen ASAP. Selection Feedback/Confirmation. Edit the scene for contacts. Provide the ability to call setupWidget at anytime, instead of only in the setup to make lazy loading of widgets easier.

Errors

Report an error when the problem impacts the user experience and the application cannot resolve the issue quickly on its own. Consider the recommendations in the following table.

Topic	Recommendation
Banner notification	Use this location when the user only needs to know about the problem, but does not need to take action.
Dialog panel	Use this location when the application cannot continue without a decision by the user. When writing the message and naming the buttons, remember to phrase the message as concisely as possible so the user understands the issue and what actions they can take. Also, avoid the word "please," negative phrases (e.g., "invalid account" or "wrong password"), and technical phrases (e.g., "server error" or "timed out"). A good example is "Try again." Provide buttons that make it simple to take corrective actions. Use verbs or phrases for the button titles that correspond directly to the language used in the message. If any of the actions are destructive, use the "destructive" button style and provide a CANCEL button.
Inline message	Use this location to show an error alert icon and a message in the scene, under the tapped item that generated the problem. If multiple items contribute to the problem (e.g., incorrect username and password), show a single message summarizing how the user can correct the problem.

Events

Consider the recommendations in the following table. For more info, see Events, Event Handlers, and Mojo.Event.

Topic	Recommendation
Event Handlers	Use the same arguments for registering and unregistering. Pre-cache the callback handler in the initialize() method of your Class.
Listener	Remove event listeners when they are not needed. Generally, look in the scene assistant's cleanup() method. It is important to remove listeners when they are attached to a DOM node outside of the scene or to a node within a closure. If not removed, the application may leak memory. Known issue: There is an issue with referencing elements by DOM ID. The Prototype $ and getElementById do not work across stage boundaries. For multistage applications, use this.controller.listen() to pass an element by DOM ID or use this.controller.get() to retrieve an element by DOM ID. For widgets, observe events on the enclosing element instead of on an element that is part of the widget implementation.
Stop Listening	Use the same method to stop listening to events as for listening to events.

Response Handling

Use .bind(this) to set up the response callbacks to ensure that the execution remains in the original scope when the callbacks are executed. For more info, see Services.

Saving Data

We recommend that you use autoSave when the user edits:

• A value in one field and then taps into another.
• A value and then performs the back gesture.
• A value, minimizes the app to a card, and then exits the application.

Saving Memory

Consider the recommendations in the following table. For more info, see Lightweight Stages, Initialization and Allocations, and Style and CSS Reference.

Topic	Recommendation
Calling bind()	Call bind() once in initialize to avoid creating multiple methods, and then reuse the same one every time.
Event listener	See Listener.
Pre-initializing fields	Pre-initialize the fields in initialize() and setup() for a more representative view of the application's memory consumption. This also allows you to determine if there is a way to reduce the complexity of your data structures.

Building Applications

When planning the work-flow and use of APIs and widgets for your application, remember to incorporate the items from our Application Checklist to take advantage of all that the Palm® webOS™ platform has to offer. How the application appears on the device is just as important as what it does. Therefore, we have summarized in this section some of the physical aspects of the device to take into account during the planning phase.

This section provides recommendations for the following topics:

• Screen Dimensions
• Designing for the Web Browser
• Launching New Cards
• Application Menu
• APIs
• Widgets
• Advanced Features
• Media Extensions

Screen Dimensions

Consider the screen dimensions in the following tables when designing an application for a particular device. If you want the application to respond to rotation changes, set the size of the scene elements so they appear correctly after rotating the device. For more info, see Accelerometer and Canvas Tag Support.

Pre item	Dimension	Comment
Application icon	64 x 64 pixels (W x H)
Browser URL bar	50 pixels (H)
Command Menu bar	50 pixels (H)	Floats above the scene content.
Screen, portrait view	Max. 320 x 480 pixels (W x H) (HVGA)	Full-screen mode occupies the entire area.
Screen, landscape view	Max. 480 x 320 pixels (W x H)	Not all apps rotate to landscape view.
Header bar, fixed	50 pixels (H)	Fixed location and floats above the scene content.
Header bar, scrolling	Varies	We recommend 50 pixels (H).
Notification bar (a)	28 pixels (H)	Always visible.
Notification pop-up	Max. 240 pixels (H), minimizes to 28 pixels (H)	Overlays the scene content. Make as small as possible, never exceeding half the screen height.
Phone title bar	28 pixels (H)
Status bar (a)	28 pixels (H)	Always visible.
View menu	50 pixels (H)	Floats above the scene content.

a. In Full-screen mode, this item is hidden.

The following table lists the differences between the Pre and Pixi devices.

Pixi item	Dimension	Comment
Screen, portrait view	Max. 320 x 400 pixels (W x H) (HVGA)	Full-screen mode occupies the entire area.
Screen, landscape view	Max. 400 x 320 pixels (W x H)	Not all apps rotate to landscape view.

Designing for the Web Browser

Consider the recommendations in the following table. For more info, see Browser Standards.

Topic	Recommendation
Device testing	Use an actual device to test the website before its release. The emulator may not behave exactly the same as an actual device.
Screen size	The device screens are smaller than the emulator. To simulate the actual screen size on the emulator, follow the instructions in Developing Web Content for the Palm® webOS™ Platform.
Finger size	Use a scaled-down screen shot of the emulator to test how easy it is to tap the links and controls with your finger. The design should leave room between tap targets to accommodate different-sized fingertips. Also, be aware that there is no "hover" state on the emulator.
Text size	Use a font size of at least 15 points to limit the need for zooming in. However, if necessary, use 14-point fonts for button labels.
Viewport meta tag	Use this meta tag to limit the width of the rendered website for easier reading without zooming in.

Launching New Cards

Sometimes a user needs to open multiple cards to collect information before continuing with an application, such as when composing an email message. Consider this situation when designing the scenes and workflow for your application. Because each card requires additional device resources, try to launch new cards only when necessary.

Application Menu

Consider the recommendations in the following table. For more info, see Commander Chain, APIs, and Widgets.

Topic	Recommendation
Commands, scene-based	Try to add no more than four commands. If adding more than four, the user has to scroll the menu list. Keep command names short and direct, and use title capitalization for the titles.
Command button icon	Create a 32 x 64 pixels (W x H) PNG file (24 bit/pixel RGB with a 1-bit alpha channel). Draw a 24 x 24 pixels monochrome image in the top 32 pixels for the unpressed state, and then draw a 24 x 24 pixels pressed state in the lower 32 pixels.
Command name	Use title capitalization for command names and include an ellipses (...) if the user must take further action after selecting that menu item to complete the named task.
Menu item, disabled	Generally show a disabled menu item when: That action is commonly available in the circumstances in which it appears currently. For example, most applications can be deleted in the launcher. Applications that cannot be deleted should show the delete menu action in a disabled state, instead of suppressing the action entirely. It is important to communicate that the action would be available, but is not available in the current circumstances.
Menu item, suppressed	Completely suppress a menu item when: Even though that action may be available in other similar circumstances, it is not expected that the action is always available. For example, a "share" menu action may be available in detail views, but the fact that it appears in the Photos application does not mean it would appear in the Videos application. Users do not expect the action to be available.

APIs

Consider the recommendations in the following table. For more info, see Storage and APIs.

API	Recommendation
Cookies	Use this API for small amounts of persistent storage such as preferences, version numbers, and similar data, but use Depot or HTML 5 for caching data for offline use or for performance caches.
Depot	Use this API for simple objects because with more complex objects the Depot conversions are less efficient and may introduce inefficiencies in performance and storage.
Service	Use asynchronous methods to improve application performance. Remember that a service may not return data immediately. In these cases, the application should keep running and allow the user to continuing using the application while waiting for data to arrive. Only create a request object if you need the subscription request to persist beyond the lifetime of the scene, or if you need to access services from outside a scene assistant, such as in an application assistant or a stage assistant. When using a service request object, you are responsible for managing the object and destroying it when it is no longer needed.
Transition	Use the following transitions for consistent application operation: Cross-fade—Moving to a similar level. New Card—Launching another application. Zoom In—Moving down a level in the hierarchy. Zoom Out—Moving up a level in the hierarchy and moving back (gesture).

Top

Widgets

Consider the recommendations in the following tables. For more info, see All About Widgets and Widgets.

Topic	Recommendation
Argument, widgetName	This argument specifies to which widget the attributes and model apply. This can be either the ID or name attribute of the widget's element. It is usually okay to use the ID, but remember that all element IDs in the page's DOM must be unique. Therefore, do not assign an ID to your widget if using it in a list or if there are multiple copies of it on a single scene. In these cases, use name instead.
Properties	You may specify some widget properties in either the model or in the attributes. If specified in both, the widget uses the property specified in the model. Specify the property in the model if it might be changes later, or if you are instantiating the widget as part of a List.
Subwidgets	Rendering subwidgets is slightly more complex, but also handled by the framework. To easily instantiate newly rendered child widgets, use the instantiateChildWidgets() method that is available on the widget controller.
Updating widgets	To reflect changes in their models, use modelChanged(). However, to change the model object that a widget is using, you must use setWidgetModel(). While setupWidget() applies to all widgets with the given name, setWidgetModel() only applies to a single widget. Therefore, you must pass the widget's ID or the actual widget DOM element. Internally, setWidgetModel calls $(widget).

 

Widget	Recommendation
Buttons	Register as a listener for the Mojo.Event.tap event to allow a user to trigger actions. If you do not need advanced features, consider just using the button styling provided by the framework to get a that matches button styling, or create your own with your own styles.
Dialogs	If launching a Dialog by tapping on an element in the main scene, stop the Mojo.Event.tap event before launching the Dialog. Because the scene has handled the event by opening a new container, you do not want the event that created the container to be active on the main scene. If setting itemsCallback to a callback function for supplying list items, there is no need to provide the items array objects at setup time. Whenever the framework needs to load items (speculatively or for display), it calls itemsCallback(listWidget, offset, limit). It is understood that the requested data may not be immediately available. After the data is available, call the given widget's noticeUpdatedItems() method to update the list. It is acceptable to call noticeUpdatedItems() immediately or at any later time. However, lengthy delays may cause various scrolling artifacts.
FilterList	Use this widget if it is better to navigate the list with a search field, particularly a list that is instantly filtered as the user types each character.
Indicators	Use the Spinner widget if space is limited or the operation duration is unknown. Otherwise, use one of the Progress indicators to give the user a bounded duration.
Menu	Do not stop any event that the application does not fully handle. The Commander Chain propagates a number of Framework events to the appropriate framework and system handlers. If you stop all events in the handleCommand method, or stop events you do not fully handle, some basic functionality of the Palm® webOS™ platform will break.
Pickers	This widget is known to be difficult to place within scenes because it occupies a lot of horizontal screen real-estate. We recommended that you style a Picker in a scene as follows: <div class = "palm-row" x-mojo-focus-highlight = "true"> <div class = "palm-row-wrapper"> <div class = "title"> <div id = "datepicker" x-mojo-element = "DatePicker"></div> </div> </div> </div>
Progress	Use this widget when a list has many items, or the progress of an event is embedded in another complicated layout. Show a Progress or an Activity Indicator if a process is going to take 2 seconds or more to complete.
ProgressSlider	Use this widget for media or other applications where only part of the content is available at any given time.
RichTextEdit	Known issue: For now, you have to use the blur event and pull the text content from the RichTextEdit's DOM element.
Scroll Listener	Making a change in response to every listener callback makes scrolling slower.
Slider	The framework uses the minimum and maximum values provided at setup to determine the current value associated with the slider. If you specify 0 to 100, and the knob is centered, the updated value is 50; specify 0 and 1, the updated value is 0.5.
Spinner	The framework provides two sizes of spinner widgets: the large Spinner is 128 x 128 pixels, which should be used to show full-screen progress, and the small Spinner is 32 x 32 pixels. These metrics are for the Palm® Pre™ screen and may vary on other devices, but the proportions and overall fit within the UI are maintained.

Advanced Features

Consider the recommendations in the following table. For more info, see Advanced Applications.

Topic	Recommendation
Dashboard panel	Create a Dashboard panel with a summary of the notification, or accumulated notifications if several have been posted without any actions taken.
Dashboard stages	The full framework CSS does not automatically load within a Dashboard stage. Currently, many of the styles for use in a card stage or main application window are not available for Dashboard stages. Therefore, you may have to copy the selectors and style properties to your application CSS. Add a listener to the Mojo.Event.stageActivate event for notification of when the user taps on the Notification bar to bring up the Dashboard view that maximizes all dashboard panels. Also, add a listener to Mojo.Event.stageDeactivate for minimized events.
Notifications, banner	Use banner notifications only when not in focus, either minimized (with a card view but not the foreground card) or in the background (without a card stage). Also, have a Dashboard stage follow the banner if the user does not tap the banner. However, neither of these guidelines are enforced by the framework.
Notifications, category	Define a category for your notifications to avoid having them replaced by other default banners, or if there are multiple notification streams to manage.
Pop-up scene	UI conventions dictate that you use pop-up scenes for simple messages and selections. The pop-up assistant must close the window on exit to close the stage and remove it from the screen.
Processed events	Show one tap target if the application needs to report a single event. If the application accumulates multiple items while running in the background, show them using two tap targets.
Secondary card	Use a different name from that of the stage. Use getStageProxy() if cardStage can be in the process of being brought up when calling this method.
Stage	As with other assistants, initialize the stage in the constructor method.

Media Extensions

Consider the recommendations in the following table. For more info, see Media Extensions.

Topic	Recommendation
Audio and video objects	Set the .palm.audioClass parameter before starting playback of media.
Media object	Create a media object by extending an existing HTML DIV object by using AudioTag.extendElement().

Top

Launching and Testing

This section provides recommendations for the following topics:

• Launching the App
• Usability Testing

Launching the Application

Consider the recommendations in the following table. For more info, see Application Launch Cycle and Application Lifecycle.

Topic	Recommendation
handleLaunch method	Consolidate all launch handling with the application assistants' handleLaunch methods, which are called after setup. This method in the AppAssistant can also launch or sub-launch the application. Including this method registers the application with the Application Manager service and allows another application to launch it through the Application Manager or from a point within their own application, such as from a Dashboard panel. In this latter case, it is better to call handleLaunch directly as a method of the AppAssistant because it is a more direct call and not subject to the overhead of going through the Application Manager.
Improvements	Improved with the following: Built-in framework Default BG Snap shot of a scene that is identified by the app author Slow down and spread out animations, make them nonlinear and more interesting Speed up spinners Splash screen

Usability Testing

Consider the recommendations in the following table.

Topic	Recommendation
Installing a new version of the application	Installing the application's new version does not remove the previous source files that are excluded from the new version. Therefore, for testing purposes, delete the old version of the application before installing the new version.
Looking for user trends	If many users experience the same problems, there is probably a problem with the UI design or implementation. If only one or two people have problems, try to find out why.
Observing users	Watch the users while they test the device. Let them struggle a little and see if they can figure out what to do without your help. If they struggle for too long or are getting frustrated, ask them what they are trying to do to understand their thought process.

Top