doc/writing-config.xml.md

   1 Writing the configuration file "config.xml"
   2 ===========================================
   3
   4 About "config.xml"
   5 ------------------
   6
   7 The file **config.xml** describes important data of the application
   8 to the framework:
   9
  10 - the unique identifier of the application
  11 - the name of the application
  12 - the type of the application
  13 - the icon of the application
  14 - the permissions linked to the application
  15 - the services and dependancies of the application
  16
  17 The file MUST be at the root of the widget and MUST be case sensitively name
  18 ***config.xml***.
  19
  20 The file **config.xml** is a XML file described by the document
  21 [widgets].
  22
  23 Example of "config.xml"
  24 -----------------------
  25
  26 Here is the example of the config file for the QML application SmartHome.
  27
  28 ```xml
  29 <?xml version="1.0" encoding="UTF-8"?>
  30 <widget xmlns="http://www.w3.org/ns/widgets" id="smarthome" version="0.1">
  31   <name>SmartHome</name>
  32   <icon src="smarthome.png"/>
  33   <content src="qml/smarthome/smarthome.qml" type="text/vnd.qt.qml"/>
  34   <description>
  35         This is the Smarthome QML demo application.
  36         It shows some user interfaces for controlling an automated house.
  37         The user interface is completely done with QML.
  38   </description>
  39   <author>Qt team</author>
  40   <license>GPL</license>
  41 </widget>
  42 ```
  43
  44 Standard elements of "config.xml"
  45 ---------------------------------
  46
  47 ### The element widget
  48
  49 #### the attribute id of widget
  50
  51 The attribute *id* is mandatory (for version 2.x, blowfish) and must be unique.
  52
  53 Values for *id* are any non empty string containing only latin letters,
  54 arabic digits, and the three characters '.' (dot), '-' (dash) and
  55 '_' (underscore).
  56
  57 Authors can use a mnemonic id or can pick a unique id using
  58 command **uuid** or **uuidgen**.
  59
  60 #### the attribute version of widget
  61
  62 The attribute *version* is mandatory (for version 2.x, blowfish).
  63
  64 Values for *id* are any non empty string containing only latin letters,
  65 arabic digits, and the three characters '.' (dot), '-' (dash) and
  66 '_' (underscore).
  67
  68 Version values are dot separated fields MAJOR.MINOR.REVISION.
  69
  70 ### The element content
  71
  72 The element *content* is mandatory (for version 2.x, blowfish) and must designate a file
  73 (subject to localisation) with its attribute *src*.
  74
  75 The content designed depends on its type. See below for the known types.
  76
  77 ### The element icon
  78
  79 The element *icon* is mandatory (for version 2.x, blowfish) and must
  80 be unique. It must designate an image file with its attribute *src*.
  81
  82 Known widget types and content
  83 ------------------------------
  84
  85 The configuration file ***/etc/afm/afm-launch.conf*** defines the types
  86 of widget known and how to launch it.
  87
  88 Known types for the type of content are (for version 2.x, blowfish):
  89
  90 - ***text/html***:
  91    HTML application,
  92    content.src designates the home page of the application
  93
  94 - ***application/x-executable***:
  95    Native application,
  96    content.src designates the relative path of the binary
  97
  98 - ***application/vnd.agl.url***:
  99    Internet url,
 100    content.src designates the url to be used
 101
 102 - ***application/vnd.agl.service***:
 103    AGL service defined as a binder,
 104    content.src designates the directory of provided binders,
 105    http content, if any, must be put in the subdirectory ***htdocs*** of the widget
 106
 107 - ***application/vnd.agl.native***:
 108    Native application with AGL service defined as a binder,
 109    content.src designates the relative path of the binary,
 110    bindings, if any must be put in the subdirectory ***lib*** of the widget,
 111    http content, if any, must be put in the subdirectory ***htdocs*** of the widget
 112
 113 - ***text/vnd.qt.qml***, ***application/vnd.agl.qml***:
 114    QML application,
 115    content.src designate the relative path of the QML root,
 116    imports must be put in the subdirectory ***imports*** of the widget
 117
 118 - ***application/vnd.agl.qml.hybrid***:
 119    QML application with bindings,
 120    content.src designate the relative path of the QML root,
 121    bindings, if any must be put in the subdirectory ***lib*** of the widget,
 122    imports must be put in the subdirectory ***imports*** of the widget
 123
 124 - ***application/vnd.agl.html.hybrid***:
 125    HTML application,
 126    content.src designates the home page of the application,
 127    bindings, if any must be put in the subdirectory ***lib*** of the widget,
 128    http content must be put in the subdirectory ***htdocs*** of the widget
 129
 130
 131 AGL features
 132 ------------
 133
 134 The AGL framework uses the feature tag for specifying security and binding
 135 requirement of the widget.
 136
 137 The current version of AGL (up to 2.0.1, blowfish) has no fully implemented
 138 features.
 139
 140 The features planned to be implemented are described below.
 141
 142 ### feature name="urn:AGL:provides-binding"
 143
 144 Use this feature for each provided binding of the widget.
 145 The parameters are:
 146
 147 #### param name="name"
 148
 149 REQUIRED
 150
 151 The value is the string that must match the binding prefix.
 152 It must be unique.
 153
 154 #### param name="src"
 155
 156 REQUIRED
 157
 158 The value is the path of the shared library for the binding.
 159
 160 #### param name="type"
 161
 162 REQUIRED
 163
 164 Currently it must be ***application/vnd.agl.binding.v1***.
 165
 166
 167 #### param name="scope"
 168
 169 REQUIRED
 170
 171 The value indicate the availability of the binidng:
 172
 173 - private: used only by the widget
 174 - public: available to allowed clients as a remote service (requires permission+)
 175 - inline: available to allowed clients inside their binding (unsafe, requires permission+++)
 176
 177 #### param name="needed-binding"
 178
 179 OPTIONAL
 180
 181 The value is a space separated list of binding's names that the binding needs.
 182
 183 ### feature name="urn:AGL:required-permissions"
 184
 185 List of the permissions required by the widget.
 186
 187 Each required permission must be explicited using a <param> entry.
 188
 189 #### param name=[required permission name]
 190
 191 The value is either:
 192
 193 - required: the permission is mandatorily needed except if the feature
 194 isn't required (required="false") and in that case it is optional.
 195 - optional: the permission is optional
 196
 197 ### feature name="urn:AGL:defined-permissions"
 198
 199 Each required permission must be explicited using a <param> entry.
 200
 201 #### param name=[defined permission name]
 202
 203 The value is the level of the defined permission:
 204
 205 - system:
 206 - platform:
 207 - partner
 208 - public:
 209
 210
 211
 212
 213
 214 [widgets]:          http://www.w3.org/TR/widgets                                    "Packaged Web Apps"
 215 [widgets-digsig]:   http://www.w3.org/TR/widgets-digsig                             "XML Digital Signatures for Widgets"
 216 [libxml2]:          http://xmlsoft.org/html/index.html                              "libxml2"
 217 [app-manifest]:     http://www.w3.org/TR/appmanifest                                "Web App Manifest"
 218