Skip to main content

Crate collect_settings

Crate collect_settings 

Source
Expand description

Build, encode and decode the configuration QR codes used by ODK Collect and its rebrand KoboCollect.

A configuration QR code carries a JSON document with three sections:

  • General — unprotected settings: server, account, form management, user interface;
  • Admin — protected settings: the admin password and every access-control switch (true = the interviewer may use it);
  • Project — the name, icon and colour shown in the project switcher.

The JSON is compressed with zlib, encoded as base64 and rendered as a QR code. Any setting the code omits is reset to its default when scanned, so the model keeps every field optional and serialises only what you set.

use collect_settings::{Settings, General, Admin, Project, Autosend, FormUpdateMode};

let settings = Settings {
    general: General {
        server_url: Some("https://kc.kobotoolbox.org".into()),
        username: Some("interviewer01".into()),
        password: Some("secret".into()),
        autosend: Some(Autosend::WifiAndCellular),
        form_update_mode: Some(FormUpdateMode::MatchExactly),
        automatic_update: Some(true),
        ..General::default()
    },
    admin: Admin::locked_interviewer("admin-pw"),
    project: Some(Project::new("Household survey").icon('H').color("#6b63e6")),
};

let payload = settings.encode().unwrap();           // base64(zlib(json))
let back = Settings::decode(&payload).unwrap();
assert_eq!(back.general.username.as_deref(), Some("interviewer01"));

let svg = settings.qr_svg(4).unwrap();              // ready to embed or print
assert!(svg.starts_with("<svg"));

The key names follow the current ProjectKeys / ProtectedProjectKeys of ODK Collect. Keys that were renamed between releases (save_as → save_as_draft, mark_as_finalized → finalize_in_form_entry) are emitted under both names so one code works on old and new app versions; Collect silently drops the keys it does not know.

Structs§

Admin
Protected settings: the admin password and the access-control switches. Every switch means “the interviewer may use this”: Some(false) hides it behind the admin password. An omitted key resets to true (allowed) when the code is scanned.
General
Unprotected settings. Every field is optional: an omitted key resets to the app default when the code is scanned, so set only what you mean.
Project
Name, icon and colour of the project as shown in the app’s project switcher.
QrCode
The encoded QR code symbol.
QrOptions
Rendering options for Settings::qr_svg_with.
Settings
The complete document carried by a configuration QR code.

Enums§

Autosend
When finalized forms are sent without the interviewer pressing Send.
BasemapSource
Basemap provider for geo questions.
ConstraintBehavior
When constraints are validated.
EcLevel
The error correction level. It allows the original information be recovered even if parts of the code is damaged.
Error
Errors from encoding, decoding or rendering.
FontSize
Font size of the form entry screen, in sp. Collect accepts 13, 17, 21, 25 and 29.
FormUpdateMode
How blank forms are kept in sync with the server.
GuidanceHint
Whether guidance hints are shown.
ImageSize
Downscaling applied to photos taken in the form.
Navigation
How the interviewer moves between questions.
PeriodicCheck
Interval of the background check for form updates.
Theme
App theme.

Functions§

decode
Decode a scanned payload back into Settings.
encode
Serialise, compress and encode: the exact string a QR code must carry.
encode_json
Compress and encode an already serialised JSON document.
render_svg
Render any QrCode with the given options.