butter 0.6.0

  • Readme
  • Changelog
  • Example
  • Installing
  • 78

pub package Build Status

A thin application framework for flutter making use of async_redux.

Butter allows you to structure your app into modules and submodules where each module is composed of pages, states, models and actions as already introduced by redux.

It is best to be used together with its commandline companion called butter_cli for easy scaffolding.

Using #

import 'package:butter/butter.dart';

Check out the API Reference for a more detailed information on usage.

Most common classes used to structure the app are as follows:

Concepts #

Data Flow #

Typical Flow

  1. An event occurs on the Page that triggers an action
  2. An Action is dispatched
  3. Redux causes the associated Reducer of the Action to get called
  4. The Reducer mutates the associated UI Model in the Store
  5. Redux calls the State to check if the UI Model data has actually changed
  6. If there is a significant change, redux triggers the Page to re-render with the updated UI Model data

On Initialization

  1. Process starts with the State reading the UI Model data from the Store
  2. UI Model data is passed to the Page for initial rendering

Routing #

The App object will contain a list of top level Modules. A typical Module contains a list of routes of State and Page pairs but it can also contain a list of sub-Modules. Sub-Modules can in turn nest further routes of State and Page pairs and sub-Modules depending on how complex an app structure you want to design.

Project Structure #

lib
 |
 +-- app
 |    |
 |    +-- app.dart
 |    +-- routes.dart
 |    +-- theme.dart
 |
 +-- config
 |    |
 |    +-- app_config.dart
 |    +-- ..._config.dart
 | 
 +-- data
 |    |
 |    +-- ..._model.dart
 |
 +-- modules
 |    |
 |    +-- <module-name>
 |    |    |
 |    |    +-- actions
 |    |    |    |
 |    |    |    +-- ..._action.dart
 |    |    |    +-- ...
 |    |    |
 |    |    +-- components
 |    |    |    |
 |    |    |    +-- ...dart
 |    |    |    +-- ...
 |    |    |
 |    |    +-- models
 |    |    |    |    
 |    |    |    +-- ..._model.dart
 |    |    |    +-- ...
 |    |    |
 |    |    +-- pages
 |    |    |    |
 |    |    |    +-- ..._page.dart
 |    |    |    +-- ...
 |    |    |
 |    |    +-- states
 |    |    |    |
 |    |    |    +-- ..._state.dart
 |    |    |    +-- ...
 |    |    |
 |    |    +-- <module-name>.dart
 |    |
 |    +-- <module-name>
 |
 +-- services
 |    |
 |    +-- ..._service.dart
 |
 +-- utils
 |    |
 |    +-- sub_module_page_specs.dart
 |
 +-- main.dart

Directories #

app - App specific codes

config - App configurations separated depending on purpose, such as, security, API urls, etc.

data - Data models to be used for things like API transactions

modules - All app modules

services - All services pertaining to the device api encapsulations or 3rd party api middlewares

utils - Utility codes from shared components across modules and utility libraries that doesn't qualify elsewhere

First Class Files #

main.dart

  • App boostrap code

app/app.dart

  • The main app declaration
  • Where the navigation settings are loaded

app/routes.dart

  • List of all top level modules
  • The first defined module in the list automatically gets assigned with the root route ('/')
  • See BaseRoutes class

app/theme.dart

  • App theming and branding definitions

config/app_config.dart

  • General app configurations and initial settings

Module Organization #

actions

components

  • Components that can be shared across all pages within the module

models

pages

states

<module-name.dart>

  • Root file of the module
  • Sub routing and child modules are defined here
  • See BaseModule class

Optional Files #

utils/sub_module_page_specs.dart

  • Page specs definition for sub-module data passing
  • See BasePageSpecs class

Examples #

Todo

  • demonstrates the basics of creating a single module with multiple screens
  • also shows how stateful components are constructed within a page

Submodules

References: #

0.6.0 #

  • Fix the state access error produced in BasePageState
  • Update async_redux

0.5.1 #

  • Remove unused import

0.5.0 #

  • Improve routing of submodules
  • Handled submodules via routeName configuration
  • Adapt a logger
  • Update the submodules example to comply with framework updates

0.4.0 #

  • Added type checking when retrieving data from the store
  • Defined the types of BaseRoutes.routes and BaseRoutes.defaultModule properly
  • Handled navigator routing for submodules
  • Added BuildContext to BaseStatefulPageView.beforeLoad() and beforeUpdate()
  • Fetched route objects based on either the context or the specified routeName
  • Added BaseNavigation.getRouteName()

0.3.1 #

  • Added repository to pubspec

0.3.0 #

  • Provided full documentation on the API and README
  • Defined type of BaseStatefulPageView.specs
  • Updated the definitions of beforeLoad() and beforeUpdate() of BaseStatefulPageView

0.2.5 #

  • Updated the butter logo
  • Added pub.dev and travis badges

0.2.4 #

  • Restored deleted BaseAction default constructor

