Customization points section
/docs/development/reference-gears/manifest/customizationpoints/
Apps and Accessories may define “customization points”, which enable the user to configure the App or Accessory at deploy time.
If you invoke ubos-admin createsite
and specify an App that declares one or more
required customization points, you will be asked for values for those customization points.
(If you specify --askForAllCustomizationPoints
as argument, you will be asked for
values for all customization points, not just the required ones.)
Here is an example:
"customizationpoints" : {
"title" : {
"type" : "string",
"required" : false,
"default" : {
"value" : "My wiki"
}
}
}
This App, or Accessory, declares a single customization point whose
programmatic name is title
. It is of type string, meaning that a value provided for it
must be a valid string. No value has to be provided by the user for this customization point,
as it is not required
; if none is provided, the default value “My wiki” will be used
instead.
Customization points are useful to set information such as the title of the installed App, a logo, or settings such as whether comments should be allowed etc.
The following types of customization points are currently recognized:
string
: A text string. May not contain newlines.email
: A valid e-mail address.url
: A valid URL.text
: A text string that may contain many lines.password
: A password. UBOS may enforce certain rules about password strength.boolean
: Eithertrue
orfalse
.integer
: A whole number that may be positive, negative or zero.positiveinteger
: A whole number that must be 1 or greater.positiveintegerorzero
: A whole number that must not be negative.float
: A floating-point number that may be positive, negative or zero.image
: An image in a supported file format.
The default value may be provided in encoded form. For example, a GIF image may be
provided in base64 encoding. Currently only plain (the default) and base64 encoding are
supported. To provide a default value in base64 encoding, add an encoding
field like
this:
"default" : {
"value" : "VUJPUw0K",
"encoding" : "base64"
}
Alternatively to an explicit value, an expression may be provided, such as:
"default" : {
"expression" : "${randompassword(8)}"
}
Customization points may be declared as private:
"customizationpoints" : {
"apikey" : {
"type" : "string",
"private" : true
...
}
}
If declared as private, only root
is allowed to see the provided values.
This applies to commands such as ubos-admin showsite
.
Customization points may also be declared as internal:
"customizationpoints" : {
"salt" : {
"type" : "string",
"internal" : true
...
}
}
If declared as internal, it is not shown to the user as it contains no information that may be useful for the user. This can be used for customization points that, for example, contain salts for internally managed application passwords.
If a customization point is of type string, an optional regular expression may be given. UBOS will enforce that any value given for the customization point conforms to this regular expression. For example:
"customizationpoints" : {
"nospaces" : {
"type" : "string",
"required" : yes,
"regex" : "^[A-Za-z0-9]+$"
}
}
allows the value HiMom
but not the value Hi Mom
.
By default, ubos-admin createsite
will ask the user for values of customization points
in an undefined sequence. To order the sequence in which the questions are asked, add
an index
field whose value is an integer, and which is used for sorting.
For example:
"customizationpoints" : {
"last" : {
"type" : "string",
"index" : 3
},
"first" : {
"type" : "string",
"index" : 1
},
"middle" : {
"type" : "string",
"index" : 2
},
}
These customization points will be presented to the user in sequence first
, middle
,
last
.