Mobile Theming

From HTML5 Builder
Jump to: navigation, search

When working on Mobile Theming, you can work either with JQuery Mobile Theming or directly with style properties.

In JQuery Mobile theming, themes are single CSS files with a basic theme definition. A theme can also include color variations or swatches, sub-themes on top of the base theme. Each of these variations is assigned a letter of the Latin alphabet (so you can define up to 26 color variations). For example, on top of your basic theme you can have a color variation for warning messages, with red colors, and another for a special page of your application; you must assign a letter to each one of these color variations, for example: w for warning messages and s for the special page. Color variation with letter a will be chosen by default.

Default Theme

By default, HTML5 Builder mobile applications will use default JQuery Mobile theme. It includes 5 color variations, which you can choose from the ColorVariation property of any MobileTheme component:

cvBasic (c)
Baseline level of visual priority.
cvHigh (a)
Highest level of visual priority.
cvMedium (b)
Secondary level of visual priority.
cvMedium2 (d)
Alternative secondary level of visual priority.
cvAccent (e)
Accent color variation.

Custom Theme

Mobile Theme

You can create a brand-new custom theme from Home > New > HTML5 Builder Projects > Files > Mobile Theme. If you wish to work from the default jQuery Mobile theme instead, copy it to your project folder, and open it with HTML5 Builder; the theme is located inside the HTML5 Builder installation directory, at rpcl\jquerymobile\css\

When you are done defining its watches, you can save the theme inside your project folder and use it in any page of your application through the MobileTheme component:

  1. Set its Theme property to thCustom.
  2. Set its CustomTheme property to the path of the CSS file.

Tip: The recommended approach is to define a single theme for a single application, as opposed to several themes for the same application.

When you set a color variation for a custom theme, set ColorVariation to cvCustom, and set CustomColorVariation to the letter that identifies the target custom variation.

Note: You must use a lowercase letter in CustomColorVariation, else it will not work. a is right, A is wrong.

Style Properties

You can also use mobile components style properties to change some of their properties. These properties are ignored by default, so if you want them to affect your component, set its Enhancement property to enStructure. That way, JQuery Mobile theme will be applied for its basic structure, but the rest of its style definition will be based on the values of its style properties.

If you want a component to completely ignore JQuery Mobile theme, set its Enhancement property to enNone instead.

Theme Look Up

In HTML5 Builder, for each mobile component, base theme and color variation is decided by checking different properties in different components. For a given component, first property in the list below with a value set will be used:

  1. Component Theme property, which can link to a MobileTheme component.
  2. Component’s parent Theme property, which can link to a MobileTheme component. Parents are looked up recursively until MPage component.
  3. MPage CssFile property.
  4. If MPage CssFile property is set to cssCustom value, CustomCssFile property.

When a MobileTheme is used, this is the lookup order for it:

  1. Theme property.
    1. ColorVariation property as color variation.
    2. If ColorVariation property is set to cvCustom, CustomColorVariation property as color variation.
  2. If Theme property is set to thCustom value, CustomTheme property.
    1. ColorVariation property as color variation.
    2. If ColorVariation property is set to cvCustom, CustomColorVariation property as color variation.

Non-Mobile Style

Those RPCL components that are not among the mobile components might inherit some style properties from the jQuery Mobile theme. If you want to prevent this, you will need to unset the property for those components through CSS:

  1. Create a CSS file: go to File > New > Other… > Web Documents, select CSS Stylesheet and click OK.
  2. Then add the needed code to the file, that is, define a class or classes that unset those undesired CSS property values from the theme. For example: .unthemed{ text-shadow:none;}.
  3. Save the file into your project’s folder.
  4. On every page where you want to apply the CSS code fix, add a StyleSheet component, and point its Filename property to the CSS file location.
  5. On the target components, set their Style property to the class you defined above. For the previous example, it would be .unthemed.

Help Resources


Video Tutorials

Sample Applications

On the JQueryMobile\Theming folder inside the sample applications directory you will find a project showcasing Mobile Theming:

  • ThemingExample.phprj. An interactive explanation of how mobile theming works.