simply 6.0.0

Flutter made simple, Simply is a light-weight package for creating production-ready applications easily and quickly.

Simply

Motivation

Simply is built to help creating production-ready flutter applications faster and easier, it handles topics such as dependency injection as well as state management and let you focus on creating beautiful UIs (the main purpose of flutter).

Normal flutter application could look like the following:

void main(){
    runApp(MyApp());
}

class MyApp extends StatelessWidget{
    @override
    Widget build(BuildContext context) {
        //All code goes here!
    }
}

But this leaves us with too many logic to handle inside the app class specially as the code grows more and more, for example:

• Execute asynchronous operations, like initialize database, log something to a remote API or intializes Firebase.
• Rebuild the whole app when the user changes the language or the theme.
• ...

Eventually this will lead to a mess inside that MyApp class handling both UI logic and initialization logic, what Simply does is that it helps you organize your app better.

---

Getting started

All what you need to start is to use the SimpleMaterialApp class which is nothing more than a StatelessWidget that helps organizing your app.

The following is the simplest working app:

import 'package:simply/simply.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends SimpleMaterialApp {
  @override
  Future<void> initialize() async {}
  
  @override
  MaterialApp buildApp(String payload, GlobalKey<NavigatorState> navigatorKey) => MaterialApp(body: SomePage());

  @override
  Widget splashPage() => SimpleSplashPage();

  @override
  Widget startupErrorPage(String errorMessage) => SimpleStartupErrorPage(errorMessage);
}

There are 4 main methods to be overridden:

• initialize (optional) this method handles two main functionalities:
  1. Inject all the dependencies that your UIs/views will need (to be explained below).
  2. Execute all the time-consuming functionalities that needs to be called at the start of your app like preparing database, or connecting to remote API.
• buildApp this corresponds to the normal build method in normal StatelessWidgets with main differences that it's called each time the app is reloaded not just once (to be explained below)
• splashPage this is a screen that the user can see while your time-consuming functionalities take place, you can use SimpleSplashPage if you don't want to implement custom splash page or if you don't have any time consuming functionalities.
• startupErrorPage in case any initialization error takes place, this is what the user will see, you can always use SimpleStartupErrorPage if you don't want to implement custom page for that.

---

Dependency Injection

Simply allows injection dependencies at the startup of the application and accessing them easily at any other location.

Assume we have a dependency on a certain repository responsible for fetching data from some storage, let's call it IMenuItemsRepository, we just need it to extend the SimpleService class to be able to inject it to distinguish the services from other types.

abstract class IMenuItemsRepository extends SimpleService {
    Future<List<String>> getMenuItemNames();
}

All what you have to do is to inject the concrete implementation of this dependency from the app level, let's say you have a class called LocalMenuItemsRepository

class MyApp extends SimpleMaterialApp {
  @override
  Future<void> initialize() async {
    Simply.register<IMenuItemsRepository>(
        service: LocalMenuItemsRepository(),
    );
  }
  // ...
}

Then use the Simply to get the dependency from anywhere in the UI (it will be passed to the whole tree).

@override
Widget build(BuildContext context) {
    var menuItemsRepo = Simply.get<IMenuItemsRepository>(context);
    // Use the dependency ..
}

This way you will keep your UI logic clean and decoupled from any implementation details.

Also if you want to call time-consuming functionalities, you can do it within the same method, while users enjoy your SplashPage

class MyApp extends SimpleMaterialApp {
  @override
  Future<void> initialize() async {
    await Firebase.initialize();
    await SharedPrefernces.initialize();
    await prepareLocalDatabase();
    // ...
  }
}

---

Reloading the app

You might want to reload the app for a global event like changing the language or the theme, you can do this easily from anywhere in the code as follows:

Simply.reload("Theme changed");

This will cause the whole app to be rebuilt and the method buildApp will be called with the parameter payload carrying whatever message you sent and also with passing the same service providers that you have previously registered.

class MyApp extends SimpleMaterialApp {
  @override
  MaterialApp buildApp(String payload) {
    IThemeService themeService = Simply.get<IThemeService>();
    return CustomMaterialApp(
      widget: const HomePage(),
      theme: themeService.currentTheme,
    );
  } 
}

---

Navigation

Simply provides navigation methods similar to the native one just to make sure that whatever dependencies are passed properly while navigation, the only difference is that it takes the widget directly instead of taking the MaterialPageRoute

Simply.navPush(view: TargetPage());
Simply.navReplace(view: TargetPage());
Simply.navPop();
Simply.navigator;

---

Advanced Topics

Injection Lifecycle

Simply supports two types of dependency injection techniques:

• scoped (default) new instance to be created per call.
• singleton same instance to be injected once and forever.

By default injection will be scoped, meaning that new instance from the injected service will be created each time it's requested from the service provider.
If you want to switch to the singleton injection method to inject specific instance from the service once and forever, use the following code:

class MyApp extends SimpleMaterialApp {
  @override
  Future<void> initialize() async {
    registry.register<IMenuItemsRepository>(
        service: LocalMenuItemsRepository(),
        method: InjectionMethod.singleton,
    );
  }
  // ...
}