Pixate Freestyle for iOS Styling Reference

This reference the explains Freestyle from a designer's perspective. It summarizes the Freestyle's CSS3 support, and the style-able iOS native controls and their properties.

App Styling with Freestyle

Freestyle styles native iOS controls using CSS. The runtime is built on a scalable vector graphics engine, a standards-based CSS styling language, and a lightweight library for interacting with iOS native controls.

Freestyle has tailored the familiar CSS3 language for the styling needs of native mobile components. Freestyle CSS is "full CSS" with the exception of not supporting pseudo-elements and a few minor differences noted in this document.

Application Structure

Let's begin with an overview of a Freestyle-based application. At application start-up, Freestyle looks for your application's CSS in a file named default.css, which can be located anywhere within your project. The default.css file can include other CSS files by using @import.

CSS rules are applied using a control's element name, class, id or other attributes. This information is represented at runtime by properties on Objective-C objects.

The element name is determined by the type of control. For example, all UIButton controls have the button element name. The control descriptions (see Native iOS Controls) lists the element name for each iOS control.

class and id are determined by the styleClass and styleId properties respectively of individual control instances. By convention, styleClass is shared by all controls with a related function or layout in the application, perhaps members within the same view. styleId is expected to be unique across the application. These conventions are not enforced by the Freestyle, and setting of these properties is not required unless you want to select controls using these properties. These properties are typically set by the application developer.

Inline CSS

Application developers can style a specific control by setting the control's styleCSS property. This property is analogous to the style property of web CSS.

Specificity

CSS Specificity determines which rules apply to controls. Freestyle follows standard CSS specificity rules.

Tip: Specificity is not simple and is usually the reason why your CSS-rules don't apply to some controls in the way you think they should. Some excellent Specificity tutorials are available, including: CSS Specificity: Things You Should Know.

CSS Media Queries

@media rules use CSS media queries to conditionally apply styles for different devices, screen resolutions, and orientations.

The following media expressions are allowed:

  • orientation: portrait | landscape
  • device: ipad | iphone | ipad-mini
  • device-width: |
  • min-device-width: |
  • max-device-width: |
  • device-height: |
  • min-device-height: |
  • max-device-height: |
  • scale:
  • min-scale:
  • max-scale:

Media types (e.g., 'print') are not supported. Use 'and' to join multiple media expressions.

Below are example uses of the @media rule:

/* Rule sets apply only when the device is in portrait orientation */
@media (orientation:portrait) { }

/* Rule sets apply if the device's height (ignores orientation)
 is at least 1000 pixels and if the device has a retina display. */
@media (min-device-height:1000px) and (scale:2) { }

/* Apply rules to iPad Mini in landscape mode. */ 
@media (orientation:landscape) and (device:ipad-mini) { }

iPod and iPhone devices appear the same and are both targeted using device:iphone. The iPad-Mini form factor is not supported in the simulator so it appears as an iPad in the simulator.

Finally, note that CSS does not support @import statements within @media rules.

Importing Style Sheets

The @import rule allows importing style rules from other style sheets. The @import statement must be followed by a URL that references a file within the application bundle or the device's Documents folder. The following statements are equivalent.

@import url("style.css")
@import "style.css"

Note that the @import does not support the CSS3 @media rule for specifying conditional style sheets or alternative style sheets. Also @import is not supported within an @media statement. This restriction is silently enforced.

Media Assets

Media assets are accessed using the url function and must be contained within the Application's bundle or on the device filesystem. Resources in the application bundle can be accessed using bundle://, files on the device are acessessed using file://, and resources in the device documents folder can be accessed using documents://. If no protocol is specified, the resources will be searched for first in the documents folder then in the resource bundle.

/* search in documents folder and application bundle for resource */
background-image:    url(star.svg);

/* search for resource in a subfolder of Documents */
background-image:    url(documents://myResources/star.svg);

/* search for resource in a subfolder of  */
background-image:    url(file://images/star.svg);

/* search for resource in application bundle */
background-image:    url(bundle://star.svg);

Runtime Configuration

The Freestyle engine allows you to customize some of its behavior, using CSS and a custom configuration element. You can access the configuration element by referencing it with the freestyle-config selector. For example:

freestyle-config {
  parse-error-destination: console;
  cache-styles: auto;
  image-cache-count: 100;
}

In the example above, adding this snippet to default.css would send parse errors to the console, set up default cache settings, and bump the image cache count to 100 images.

Configuration Properties

Property Value
parse-error-destination

none or console

Setting it to console displays any parse errors in your project's CSS in the XCode console during debugging. The default value is none.

cache-styles

auto, none, all, minimize-styling, and cache-images

Used to toggle caching and to set limits for those caches. This property accepts a comma-delimited list of the preceding values. Values are processed in order and are accumulated. auto is the same as minimize-styling, cache-images. minimize-styling tries to prevent styling of an element if its styling has not changed. cache-images caches images generated during styling to avoid unnecessary rendering on future stylings and to generally increase styling speeds. The default (and recommended) value is auto.

image-cache-count

number

Determines how many images we be retained in the image cache, assuming it has been turned on with cache-styles. If this is set to 0, then there will be no upper limit to how many images live in the cache. The default value is 10.

image-cache-size

number

Determines how many bytes of image data are retained in the image cache. A value of 0 indicates that there is no upper limit to how many bytes can live in the cache. Note that image-cache-count will still be honored. The default value is 0.