docs/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:required-binding"
 143
 144 List of the bindings required by the widget.
 145
 146 Each required binding must be explicited using a <param> entry.
 147
 148 #### param name=[required binding name]
 149
 150 The value is either:
 151
 152 - required: the binding is mandatorily needed except if the feature
 153 isn't required (required="false") and in that case it is optional.
 154 - optional: the binding is optional
 155
 156 ### feature name="urn:AGL:required-permission"
 157
 158 List of the permissions required by the widget.
 159
 160 Each required permission must be explicited using a <param> entry.
 161
 162 #### param name=[required permission name]
 163
 164 The value is either:
 165
 166 - required: the permission is mandatorily needed except if the feature
 167 isn't required (required="false") and in that case it is optional.
 168 - optional: the permission is optional
 169
 170 ### feature name="urn:AGL:provided-binding"
 171
 172 Use this feature for each provided binding of the widget.
 173 The parameters are:
 174
 175 #### param name="name"
 176
 177 REQUIRED
 178
 179 The value is the string that must match the binding prefix.
 180 It must be unique.
 181
 182 #### param name="src"
 183
 184 REQUIRED
 185
 186 The value is the path of the shared library for the binding.
 187
 188 #### param name="type"
 189
 190 REQUIRED
 191
 192 Currently it must be ***application/vnd.agl.binding.v1***.
 193
 194
 195 #### param name="scope"
 196
 197 REQUIRED
 198
 199 The value indicate the availability of the binidng:
 200
 201 - private: used only by the widget
 202 - public: available to allowed clients as a remote service (requires permission+)
 203 - inline: available to allowed clients inside their binding (unsafe, requires permission+++)
 204
 205 #### param name="needed-binding"
 206
 207 OPTIONAL
 208
 209 The value is a space separated list of binding's names that the binding needs.
 210
 211 ### feature name="urn:AGL:defined-permission"
 212
 213 Each required permission must be explicited using a <param> entry.
 214
 215 #### param name=[defined permission name]
 216
 217 The value is the level of the defined permission.
 218 Standard levels are:
 219
 220 - system
 221 - platform
 222 - partner
 223 - public
 224
 225 This level defines the level of accreditation required to get the given
 226 permission. The accreditions are given by signatures of widgets.
 227
 228
 229
 230 [widgets]:          http://www.w3.org/TR/widgets                                    "Packaged Web Apps"
 231 [widgets-digsig]:   http://www.w3.org/TR/widgets-digsig                             "XML Digital Signatures for Widgets"
 232 [libxml2]:          http://xmlsoft.org/html/index.html                              "libxml2"
 233 [app-manifest]:     http://www.w3.org/TR/appmanifest                                "Web App Manifest"
 234