elementary-team / flutter-elementary

This is a home to a family of Elementary library packages.

Flutter Elementary repository

Description

This repository is a home to packages and tools from the Elementary library family.

Package	Version
elementary
elementary_helper
elementary_test
elementary_cli

Elementary overview

Elementary is a simple and reliable way to build applications with MVVM in Flutter. Benefits from using:

• maximum Flutter-like, you don't need to spend a lot of time learning the library if you are already familiar with the standard Flutter approaches;
• splitting code into different layers by responsibility, that bring low coupling, make code simpler as well as more readable;
• high testability of all layers from widgets to business logic;
• speed boost for a team consisting of more than one person, due to the easy sharing of independent task-parts among team members.

Environment

For reduce amount of boilerplate and the manual work, for Elementary there are few options:

• elementary_cli - command line util helps with boilerplate generation;
• plugin for IntelliJ - plugin for IntelliJ IDE family, based on elementary_cli;
• plugin for VSCode - plugin for VSCode, based on elementary_cli;
• elementary brick - command line util helps with boilerplate generation, based on mason.

Examples

Country - general example how to use elementary for development;

Elementary with Redux - example how to use elementary + redux;

Profile - example shows the feature with the process that spread by separate screens, and also how to use elementary + bloc;

Maintainer

Mikhail Zotyev

Contributors thanks

Big thanks to all these people, who put their effort to help the project.

Special thanks to:

Dmitry Krutskikh, Konoshenko Vlad, Denis Grafov for the early adoption and the first production feedback;

Alex Bukin for IDE plugins;

All members of the Surf Flutter Team for actively using and providing feedback.

Sponsorship

Special sponsor of the project:

For all questions regarding sponsorship/collaboration connect with Mikhail Zotyev.

flutter-elementary's Issues

Idea plugin doesn't compatible with IntelliJ IDEA 2021.3

Hello!
Jetbrain's marketplace shows 'Not compatible with the version of your running IDE (IntelliJ IDEA 2021.3)'
Compatibility range 2020.3 — 2021.2.4

https://plugins.jetbrains.com/plugin/18099-elementary

using TickerProviderStateMixin

in MVVM model as this library how can i implement TickerProviderStateMixin or SingleTickerProviderStateMixin the same as StatefulWidget? i know i can separate part of code as a simple class but i want to use in main class

Create quick start guideline

Create a guideline with steps to follow those, a newbie can easier start to use Elementary.

WidgetModel Tests fail on Flutter 3.10 - NoSuchMethodError: has no instance setter '_wmHandler='

Steps to reproduce

1. Create basic ElementaryModel - WidgetModel - ElementaryWidget.
2. Create test for WidgetModel.
3. Invoke tester.init() in testFunction inside testWidgetModel.

Expected result

Tests will not fail.

Actual result

Tests will fail with error:

NoSuchMethodError: Class 'ExampleModelMock' has no instance setter '_wmHandler='.

Receiver: Instance of 'ExampleModelMock'

Tried calling: _wmHandler=Closure: (Object) => void from Function 'onErrorHandle':.

Screenshot

Code example

import 'package:elementary/elementary.dart';
import 'package:elementary_test/elementary_test.dart';
import 'package:flutter/material.dart';
import 'package:mocktail/mocktail.dart';

class ExampleModel extends ElementaryModel {}

class ExampleWidget extends ElementaryWidget<IExampleWidgetModel> {
  const ExampleWidget({
    Key? key,
    WidgetModelFactory wmFactory = defaultExampleWidgetModelFactory,
  }) : super(wmFactory, key: key);

  @override
  Widget build(IExampleWidgetModel wm) {
    return Container();
  }
}

abstract class IExampleWidgetModel extends IWidgetModel {}

ExampleWidgetModel defaultExampleWidgetModelFactory(BuildContext context) {
  return ExampleWidgetModel(ExampleModel());
}

class ExampleWidgetModel extends WidgetModel<ExampleWidget, ExampleModel>
    implements IExampleWidgetModel {
  ExampleWidgetModel(ExampleModel model) : super(model);
}

/// Тесты для [ExampleWidgetModel]
void main() {
  late ExampleModelMock model;

  ExampleWidgetModel setUpWm() {
    model = ExampleModelMock();
    return ExampleWidgetModel(model);
  }

  testWidgetModel<ExampleWidgetModel, ExampleWidget>(
    'myfirsttestcase',
    setUpWm,
    (wm, tester, context) {
      tester.init();
    },
  );

  testWidgetModel<ExampleWidgetModel, ExampleWidget>(
    'mysecondtestcase',
    setUpWm,
    (wm, tester, context) {
      tester.init();
    },
  );
}

class ExampleModelMock extends Mock implements ExampleModel {}

why screen referensed again in Country sample?

in CountryListScreen class we have countryListScreenWidgetModelFactory as a Factory

flutter-elementary/examples/country/lib/ui/screen/country_list_screen/country_list_screen.dart

Line 10 in a61d1c8

WidgetModelFactory wmFactory = countryListScreenWidgetModelFactory,

and into that we have CountryListScreenWidgetModel class

flutter-elementary/examples/country/lib/ui/screen/country_list_screen/country_list_screen_widget_model.dart

Line 16 in a61d1c8

