mirror of
https://github.com/cockpit-project/cockpit.git
synced 2026-05-06 04:16:43 -04:00
Freya Gustavsson
bc62cb3709
Antora uses a dedicated folder structure which we need to adhere to for it to work as it should. Makefiles has moved to `doc/` root to simplify the approach needed with Antora and AsciiDoctor. Existing bundling of documentation with help of AsciiDoctor works as normal and does not interfere with the directory change. Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
167 lines
4.8 KiB
Plaintext
167 lines
4.8 KiB
Plaintext
= cockpit.js: Utilities
|
|
|
|
Various utility functions
|
|
|
|
[[cockpit-format]]
|
|
== cockpit.format()
|
|
|
|
....
|
|
string = cockpit.format(template, args)
|
|
string = cockpit.format(template, [arg, ...])
|
|
....
|
|
|
|
Format a string interpolating `+args+` into `+template+` using shell
|
|
like syntax. The `+args+` may be either an array or javascript object.
|
|
The `+template+` can contain fields that look like `+$name+` or
|
|
`+${name}+` or `+$0+`. Numeric fields are used with array `+args+` and
|
|
start at zero.
|
|
|
|
In the second form, multiple `+arg+` arguments may be passed directly,
|
|
and interpolated as as numeric fields in the `+template+`.
|
|
|
|
All falsy arguments except the numbers `+0+` and `+0.0+`are replaced by
|
|
an empty string.
|
|
|
|
[[cockpit-format-number]]
|
|
== cockpit.format_number()
|
|
|
|
....
|
|
string = cockpit.format_number(number, [precision])
|
|
....
|
|
|
|
Formats `+number+` into a displayable `+string+`. If the number is not
|
|
an integer, it is rounded to the given number of decimal places,
|
|
defaulting to 3. If the number is near zero, but not quite zero it is
|
|
rounded to the smallest non-zero value of the given precision; i.e.
|
|
±0.001 for default precision 3.
|
|
|
|
If `+number+` is `+null+` or `+undefined+` an empty string will be
|
|
returned.
|
|
|
|
[[cockpit-format-bytes]]
|
|
== cockpit.format_bytes()
|
|
|
|
....
|
|
string = cockpit.format_bytes(number, [options])
|
|
....
|
|
|
|
Formats `+number+` into a displayable `+string+` with a suffix, such as
|
|
_kB_ or _MB_.
|
|
|
|
By default, SI units are used. IEC units (1024-based) can be requested
|
|
by including `+base2: true+` in `+options+`.
|
|
|
|
By default, non-integer numbers will be formatted with 3 digits of
|
|
precision. This can be changed with `+options.precision+`.
|
|
|
|
If `+number+` is `+null+` or `+undefined+` an empty string will be
|
|
returned.
|
|
|
|
[[cockpit-format-bytes-per-sec]]
|
|
== cockpit.format_bytes_per_sec()
|
|
|
|
....
|
|
string = cockpit.format_bytes_per_sec(number, [options])
|
|
....
|
|
|
|
Format `+number+` of bytes into a displayable speed `+string+`.
|
|
|
|
This function is mostly equivalent to `+cockpit.format_bytes()+` but the
|
|
returned value contains a unit like _kB/s_ or _MB/s_.
|
|
|
|
[[cockpit-format-bits-per-sec]]
|
|
== cockpit.format_bits_per_sec()
|
|
|
|
....
|
|
string = cockpit.format_bits_per_sec(number, [options])
|
|
....
|
|
|
|
Format `+number+` of bits into a displayable speed `+string+`.
|
|
|
|
This function is mostly equivalent to `+cockpit.format_bytes()+` but the
|
|
returned value contains a unit like _kbps_ or _Mbps_.
|
|
|
|
This function does not support IEC units. `+base2+` may not be passed as
|
|
part of `+options+`.
|
|
|
|
[[cockpit-init]]
|
|
== cockpit.init()
|
|
|
|
....
|
|
await cockpit.init();
|
|
|
|
cockpit.init().then(() => { ... });
|
|
....
|
|
|
|
Requests initialization of the Cockpit client library. This will ensure
|
|
that the transport is connected and we are ready to create channels. It
|
|
also populates the `+cockpit.info+` field.
|
|
|
|
This function returns a promise. Initialization isn't complete until the
|
|
promise has resolved. You can either `+await+` it or call `+.then()+` on
|
|
it.
|
|
|
|
[[cockpit-info]]
|
|
== cockpit.info
|
|
|
|
....
|
|
cockpit.info.channels[payload]
|
|
|
|
cockpit.info.os_release[field]
|
|
|
|
cockpit.info.user
|
|
|
|
cockpit.info.ws.version
|
|
....
|
|
|
|
This object contains information about Cockpit itself. It is only
|
|
available after cockpit.init() has been called and awaited.
|
|
|
|
`+channels+`::
|
|
This is a mapping of channel payload types (keys, strings) supported
|
|
by the bridge to capabilities advertised by those channels (values,
|
|
lists of strings). Channels are listed even if they don't advertise
|
|
any capabilities, making this useful as a way to determine which
|
|
channel types are supported by the bridge.
|
|
`+os_release+`::
|
|
This is the data from the `+/etc/os-release+` or
|
|
`+/usr/lib/os-release+` on the system that the bridge is running on.
|
|
It is a mapping from the key names to their values. See the
|
|
https://www.freedesktop.org/software/systemd/man/latest/os-release.html[os-release
|
|
Specification] for information about the available keys.
|
|
`+user+`::
|
|
Contains information about the user we're logged in as.
|
|
`+uid+`;;
|
|
This is unix user id as an integer.
|
|
`+gid+`;;
|
|
This is unix user group id as an integer.
|
|
`+name+`;;
|
|
This is the unix user name like `+"root"+`.
|
|
`+fullname+`;;
|
|
This is a readable name for the user, from the GECOS field.
|
|
`+group+`;;
|
|
This is the primary group name of the user.
|
|
`+groups+`;;
|
|
This is an array of group names to which the user belongs. The first
|
|
item in this list is the primary group.
|
|
`+home+`;;
|
|
This is user's home directory.
|
|
`+shell+`;;
|
|
This is unix user shell.
|
|
`+ws+`::
|
|
Contains information about the webserver Cockpit is being served with.
|
|
`+version+`;;
|
|
The version of the webserver.
|
|
|
|
[[cockpit-event-target]]
|
|
== cockpit.event_target
|
|
|
|
....
|
|
cockpit.event_target(object, [handlers])
|
|
....
|
|
|
|
Adds an
|
|
https://developer.mozilla.org/en-US/docs/Web/API/EventTarget[EventTarget]
|
|
implementation to the `+object+`. Optionally store the handlers in
|
|
`+handlers+` if its specified.
|