Theme images
A theme can name images: the background image, the images of single screens, and image tokens you read in Dart. All use the same map. An image is either an asset of the app or a file from the network. Network images are downloaded in the background, kept in a cache that survives restarts, checked against a SHA-256 digest if you give one, and refreshed when you ask.
spring:
flutter:
theme:
background:
image:
source: https://cdn.example.com/neon/background.jpg
refresh: 1d
source-sha256: 9f2c1a5e7b2d4a6f8c0e1b3d5f7a9c2e4b6d8f0a1c3e5b7d9f1a3c5e7b9d1f3a
headers:
Authorization: Bearer ${cdn.token}
timeout: 10s
fallback: assets/images/background.jpg
tokens:
brand:
hero:
source: https://cdn.example.com/hero.png
refresh: 1d
Properties
| Property | Type | Values | Default | What it does |
|---|---|---|---|---|
source |
text | an asset path, an https:// URL, a github:owner/repo/path@ref address |
required | Where the image is. A path with no scheme (and a Windows drive such as C:) is an asset; an address is downloaded. http:// stops the start unless spring.remote.allow-insecure is true (see insecure connections). Any other scheme stops the start |
refresh |
duration | 30m, 12h, 1.5d |
none | How old the cache may get before the file is looked at again in the background. Without it the first download is kept for ever and there is never another request |
source-sha256 |
text | 64 hexadecimal digits | none | The file must have exactly this digest. Any other file is refused |
headers |
map | header name to value | none | Request headers, such as Authorization. ${...} placeholders are resolved by the application's configuration. Header names keep their spelling |
timeout |
duration | 10s, 1m |
10s |
The longest a download may take |
fallback |
text | an asset path | none | An asset shown while a network image is not there yet |
Durations here are the same as everywhere in a theme: a number (decimals
allowed) with a unit (ms, s, m, h, d), like 1.5s or 0.5d. A
plain number is milliseconds. ISO-8601 (PT1H30M) is not accepted.
In a background image these keys sit next to
fit, alignment, opacity and blur. Any other key stops the start and
lists the valid ones.
References ($colors.primary) are not resolved in source, fallback,
source-sha256 or headers, so a $ in a secret that came from a placeholder
stays exactly as it is. See tokens and references.
What is shown, and when
The start never waits for the network.
| Situation | What the app shows |
|---|---|
| An asset | The asset, at once |
| A network image with a cache | The cached image, at once |
A network image without a cache, with a fallback |
The fallback; the download runs in the background and the image replaces it when it arrives |
| A network image without a cache and without a fallback | Nothing; for a background, its color |
When a download ends, the new image fades in (for a background, over its
transition).
Downloads and the cache
- Where. The cache is in the app's
supportfiles place, inspring/images/<sha256 of source and digest>/(imageandmeta.json). It survives restarts. In a browser it is in IndexedDB. The folder belongs to the source and the digest, so a changedsourceorsource-sha256downloads again. Images that are no longer in any theme are removed at start. Two themes that name the same image share one download. - First start. No cache means a download in the background, once. The
request asks for
image/*. - Refresh. With
refresh, a cache that is older than that is read again in the background, withIf-None-MatchandIf-Modified-Since. A304only renews the age. A new file is swapped in as soon as it arrives. If a download fails, it is tried again after the refresh time, but not later than five minutes. - Digest. A downloaded file with a different SHA-256 is refused and the image on screen stays. A cached file that does not match is dropped with a warning.
- Limits. A file may be 20 MiB at most; an empty answer is an error.
- Failures. Offline, a timeout, a wrong digest or a file that is too big keep what is shown, and write a warning to the log.
- Redirects. A redirect to another host drops your custom
headers, so a token is not sent to a stranger. - On the web the server must allow your origin with CORS headers
(
Access-Control-Allow-Origin). If a download fails there, the log says so.
Image tokens
A token that is a map with a source and only the keys of the table above
is an image. A map with another key next to source is a group of tokens.
The image sits at least at tokens.<group>.<key>.
spring:
flutter:
theme:
tokens:
neon:
hero: { source: https://cdn.example.com/hero.png, refresh: 1d }
logo: { source: assets/images/logo.png }
final hero = context.theme.tokens.neon.hero; // a ThemeImage
ValueListenableBuilder(
valueListenable: hero.listenable,
builder: (context, provider, _) =>
provider == null ? const SizedBox() : Image(image: provider),
);
ThemeImage.provider is the image to paint now (null while a network image
has neither a cache nor a fallback), and listenable notifies when a download
arrives or is refreshed. theme.tokenImage('neon.hero') reads the same image
without the generator.
Errors
A wrong value stops the start and names the property, for example
tokens.neon.hero.source-sha256 with "must be 64 hexadecimal digits". An
http:// source stops the start with "the connection is not secure", naming
the address and its property, unless spring.remote.allow-insecure is
true. A missing source is an error too: every image needs one.
See also
- Background
- Tokens and references
- Properties: a whole theme from a URL