return CountryListScreenWidgetModel(model, theme);

and in this class CountryListScreenWidgetModel extends again screen as CountryListScreen

i can't understand why we should extend screen again

when initWidgetModel() initializing?

in this code i pasted my simplified MVVM which in that i defined width, but in widget i get

LateInitializationError: Field '_width@234398598' has not been initialized.

error and i'm not sure how can i resolve that

class ManageAddressesWidgetModel extends ...{

  late double _width;

  @override
  double get width => _width;

  @override
  void initWidgetModel() {
    super.initWidgetModel();
    Future.microtask(() => _width = context.size!.width);
  }
}

abstract interface class IManageAddressesWidgetModel implements IWidgetModel {
  double get width;
}

Passing arguments in widgets

Hello everyone.

I have a question, is it possible to implement a function to pass arguments to screens?

Now I can pass at the Widget stage, but not with the MWWM or Model constructor.
I need to interact with the data in initState, but it's only in MWWM.

Thanks!

Passing wm inside child widgets?

I have ElementaryWidget that contains Scaffold inside it and I decided to spread Scaffold into AppBar, Body and Bottom classes like this:

< some  other imports … >

part 'widgets/chat_page_app_bar.dart';
part 'widgets/chat_page_body.dart';
part 'widgets/chat_page_bottom_bar.dart';

class ChatPageWidget extends ElementaryWidget<IChatPageWidgetModel> {
  final String title;

  const ChatPageWidget({
    Key? key,
    this.title = 'Чат с диспетчером',
    WidgetModelFactory wmFactory = defaultChatPageWidgetModelFactory,
  }) : super(wmFactory, key: key);

  @override
  Widget build(IChatPageWidgetModel wm) {
    return GestureDetector(
        onTap: wm.onTapOutsideMessageTextField,
        child: Scaffold(
          resizeToAvoidBottomInset: true,
          appBar: ChatPageAppBar(title: title),
          body: Column(
            children: [
              Expanded(
                  child: ChatPageBody(
                wmFactory,
              )),
              ChatPageBottomBar(wmFactory)
            ],
          ),
        ));
  }
}

These parts extends Elementary Widget as well. Of course, I faced with issue when new Widget Model instance creates each time instead of using the same instance created in parent ChatPageWidget. I could convert parts to simple Stateless widgets and pass wm variable in their constructors but in this case I have access to context leaks to its build method that breaking single source of truth of WidgetModel.

Is there way to keep AppBar, Body and BottomBar widgets as ElementaryWidgets with build(IChatPageWidgetModel wm) function instead of build(BuildContext context) one?

change CountryListScreenModel to use injected CountryRepository

in Country sample code we have this implementation into main.dart:

_http = Dio();
_defaultErrorHandler = DefaultErrorHandler();
_countryClient = CountryClient(_http);
_countryRepository = CountryRepository(_countryClient);

and ower country_client.dart class is:

@RestApi()
abstract class CountryClient {
  factory CountryClient(Dio dio, {String baseUrl}) = _CountryClient;

  /// Получение списка адресов пользователя
  @GET(AppUrls.all)
  Future<List<CountryData>> getAll();
}

and providers is:

return MultiProvider(
    providers: [
      Provider<CountryListScreenModel>(
        create: (_) => _countryListScreenModel,
      ),
      Provider<ThemeWrapper>(
        create: (_) => _themeWrapper,
      ),
    ],
    child: widget.app,
);

i want to use _countryClient the same as DI with Provider and my problem is when i try to define country_client.dart to use that with ProxyProvider, my CountryListScreenModel class of mine no longer have a constructor parameter named _countryRepository

my RestClient class:

const String _baseApiUrl = 'https://restcountries.com/v3.1';

@RestApi(baseUrl: _baseApiUrl)
abstract class RestClient {
  factory RestClient(Dio dio, {String baseUrl}) = _RestClient;

  @GET('$_baseApiUrl/all')
  Future<List<CountryData>> getAll();

  static RestClient create() {
    final BaseOptions options = BaseOptions(
      connectTimeout:const Duration(seconds: 3000),
      receiveTimeout: const Duration(seconds: 3000),
    );

    /* ... */
    return _RestClient(dio);
  }
}

my rest_client provider:

Provider(
  create: (_) => RestClient.create(),
),

i defined CountryRepository class with ProxyProvider to use RestClient which is defined as above, contrary to what you have defined in the code.

my code:

ProxyProvider<RestClient, CountryRepository>(
  update: (context, api, viewModel) => CountryRepository(restApi: api),
),

your code:

_http = Dio();
_countryClient = CountryClient(_http);
_countryRepository = CountryRepository(_countryClient);

now how can i define CountryListScreenModel with ProxyProvider or other provider to use getAllCountries() function of that? because i don't have implementation the same as :

_countryListScreenModel = CountryListScreenModel(
  _countryRepository,
  _defaultErrorHandler,
);

how can i define CountryRepository into provider such as ProxyProvider to use that into CountryListScreenModel class?

👉👉👉UPDATED GITHUB REPOSITORY👈👈👈

Proposal for the amendment of the documentation

Hello!
Could you please add to docs the information that properties of the UI layer can be accessed inside the WidgetModel when called through the widget getter. I found it difficult to figure this out.
Thanks in advance!