empire

Description:

empire

EMPIRE
A simple, lightweight state management library for Flutter
Features #
Less boiler plate and significantly reduced clutter in your Widget build functions than other state management solutions.
Getting Started #
In your flutter project, add the dependency to your pubspec.yaml
dependencies:
empire: ^1.2.0
copied to clipboard
Tip: Consider installing the Empire Flutter Snippets extension in Visual Studio Code to make creating Empire classes easier.
Usage #
A simple example using the classic Flutter Counter App.
counter_view_model.dart #

import 'package:empire/empire.dart';

class CounterViewModel extends EmpireViewModel {
final count = EmpireIntProperty.zero(propertyName: 'count');

void incrementCounter() {
count.increment();
}

@override
List<EmpireProperty> get empireProps => [count];
}
copied to clipboard
counter_page.dart #
import 'package:empire/empire.dart';

class CounterPage extends EmpireWidget<CounterViewModel> {
const CounterPage({super.key, required super.viewModel});

@override
EmpireState<EmpireWidget<EmpireViewModel>, CounterViewModel> createEmpire() => _CounterPageState(viewModel);
}

class _CounterPageState extends EmpireState<CounterPage, CounterViewModel> {
_CounterPageState(super.viewModel);

@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: Text('Example')),
body: Center(
child: Text('${viewModel.count}'),
),
floatingActionButton: FloatingActionButton(
onPressed: viewModel.incrementCounter,
tooltip: 'Increment',
child: const Icon(Icons.add),
),
);
}
}

copied to clipboard
main.dart #
void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
const MyApp({super.key});

@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Empire State Example',
home: CounterPage(
viewModel: CounterViewModel(),
),
);
}
}
copied to clipboard
Our business logic is clearly separated from the UI in a clean and simple way. Even in more complicated situations where, with other state management solutions, it's common to create separate classes to represent your state, with Empire this is as complicated as it gets while supporting even the most complex scenarios.
By extending EmpireWidget and EmpireState and supplying an EmpireViewModel, your UI will automatically update whenever an EmpireProperty in your view model changes.
Application Wide State Management #
What if you have application wide data that you want all your widgets to have access to at any time. Enter the Empire widget.
Create a ViewModel for your application:
application_view_model.dart #
import 'package:empire/empire.dart';

class ApplicationViewModel extends EmpireViewModel {
final loggedInUser = EmpireProperty<User?>(null);

void updateUser(User user) => loggedInUser(user);

@override
List<EmpireProperty> get empireProps => [loggedInUser];
}
copied to clipboard
Make the child of your CupertinoApp or MaterialApp an Empire widget. Supply a function to generate a unique application state id. This tells your app it needs to refresh the widget tree below your your Empire widget. In this example, we are using the Uuid package to handle creating a unique ID, but we leave it up to you to decide what dependencies you want to include in your application. This function will get called anytime the loggedInUser property is changed in the ApplicationViewModel and trigger the UI for your app to update.
main.dart #
import 'package:empire/empire.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
const MyApp({super.key});

@override
Widget build(BuildContext context) {
return MaterialApp(
home: Empire(
ApplicationViewModel(),
onAppStateChanged: () => const Uuid().v1(),
child: Builder(
builder: (context) {
final appViewModel = Empire.viewModelOf<ApplicationViewModel>(context);
final loggedInUser = appViewModel.loggedInUser;

return Column(
children: [
Text('User: ${loggedInUser}'),
TextButton(
child: Text('Update User'),
onPressed: () => appViewModel.updateUser(User('foo', 'bar')),
),
],
);
},
),
),
);
}
}
copied to clipboard
Contributing #
This is an open source project, and thus contributions to this project are welcome - please feel free to create a new issue if you encounter any problems, or submit a pull request. For community contribution guidelines, please reveiw the Code of Conduct.
If submitting a pull request, please ensure the following standards are met:


Code files must be well formatted (run flutter format .).


Tests must pass (run flutter test). New test cases to validate your changes are highly recommended.


Implementations must not add any project dependencies.


Project must contain zero warnings. Running flutter analyze must return zero issues.


Ensure docstrings are kept up-to-date. New feature additions must include docstrings.


Additional information #
This package has ZERO dependencies on any other packages.
You can find the full API documentation here
Developed by:
© 2022 Strive Business Solutions