ModelMate

ModelMate is a lightweight, easy-to-use state management library for Flutter applications. It provides a simple and intuitive way to manage reactive models and observable properties, making it easier to build responsive and maintainable apps.

Table of Contents

Getting Started

Installation

Add model_mate to your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  model_mate: ^0.0.1

Then, run:

flutter pub get

Importing

Import model_mate in your Dart code:

import 'package:model_mate/model_mate.dart';

Usage

ReactiveModel

Create a class that extends ReactiveModel and define your observable properties:

import 'package:model_mate/model_mate.dart';

class CounterModel extends ReactiveModel {
  CounterModel(int initialCount) {
    count = observable(initialCount);
  }

  late final ObservableProperty<int> count;

  void increment() {
    count.value += 1;
  }

  void decrement() {
    count.value -= 1;
  }
}

ModelMateProvider

Wrap your application with ModelMateProvider to make your models available throughout the widget tree:

void main() {
  runApp(
    ModelMateProvider(
      models: [
        CounterModel(0),
        // Add other models here
      ],
      child: const MyApp(),
    ),
  );
}

ModelMateConsumer

Use ModelMateConsumer to access your models in the widget tree:

class CounterPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ModelMateConsumer<CounterModel>(
      builder: (context, counterModel) {
        return Scaffold(
          appBar: AppBar(title: const Text('Counter')),
          body: Center(
            child: Text('Count: ${counterModel.count.value}'),
          ),
          floatingActionButton: Column(
            mainAxisAlignment: MainAxisAlignment.end,
            children: [
              FloatingActionButton(
                onPressed: counterModel.increment,
                child: const Icon(Icons.add),
              ),
              const SizedBox(height: 10),
              FloatingActionButton(
                onPressed: counterModel.decrement,
                child: const Icon(Icons.remove),
              ),
            ],
          ),
        );
      },
    );
  }
}

ObservableProperty

ObservableProperty

class MyModel extends ReactiveModel {
  MyModel() {
    name = observable('Initial Name');
  }

  late final ObservableProperty<String> name;

  void updateName(String newName) {
    name.value = newName;
  }
}

ModelState

ModelMate provides built-in support for handling different states of your models:

  • LoadingState: Indicates that the model is loading data.
  • DataState: Indicates that the model has loaded data successfully.
  • ErrorState: Indicates that an error occurred while loading data.

You can update the state of your model using:

class MyModel extends ReactiveModel {
  Future<void> fetchData() async {
    setLoading(); // Set state to LoadingState
    try {
      // Perform data fetching
      setLoading(val: false); // Set state back to DataState
    } catch (error) {
      setError(error); // Set state to ErrorState
    }
  }
}

In your UI, you can handle different states:

ModelMateConsumer<MyModel>(
  builder: (context, model) {
    switch (model.state) {
      case LoadingState():
        return CircularProgressIndicator();
      case ErrorState(error: var error):
        return Text('Error: $error');
      case DataState():
        return Text('Data Loaded');
      default:
        return Container();
    }
  },
);

Examples

Check out the example directory for a complete sample app using ModelMate.

To run the example:

cd example
flutter run

Contributing

We welcome contributions from the community! Please read the following guidelines before contributing.

Code of Conduct

We expect all contributors to abide by our Code of Conduct. Please read it to understand the standards of behavior we expect from contributors.

How to Contribute

Fork the Repository: Click the "Fork" button at the top right corner of the repository page.

Clone Your Fork:

git clone https://github.com/yourusername/model_mate.git

Create a Branch:

Copy code
git checkout -b feature/your-feature-name

Make Your Changes: Implement your feature or fix the issue.

Write Tests: Ensure that your changes are covered by tests.

Run Tests:

flutter test

Commit Your Changes:

git commit -am 'Add your commit message here'

Push to Your Fork:

git push origin feature/your-feature-name

Create a Pull Request: Go to the original repository and create a pull request from your fork.

Wait for Review: We'll review your pull request and provide feedback.

License

ModelMate is released under the MIT License.

Acknowledgments

Thanks to all the contributors who have helped make ModelMate better. Inspired by the simplicity of state management in Flutter.

Libraries

model_mate
Model mate library.