0.2.3 #

  • Removed BaseDispatcher.dispatchAttribs()
  • Fixed the reduce() definition of BaseAction
  • Added docs to BaseAction and BasePageState

0.2.2 #

  • Fixed various health issues and suggestions reported by pub.dev

0.2.1 #

  • Allowed models to overwrite data in the store
  • write(), dispatchModel() and mutate() now have an overwrite parameter

0.2.0] #

  • Split BasePageView into BaseStatefulPageView and BaseStatelessPageView
  • Provided BaseStatefulPageView to support smart page loads and updates
  • Provided baseline implementation for nested modules capability
  • Allowed mother pages to retrieve elements from child pages

0.1.0 #

  • Incremented minor version due to breaking changes

0.0.3 #

  • Discontinued the use of store attributes
  • Introduced model keys
  • Properly define generic types

0.0.2 #

  • Made defaultTransition as optional in BaseRoutes

0.0.1 #

  • Initial release

example/README.md

Examples #

  • Todo example
    • demonstrates the basics of creating a single module with multiple screens
    • also shows how stateful components are constructed within a page
  • Middleware example
    • shows how an app with multiple modules looks like
    • demonstrates how submodules are constructed
    • provides the differences between a page inheriting from a BaseStatelessPageView and a BaseStatefulPageView

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  butter: ^0.6.0

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:butter/butter.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
56
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
78
Learn more about scoring.

We analyzed this package on Jul 9, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.14
  • Flutter: 1.17.5

Analysis suggestions

Package does not support Flutter platform android

Because:

  • package:butter/butter.dart that imports:
  • package:butter/src/base_routes.dart that imports:
  • package:butter/src/base_module.dart that imports:
  • package:butter/src/base_page_state.dart that imports:
  • package:butter/src/base_navigator.dart that imports:
  • package:async_redux/async_redux.dart that imports:
  • package:async_redux/src/local_persist.dart that imports:
  • package:path_provider/path_provider.dart that imports:
  • package:path_provider_linux/path_provider_linux.dart that declares support for platforms: linux

Package does not support Flutter platform ios

Because:

  • package:butter/butter.dart that imports:
  • package:butter/src/base_routes.dart that imports:
  • package:butter/src/base_module.dart that imports:
  • package:butter/src/base_page_state.dart that imports:
  • package:butter/src/base_navigator.dart that imports:
  • package:async_redux/async_redux.dart that imports:
  • package:async_redux/src/local_persist.dart that imports:
  • package:path_provider/path_provider.dart that imports:
  • package:path_provider_linux/path_provider_linux.dart that declares support for platforms: linux

Package does not support Flutter platform macos

Because:

  • package:butter/butter.dart that imports:
  • package:butter/src/base_routes.dart that imports:
  • package:butter/src/base_module.dart that imports:
  • package:butter/src/base_page_state.dart that imports:
  • package:butter/src/base_navigator.dart that imports:
  • package:async_redux/async_redux.dart that imports:
  • package:async_redux/src/local_persist.dart that imports:
  • package:path_provider/path_provider.dart that imports:
  • package:path_provider_linux/path_provider_linux.dart that declares support for platforms: linux

Package does not support Flutter platform web

Because:

  • package:butter/butter.dart that imports:
  • package:butter/src/base_routes.dart that imports:
  • package:butter/src/base_module.dart that imports:
  • package:butter/src/base_page_state.dart that imports:
  • package:butter/src/base_navigator.dart that imports:
  • package:async_redux/async_redux.dart that imports:
  • package:async_redux/src/local_persist.dart that imports:
  • package:path_provider/path_provider.dart that declares support for platforms: android, ios, linux, macos

Package does not support Flutter platform windows

Because:

  • package:butter/butter.dart that imports:
  • package:butter/src/base_routes.dart that imports:
  • package:butter/src/base_module.dart that imports:
  • package:butter/src/base_page_state.dart that imports:
  • package:butter/src/base_navigator.dart that imports:
  • package:async_redux/async_redux.dart that imports:
  • package:async_redux/src/local_persist.dart that imports:
  • package:path_provider/path_provider.dart that declares support for platforms: android, ios, linux, macos

Package not compatible with SDK dart

Because:

  • butter that is a package requiring null.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.7.0 <3.0.0
async_redux ^2.11.0 2.12.3
flutter 0.0.0
logger ^0.9.1 0.9.1
Transitive dependencies
collection 1.14.12 1.14.13
file 5.2.1
intl 0.16.1
logging 0.11.4
meta 1.1.8 1.2.1
path 1.7.0
path_provider 1.6.11
path_provider_linux 0.0.1+2
path_provider_macos 0.0.4+3
path_provider_platform_interface 1.0.2
platform 2.2.1
plugin_platform_interface 1.0.2
process 3.0.13
sky_engine 0.0.99
typed_data 1.1.6 1.2.0
vector_math 2.0.8 2.1.0-nullsafety
weak_map 1.2.1
xdg_directories 0.1.0
Dev dependencies
flutter_test