Configuration

The easiest way to build custom apps is to use the special method we provide for you - nokia.mh5.app.embed. This method instantiates a predefined app and embeds it in the given DOM node. There are various configuration properties that you can use to adjust it to meet your needs. It is easy to use, as we made some assumptions about the app structure that should fit in most real-world use cases. If this does not apply in your case, feel free to use our low-level API to gain further control over your app structure and behavior.

Changeable Configuration Properties

Here is an example of the nokia.mh5.app.embed method, which sets a number of properties:

nokia.mh5.app.embed ({
	domNode: "#application_location",
	appId: "demo_wwzrmoloHAFVvyW",
	appCode: "Vgl_08RQWnjJo92Lw1F_uQ",
	hideAddressBar: true,
	configuration: {
		//configuration for the search page
		search: {
			searchAdapter: LastFmSearchAdapter,
			placeholder: "Search artists ..."
		},
		// Configuration for the detail page
		details: {
			listeners: {
				update: function (e) {
					var lfmEvent = e.data;
					// Treat last fm events and nokia places differently.
					// The event overview is shown only for events.
					if (!lfmEvent || !lfmEvent.eventId) {
						this.overview.visible = false;
					} else {
						this.overview.root.innerHTML =
							"<div>" +
							"<div>" + lfmEvent.headliner + "</div>" +
							"<div> <span>Date</span>: " + 
							lfmEvent.startDate + "</div>" +
							"<div> <span>Attendance</span>: " + 
							lfmEvent.attendance + "</div>" +
							"</div>" +
							"<img src=\"" + lfmEvent.eventImage + "\"/>";
							this.overview.visible = true;
					}
				}
			},
			customContent: {
				name: "overview",
				before: "summary",
				cssClass: "lastfm_detailsContent mh5_baseBackgroundColor"
			}
		}
	}
});

The MH5 Framework for Mobile HTML5 enables you to change predefined properties to configure your app. Some of these properties act like switches, which give you the chance to disable specific components that you may not need (by default, we show all of them). Some of them act like handlers and let you replace default components with your own. Others allow you to change app behavior. For example, you can decide if the app should manipulate the browser's history or not.

Configuration may be nested, which means that the value of a specific setting may be a configuration object itself. This configuration object may be used later during the instantiation of a specific component. From a developer's perspective, it may seem like the settings object is divided into several sections.

List of Configuration Properties

This section lists the configurable properties and explains them briefly. Note that complex properties are objects, with properties and nested objects of their own.

  • "domNode" – reference to a DOM element (or string containing CSS selector)
  • "appId" – id of your app; register the app to obtain it
  • "appCode" – code of your app
  • "manipulateUrl" – if true, then the URL is not changed when switching pages
  • "browserHistory" – specifies whether the app changes the browser history (true by default)
  • "configuration" – an object that can include the following properties:
    • "distanceUnit" – unit of distance; possible values are "km" or "mi"
    • "positionDisabled" – disables positioning handling
    • "map" – an object that can include the following properties:
      • "schema" – map schema; possible values are – "normal.day", "hybrid.day", "normal.day.transit", "normal.day.traffic", "normal.day.community", "hybrid.day.community"
      • "positionButton" – if you want to remove the position button from the map, set this property to null
      • "settingsButton" – if you want to remove the settings button from the map, set this property to null
      • "infoBubble" – an object, set this property to null to remove the infoBuble from the map, otherwise, the infoBubble initialization object can include the following properties –
        • "content" – the possible value is one of "title", "descritpion", "more", or "rating"
        • "left" – an image to the left of the content
        • "right" – an image to the right of the content
        • "image" – alternatively, you can construct your own canvas element and pass it complete to the infoBubble constructor; note that when you do that, you can only set the "click" listener which receives a mouse event as its parameter
        • "listeners" – an object containing the following properties (whose values are callback functions):
          • "click" – callback function for user click
          • "leftclick" – callback function for the action on the left image overwrites "click" for the left portion of the bubble
          • "rightclick" – callback function for the action on the right image overwrites "click" for the right portion of the bubble
        • "maxWidth" – the maximum width of the infoBubble, if not set, the infoBubble is as big as it needs to be to fill the available space, up to 50 pixels less than the width of the device/embedded application; extra text is clipped with ellipsis.
      • "search" – the value of this property defines the search component; if you prefer to remove the search component, set the value to null (note that if you remove the search component, you are responsible for switching between the map and the list mode in the phone layout), otherwise you can specify the following search properties:
        • "placeholder" – place holder displayed in the input field in the search page
        • "searchAdapter" – your own search adapter
      • "route" – an object with the following properties:
        • "fromPlaceholder" – place holder displayed in "from" input field in route page
        • "toPlaceholder" – place holder displayed in "to" input field in route page
      • "details" – code that processes search requests, see also nokia.mh5.components.PlaceDetails

Colorization of the App

Almost every element in the MH5 Framework for Mobile HTML5 can be custom-colorized. In most cases, the tool for doing that is CSS that can be changed by a designer. However, if you would like to modify the colors for the map, satellite, traffic and other tiles, you can download the Visual Design Guidelines.

So let's start with an easy one: CSS. The MH5 Framework for Mobile HTML5 ships with colors.css residing in the lib folder, which can be used to customize the colors of most elements.

Table 1. CSS classes
CSS class Description
.mh5_baseBackgroundColor {
	background-color: #124191;
}

Header bar color

.h5o_primaryBackgroundColorBright {
	background-color: #F58600;
}

Place details: Line between category and results

.h5o_primaryBorderColorBright {
	border-color: #F58600;
}

Place details: Little triangle between category and results

.h5o_primaryColorDark,
.h5o_primaryColorDark a {
	color: #F58600;
}

Place details: Text below 'Call', 'Share', 'Route' icons

.h5o_primaryBackgroundColorDark,
.h5o_scrollbarH > div,
.h5o_scrollbarV > div {
	background-color: #F58600;
}

Colors for non-native scrollbars currently used for search results in tablet mode

.h5o_secondaryColorBright,
.h5o_secondaryColorBright a,
.h5o_secondaryColorBright input[type='search'],
.h5o_secondaryColorBrightPH 
	input::-webkit-input-placeholder {
		color: #666666;
}

Search Input Field: Text color and color of input word in Search History/Suggestions

.h5o_secondaryBackgroundColorDark {
	background-color: #666666;
}

Route: Line between input fields and drive/walk/public transport mode button

.h5o_standardBackgroundColorDark {
	background-color: #33343 4;
}

Place details: Background for summary and action icons

.mh5_modalBg {
	background-color: rgba (0, 15, 26, .85) !important;
}

Settings Dialog: Background color/transparency/opaqueness/alpha channel

A different approach is required if you decide to change images used for icons, buttons, and so forth. The corresponding image files reside in lib/img/. The naming convention is self-explanatory. For example, lib/img/categories/transport.png refers to the POI used for public transport stops. You can find more details on how to customize images by downloading the zip file.