JSON Configuration Reference

To customize GetSocial UI you have to provide custom assets (drawables, fonts) and json configuration file.

Default JSON

default.json is a UI configuration file that we use for the default theme of the GetSocial UI. We recommend to use it as a starting point in building your json UI configuration.

In the following sections json configuration file structure will be described.

Base Design

Base design object has a set of properties that describe base design mockup settings and UI behaviour on different screen sizes. GetSocial SDK need to know base design width, height, ppi and scale-mode to calculate UI element sizes on screens with a various resolutions and pixel densities.

Width and height is a pixel resolution of base design mockup PSD, ppi is a density resolution measured in pixels/inch.

Base design section is mandatory in json configuration. Here is example taken from default.json:

1
2
3
4
5
6
"base-design": {
    "scale-mode": "scale-with-screen-size",
    "width": 320,
    "height": 640,
    "ppi": 72
}

Scaling Modes

For now SDK support only scale-with-screen-size scaling mode.

Scale with screen size mode

Using the scale-with-screen-size mode, positions and sizes can be specified according to the pixels of a specified base design resolution. If the current screen resolution is larger than the base design resolution, the canvas will keep the aspect ratio of the base design, but will scale up to fit the screen. If the current screen resolution is smaller than the base design resolution, the canvas will similarly be scaled down to fit. In any case SDK will keep the aspect ratio of the base design.

If the current screen resolution has a different aspect ratio than the base design resolution, the SDK will make the canvas resolution deviate from the base design resolution to respect the aspect ratio of the screen. SDK will make sure that canvas will always be fully visible (not cropped) a fit the same amount of content on any screen size and density, see illustration below.

Assets Base Path

Property assets-base-path specifies common part of the path for the resources, e.g. if assets are located in Resources/getsocial/assets/getsocial/Assets/StreamingAssets/getsocial/ folder, configuration should be following:

1
"assets-base-path": "getsocial"

Text Styles Definition

text-styles object contains all the text style definitions that can be used to configure elements under elements object.

Each text style has the following properties:

  • font - mandatory parameter, can be one of two:
    • font name registered in the system, e.g. HelveticaNeue ;
    • path to the font file relative to folder specified in assets-base-path property, e.g. fonts/HelveticaNeue.ttf; note that SDK supports only TTF fonts;
  • font-size - mandatory parameter, font size measured from base design mockup in points (pt), can be a float value;
  • font-color, stroke-color - optional, color properties specified in 0xAARRGGBB format;
  • stroke-size, stroke-offset-x, stroke-offset-y - optional, integer values that should be measured from the base design mockup in pixels.

Font sizes are specified in point

Unlike dimensions, that are specified in pixels (px), font-size property expect values in points (pt).

File name should match postscript name

Font file name should be exactly the same as font postscript name and not file name. Learn how to find postscript name on mac here.

Define text style:

1
2
3
4
5
"content": {
    "font": "HelveticaNeue",
    "font-size": 16.0,
    "font-color": "0xFF797E85"
}

Use it for one of the elements:

1
2
3
"content": {
    "text-style": "content"
}

UI Elements Configuration

All elements are configured with a set of properties.

Each property can be one of the following types: dimension, color, drawable, text style, insets, paddings, aspect ratio or constant. Type of property is defined by it’s suffix, e.g. bg-image-normal is a drawable property because it has bg-image suffix.

Check the full list of available properties for elements in the default.json.

Specifying Dimensions

Suffixes that correspond to dimension properties: height, width, margin-top, margin-bottom, margin-left, margin-right, text-y-offset-normal, text-y-offset-pressed, radius, border-size, border-radius.

Dimensions are the integer numbers and should be measured from base design mockup in pixels:

1
2
3
"header": {
    "height": 38
}

Specifying Colors

Suffixes that correspond to color properties: bg-color, tint-color, bar-color, hint-color, border-color, bg-color-normal, bg-color-pressed, bg-color-even, bg-color-odd, bg-color-read, bg-color-unread, bg-color-selected.

Color properties support alpha and should be specified in 0xAARRGGBB format:

1
2
3
"header": {
    "bg-color": "0xFF2A3B45"
}

Specifying Drawables

Suffixes that correspond to drawable properties: bg-image, bg-image-normal, bg-image-selected, bg-image-pressed, default-image.

SDK will load drawables without any configuration if they:

  • are located in the folder specified in assets-base-path property;
  • has convention names (original names after executing exportAssets action on assets.psd).

In case you want to use custom name or reuse the same drawable for several UI elements (e.g. use the same image for several buttons) you have to specify path to the image relative to folder specified in assets-base-path property.

Fo instance, if on Android, you want to use image located in assets/getsocial/buttons/green-button.png:

1
2
3
4
5
6
7
"invite-friends-button": {
    "bg-image-normal": "buttons/green-button.png",
    "bg-image-pressed": "buttons/green-button.png"
},
"activity-action-button:": {
    "bg-image-normal": "buttons/green-button.png"
}

Specifying Text Style

Suffixes that correspond to text style properties: text-style, text-style-normal, text-style-selected.

Text styles configuration consist from two parts: definition in the text-styles block and usage in elements configuration by referencing text style id. Learn how to define a new text style.

To use a text style on the element:

1
2
3
"content": {
    "text-style": "content"
}

Specifying Paddings

A suffix that correspond to insets properties: text-insets.

Paddings (or text-insets) define the relative area within the image that the contents of the view are allowed to lie within.

In the mockup above, the dark area identifies the region in which the contents of the view are allowed. If the contents do not fit in this region, then the image will be stretched so that they do.

Paddings are an integer numbers and should be measured from base design mockup in pixels, order in the json configuration: “top right bottom left”:

1
2
3
"badge": {
    "text-insets": "0 4 0 4"
}

Important

Unlike drawable insets, that should be measured from the source file, paddings should be measured from base design mockup.

Specifying Aspect Ratio

A suffix that correspond to insets properties: aspect-ratio.

Aspect ratio can be specified as a string ("width:height") or a float number (result of division width/height):

1
2
3
"activity-image": {
    "aspect-ratio": "16:9"
}

Specifying Animation Style

For now only window element has animation property.

Supported values for animation-style:

  • none - window appears without animation
  • scale - animation scales the window in and out
  • fade - animation fades the window in and out
  • fade-and-scale - animation fades and scales the window in and out at the same time

Default animation is set to scale:

1
2
3
"window": {           
    "animation-style": "scale"
}

Give us your feedback! Was this article helpful?

😀 🙁