README_Jolla

THIS IS A README FOR TEMPLATE AMBIENCE

The Other Half (TOH) can be used to install different kind of content from Jolla
store. TOH always installs a new wallpaper and colors, but rest of the content
is not mandatory.

In addition to wallpaper and colors it can install sounds tones (7 different) and
any kind of content which can be installed via RPM packaging such as applications
either packed in to the same RPM package or via dependency, music, videos, browser
bookmarks to the home.

INSTALLATION

When user attach TOH, it is detected by ambience backend and it asks Store to
install corresponding package if it's not yet installed. Store fetches the package
information first and after that it asks user, if ambience package should be
installed. If user selects to install the package, then installation status is
shown on the home screen and once the intallation is done, the downloaded
ambience will be activated.

TOH ID

Every TOH needs to have TOH ID. TOH ID is used for fetching package information
from the Store. In the Store backend side, it is required to have mapping from
TOH ID to the correct ambience RPM package. Without this mapping ambience RPM
package can't be installed.


CREATING AMBIENCE RPM PACKAGE

This ambience-template package should be used as a reference when creating new
ambiences. The template package is the latest documentation of how to create
ambience RPM package.

It is recommended to have the following structure for an ambience package:

template-ambience
  |
  |
  ambience-template.ambience - Defines ambience wallpaper, sounds and colors
  |
  images (directory)
  |   |
  |   template.jpg - Wallpaper image
  |
  sounds.index - Translation id's for all the sound files
  |
  sounds (sound file directory)
  |   |
  |   template-ringtone.wav
  |   template-message.wav
  |   template-im.wav
  |   template-email.wav
  |   template-calendar.wav
  |   template-clock.wav
  |
  translations (Directory)
  |   |
  |   AmbienceTranslations.qml - Defines all the strings which can be translated


NOTE: each 'template' should be renamed in the final implementation.

FILE 'ambience-template.ambience'

Defines all the parameters for the ambience. It should be installed in:

    '/usr/share/ambience/template-ambience'

directory. Ambience file name must always reflect the name of the installation
directory for example 'my-first-ambience' will be installed in:

    '/usr/share/my-first-ambience'

and ambience file name must be named as 'my-fist-ambience.ambience'.

This is required in order to make sure that when the ambience is installed via
store, it can be guaranteed that installation succeeds.

AMBIENCE COLORS

Every ambience should define colors which match the ambience wallpaper. When an
ambience is installed via ambience RPM package, the colors won't be autogenerated.

Usually ambience only defines two colors:

    "highlightColor"            : "#FF9D80",
    "secondaryHighlightColor"   : "#FF9D8099",

Highlight and the secondary highlight colors are mostly used theme colors on
Sailfish OS to indicate custom ambience and the mood it has created. The
convention here is that secondaryHighlightColor is always the highlightColor with
opacity.

    "primaryColor"              : "#FFFFFF",
    "secondaryColor"            : "#FFFFFF99",

Primary and secondary colors usually aren't changed at all.

AMBIENCE TONES

Ambience can be installed with or without any tones. Tone file can be defined as
shown below:

    "ringerToneFile" : { "file": "template-ringtone.wav", "enabled": 1 }

But it can also be left out:

    "ringerToneFile" : { "file": "", "enabled": 1 }

Which means that then when this ambience is activated, it fallbacks to the default
Sailfish OS ringtone.

FAVORITE AMBIENCES:

By default ambiences are not favorited, if there's no 'favorite' flag set. This
means that ambience won't be promoted to the Ambience switcher in the home screen.
To make an ambience a favorite ambience, set the 'favorite' flag true:

    "favorite : true

RINGER VOLUME:

Ambience can be define the inial ringer volume level, but it can be changed by
user later. To use the default system ringertone volume, the volume level can
be set to -1. To define pre-set level, the value must be in between 0 and 100.

    "ringerVolume" : 70

SEE template.ambience file for all the parameters which can be used by ambience.

DIRECTORY 'images'

Usually images directory contains only used wallpaper image, but it can also
contain other images which are installed by this ambience. By default, when a
new ambience file is parsed the wallpaper is searched from the 'images' directory.

It should be installed in:

    '/usr/share/ambience/template-ambience/images'

FILE 'template.jpg'

This file is used to create background for the ambience. It can be either JPEG
or PNG image. For the best result, it should be cropped to the following size:

    Width x Height: 540x1600

Without pre-defining the size properly, it can't be guaranteed that the result is
as expected.

FILE 'sounds.index'

File sounds.index is used for defining display name translation IDs for the
sound files for example:

    { "displayName" : "template-ringtone", "fileName" : "template-ringtone.wav" },

The 'template-ringtone' id must be defined in AmbienceTranslations.qml file

DIRECTORY 'sounds'

The 'sounds' directory contains all the sound files for different tones. It should
be installed in:

    '/usr/share/ambience/ambience-template/sounds'

DIRECTORY 'translations' and FILE 'AmbienceTranslations.qml'

The 'translations' directory contains QML file 'AmbienceTranslation.qml' which
defines translation IDs for the strings which should be translated such as
the display name for the ambience or translations for sound files.