The app widget
With home:, SpringApplicationWidget puts a SpringApp at the root: a WidgetsApp, or with a design starter a MaterialApp or CupertinoApp, set up by properties instead of code. Its type, title, debug banner and locales come from spring.flutter.app.*, its themes from spring.flutter.theme.*. The properties can differ per profile, so iPhones can get a CupertinoApp while the other platforms get a MaterialApp.
Why
An app widget is mostly settings: a title, the locales, a theme and a dark theme, observers. Written in Dart, they must be kept in step with the message files and the themes by hand. From properties, the locales follow the message files, the theme follows the theme files, and a platform or a build changes them by file name.
Example
Material on most platforms and Cupertino on iPhones: the app lists both design starters and their libraries. With two design starters it chooses the type, for every platform and again in the iOS profile (see The type when not set); an app with one design starter leaves type out.
# pubspec.yaml
dependencies:
material_ui: ^1.11.0
cupertino_ui: ^1.1.6
spring_boot_starter_flutter_material: ^0.9.0
spring_boot_starter_flutter_cupertino: ^0.9.0
# lib/resources/application.yml
spring:
flutter:
app:
type: material
title: NEON Books
description: The bookshop of the NEON district.
debug-banner: false
locales: en, ja, pt_BR
# lib/resources/application-ios.yml: the iOS look on iPhones
spring:
flutter:
app:
type: cupertino
@SpringBootApplication()
void main() => runApp(
SpringApplicationWidget(
application: () => springApplication,
home: const BookListPage(), // a MaterialApp, or a CupertinoApp on iOS
),
);
The properties
| Key | Type | Default | Meaning |
|---|---|---|---|
spring.flutter.app.type |
text: widgets, material, cupertino, or the type of an app factory of your own |
not set: the one design starter's type (material, cupertino), else widgets; with several, required |
The app widget: WidgetsApp (this starter's own, no design library), MaterialApp (needs spring_boot_starter_flutter_material; needed by Scaffold, AppBar and the other Material widgets) or CupertinoApp (needs spring_boot_starter_flutter_cupertino). See App factories |
spring.flutter.app.title |
text | empty | The app's name for the OS: the task switcher, the browser tab. The web build also writes it into web/index.html (<title>) and web/manifest.json (name, short_name) |
spring.flutter.app.description |
text | none | What the app is, in a sentence. Not used at run time: the web build writes it into web/index.html (<meta name="description">) and web/manifest.json |
spring.flutter.app.debug-banner |
true, false |
true |
Flutter's DEBUG banner in debug builds |
spring.flutter.app.locales |
comma-separated language tags (en, pt_BR, zh_Hant_TW) |
the languages of the message files | The locales the app supports |
Write locales as one comma-separated value, also in YAML (locales: en, ja). The app widget reads it as a single value, so a YAML list ([en, ja]) is not seen; the locales then come from the message files.
The type when not set
spring.flutter.app.type need not be set. As Spring Boot deduces spring.main.web-application-type from the class path, the application's starters decide:
| The application has | The app is |
|---|---|
| no design starter | widgets, a WidgetsApp |
one design starter: spring_boot_starter_flutter_material or spring_boot_starter_flutter_cupertino |
material or cupertino |
one SpringAppFactory bean of its own type (ocean, see App factories) |
that type |
| app factories of several types, both design starters for instance | none: the start fails and asks for the property |
With several, the failure report names the property and the types:
Invalid argument(s) (spring.flutter.app.type): not set, and the application has app widgets of several types: cupertino, material. Choose one, for every platform or in a profile of each (spring.flutter.app.type=cupertino in application-ios.properties)
Set, the property always wins: widgets keeps a WidgetsApp although a design starter came in through another package, and an app that sets its type is not changed by a starter it adds.
Locales
By default the app supports the languages it has texts for: messages.properties counts as English, and each messages_<locale>.properties adds its locale (messages_ja adds ja, messages_pt_BR adds pt_BR). So the app's locales and context.message agree. With other files than messages*.properties, set spring.messages.basename as one comma-separated value with / as the separator (i18n/messages,i18n/errors), and the starter looks for the locales of those files.
Flutter's own translations for the app type (the texts of its widgets, in every language) are added by the type's app factory (SpringAppFactory.localizationsDelegates): GlobalWidgetsLocalizations for widgets; the Material starter's factory adds Material's (GlobalMaterialLocalizations), the Cupertino starter's Cupertino's (GlobalCupertinoLocalizations). flutter_localizations comes with the starter. See Messages and languages.
The theme
The theme shown is the one the ThemeSelection bean picks. widgets gets the theme's text style and color. With the Material starter, material gets the Material ThemeData of the theme shown (and its dark counterpart for system); with the Cupertino starter, cupertino gets the CupertinoThemeData. A theme picked at run time, or loaded from a server, shows at once. A SpringTheme above the app gives the theme to the app's own widgets. See Themes.
Navigator observers
Every NavigatorObserver bean becomes an observer of the app's navigator, in @Order:
// Logs every screen the user opens.
@Component()
@Log()
class ScreenLog extends NavigatorObserver {
@override
void didPush(Route<dynamic> route, Route<dynamic>? previousRoute) =>
log.info('Opened ${route.settings.name}');
}
FlutterAppCustomizer
What no property covers is changed by a FlutterAppCustomizer bean: a builder, keyboard shortcuts, the scrollBehavior, the app's own localization delegates. Each one gets the FlutterAppSettings once, before the app widget is first built, in @Order:
// The app's own translations, and text that never grows past 130 %.
@Component()
class AppLocalizations implements FlutterAppCustomizer {
@override
void customize(FlutterAppSettings app) {
app.localizationsDelegates.add(LegalTerms.delegate);
app.builder = (context, child) => MediaQuery.withClampedTextScaling(
maxScaleFactor: 1.3,
child: child!,
);
}
}
The fields of FlutterAppSettings:
| Field | From | Meaning |
|---|---|---|
type |
spring.flutter.app.type, or when not set the type the starters decide on |
The type of the app factory that builds the app widget, a String (widgets, material, cupertino) |
title |
spring.flutter.app.title |
The app's name for the OS |
debugShowCheckedModeBanner |
spring.flutter.app.debug-banner |
The DEBUG banner |
supportedLocales |
spring.flutter.app.locales or the message files |
The app's locales |
localizationsDelegates |
the app factory's (Flutter's for the type) | Add the app's own here |
navigatorObservers |
the NavigatorObserver beans |
The navigator's observers |
builder |
null |
Wraps the navigator, like MaterialApp.builder |
scrollBehavior |
null |
The app's scroll behavior (not used by a WidgetsApp) |
shortcuts |
null |
The app's keyboard shortcuts in Flutter's form; for actions in the configuration, see Keyboard shortcuts |
The starter uses customizers itself: the keyboard shortcuts and the debug panel are installed around the navigator that way. Spring Boot (Java) customizes its web server the same way, with a WebServerFactoryCustomizer bean.
Routes
home is the first page, and the app navigates with Navigator. Without home, SpringApp builds the router form of the app widget (WidgetsApp.router, or MaterialApp.router and CupertinoApp.router of the design starters) on the application's RouterConfig<Object> bean: the one spring_boot_starter_flutter_navigation adds, or the app's own.
App factories
spring.flutter.app.type is a text: the type of a SpringAppFactory bean, which builds the app widget. Types are compared without case.
| Type | App factory | From |
|---|---|---|
widgets |
WidgetsAppFactory |
spring_boot_starter_flutter (its own) |
material |
MaterialAppFactory (bean materialAppFactory) |
spring_boot_starter_flutter_material |
cupertino |
CupertinoAppFactory (bean cupertinoAppFactory) |
spring_boot_starter_flutter_cupertino |
A design of your own is one more bean:
// An app widget of the company's own design system.
@Component()
class OceanAppFactory implements SpringAppFactory {
@override
String get type => 'ocean';
@override
List<LocalizationsDelegate<Object?>> get localizationsDelegates =>
const [GlobalWidgetsLocalizations.delegate];
@override
Widget build(BuildContext context, SpringAppRequest app) =>
OceanApp(title: app.settings.title, home: app.home);
}
spring.flutter.app.type: ocean then builds an OceanApp; without a design starter in the application, the type need not be set, as the one factory of its own decides. The SpringAppRequest has the settings, the themes, the theme selection, the theme shown, the builder to pass on as it is, and home or the router. See Design libraries.
Checked at the start
The settings are made once per context, when the application starts. An invalid value (debug-banner=maybe) fails the start with the failure report, naming the property. So does a type no app factory has: material or cupertino without its starter names the starter to add (the app widget of type material is built by spring_boot_starter_flutter_material: add it to the dependencies (this application has: widgets)), any other type lists the known ones (type=swing: one of: widgets).
With your own app widget
With SpringApplicationWidget(child: ...) you write your own app widget, and these keys are not used. In widget tests, put a SpringApp under a SpringScope to get the app widget of the properties (see Testing).