Framy
A convenient code generator for app styleguide, gallery, wireframes and/or storyboard.
👉 Official documentation 👈
Packages
In order to use Framy, you will need two following packages:
- framy_annotation - A package containing annotation classes.
- framy_generator - A powerful code generator which creates whole application based on the annotations used.
Examples
Idea
The idea behind Framy is to allow developers, designers, testers, managers and clients to easily access the components used in the Flutter app.
Framy is annotation-driven tool based on which you can generate:
- a style guide describing the theme of your app
- a component gallery showing the widgets you have written in out-of-context way
- a playground for testing widgets with a variety of dependencies
- and much more coming soon...
What makes Framy special?
- Fully responsive
- The generated application is mobile, tablet, desktop and web friendly. Framy generates a separate main file with a separate MaterialApp but it does use the same widgets you are using in your own Flutter app.
- Standalone
- You can easily host generated app the way you prefer or just run it locally. (Automated hosting of Framy App is planned as well 😉)
- Non-invasive
- Framy doesn't require using any special widgets to be working. There is no
Framy widget to wrap your app in so it doesn't affect your actual product. Only annotations.
Installation
Get packages
To use Framy, you will need your typical build_runner/code-generator setup.
First, install build_runner and Framy by adding them to your pubspec.yaml file:
dependencies:
framy_annotation:
dev_dependencies:
build_runner:
framy_generator:
Add the @FramyApp annotation
@FramyApp annotation is coming from framy_annotations package. It's only purpose is to specify where the Framy app should be generated. Without this, the generator will not work. There should be only one @FramyApp annotation for the project.
@FramyApp()
class MyApp extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(...);
}
}
Run the generator
You can either run
flutter pub run build_runner build to generate the app from the current code or flutter pub run build_runner watch to keep listening to changes in the source code and update the Framy app accordingly.
Run the generated app
Generator creates a new main file. Run flutter run lib/main.app.framy.dart to use Framy!
Annotations
Framy Annotations package offers a variety of annotations to generate the widest variety of pages in your Framy App.
FramyTheme
FramyTheme points out the ThemeData used in the Flutter application.
Using with ThemeData method or field
Since Framy uses the same widgets you do, it should use the same Theme as well. Use FramyTheme annotations to specify the Theme you are using. Based on that, Framy will generate your typography and color palette as well as it will use that theme for any other widget in the catalog.
@FramyTheme()
ThemeData getThemeData() => ThemeData(primarySwatch: Colors.orange);
Method annotated with FramyTheme must be public (available to use from outside the file)!
Using with custom theme class
Alternatively, you can use FramyTheme annotation with your own Theme class. If you have any colors (methods, fields, getters) defined in a class annotated with FramyTheme they will also be used in your color palette.
@FramyTheme()
class AppTheme {
static ThemeData get getTheme => ThemeData(primarySwatch: Colors.orange);
Color get myAppBlack => Colors.black;
static const myCompanyColorWhite = Color(0xFFFEFEFE);
}
There can be only one ThemeData accessor annotated in a project
FramyWidget
Annotate your Widget classes to include them in the gallery.
Framy will generate a dependencies panel which will allow the user to pass any parameters that are defined in the Widget's constructor.
@FramyWidget()
class CounterTitle extends StatelessWidget {
final String verb;
final int counter;
const CounterTitle({this.verb = 'pushed', this.counter = 0});
@override
Widget build(BuildContext context) {
return Column(
key: Key('Counter title'),
mainAxisAlignment: MainAxisAlignment.center,
children: <Widget>[
Text('You have $verb the button this many times:'),
Text('$counter', style: Theme.of(context).textTheme.headline4),
],
);
}
}
FramyModel
Annotate your model classes to pass more complex parameters to your widgets
FramyWidget's constructor dependencies support by default only primitive types. In many cases you will pass a custom object instead of String or int. If you want to add an option to change custom dependencies, use FramyModel annotation with your model class.
@FramyModel()
class User {
final String firstName;
final String lastName;
final int age;
final List<String> emails;
User(this.firstName, this.lastName, this.age, {this.emails});
}
You can annotate enums the same way:
@FramyModel()
enum Gender {female, male, other}
If your class uses other custom classes (e.g. Address in User), the subclasses have to be annotated with @framyModel as well
FramyPreset
Define dependency presets to speed up testing parameters to your widgets
In cases when your models have a lot of dependencies and it would be a big hustle to click them all through, you can define a preset object models which will be accessible in dependencies panel.
@FramyPreset()
User teenageJohn() => User('John', 'Smith', 13);
Since presets will be part of your normal source code, we recommend having them in a separate file, e.g. for User presets file user.framy.dart would do. :)
FramyUseProvider
If your widget dependency is passed by Provider and not constructor, just use @FramyUseProvider annotation
FramyUserProvider with FramyWidget will cause the generated app to pass a dependency using wrapped Provider around your widget.
@FramyUseProvider(User)
@framyWidget
class ProfilePage extends StatelessWidget {
@override
Widget build(BuildContext context) {
return Consumer<User>(
builder: (context, user, child) {
return ...;
},
);
}
}
Maintenance
Our purpose is to make this tool as comprehensive as possible. We are trying to constantly improve it, add new features, handle new cases and fix any bugs.
If there is any use-case that we do not support and you think we should, feel free to submit an issue on GitHub. 🙂
