wc_dart_framework #

Dart framework to provide common code for projects

About #

This package is designed to provide common code utilities for Flutter projects, reducing boilerplate code and improving development efficiency.

Features #

• AssetGen
• BlocGen
• BlocUpdateField
• EnumGen
• Utils

How to use wc_dart_framework #

AssetGen #

AssetGen generates a class with references to all assets within a specified folder structure, eliminating the need to manually reference asset paths.

Example

Create a separate file (e.g., images.dart): In this file, define one or more classes with the prefix _$ and annotate them with @AssetGen to specify the paths to your asset directories. This will generate a file named images.asset.g.dart containing the asset classes.

// ignore_for_file: unused_element

import 'package:wc_dart_framework/wc_dart_framework.dart';

part 'images.asset.g.dart'; // Generated file

// Class for SVG assets
@AssetGen(
  path: 'assets/svgs', // Path to your SVG assets
  showExtension: false,
)
class _$SvgImages {}

// Class for other image assets
@AssetGen(
  path: 'assets/others', // Path to other assets
  showExtension: false,
)
class _$OtherImages {}

Access your assets using the generated classes.

// Access SVG assets
Image.asset(SvgImages.IC_HOME); // 'assets/svgs/ic_home.svg'

// Access other image assets
Image.asset(OtherImages.RED); // 'assets/others/red.jpeg'

You can create multiple classes (e.g., _$SvgImages, _$OtherImages) to organize assets from different directories.

Parameters

BlocGen #

BlocGen is a code generation tool that automates the creation of BLoC classes, selectors, and listener callbacks. It simplifies working with flutter_bloc and built_value by reducing boilerplate code.

Example

Add the @BlocGen() annotation to your BLoC class.

part 'example_bloc.bloc.g.dart';

@BlocGen()
class ExampleBloc extends Cubit<ExampleState> {
  ExampleBloc() : super(ExampleState());
}

class ExampleState {
  final bool isLoading;
  final bool hasError;
  final String errorMessage;

  ExampleState({
    this.isLoading = false,
    this.hasError = false,
    this.errorMessage = '',
  });
}

Use the generated selectors to access state fields in a type-safe manner.

ExampleBlocSelector(
  selector: (state) => state.hasError,
  builder: (hasError) {
    // Your UI code
  },
)

For built_value states, the selectors are even simpler:

ExampleBlocSelector.errorMessage(
  builder: (errorMessage) {
    // Your UI code
  },
)

BlocGen Annotations #

• BlocUpdateField
• BlocListenField
• BlocGenIgnoreFieldSelector
• BlocHydratedField

Note:

These annotation works only when the state class is implemented using built_value.

BlocUpdateField #

The @BlocUpdateField annotation is used to auto-generate methods for updating state fields in BLoC classes.

Example

Use the @BlocUpdateField() annotation on the fields you want to generate update methods for.

abstract class ExampleState implements Built<ExampleState, ExampleStateBuilder> {
  ExampleState._();
  factory ExampleState([void Function(ExampleStateBuilder) updates]) = _$ExampleState;

  @BlocUpdateField()
  String get errorMessage;
}

Add the Mixin to Your BLoC

@BlocGen()
class ExampleBloc extends Cubit<ExampleState> with _$ExampleBlocMixin {
  ExampleBloc() : super(ExampleState());
}

Using the Generated Update Methods

final bloc = BlocProvider.of<ExampleBloc>(context);
bloc.updateErrorMessage('Hello Error!');

BlocListenField #

Use the @BlocListenField() annotation to generate a callback method that is triggered when the field is updated.

Example

@BlocUpdateField()
@BlocListenField()
String get errorMessage;

Override the generated callback method in your BLoC:

@override
void _$onUpdateErrorMessage() {
  print('Error Message: ${state.errorMessage}');
}

BlocGenIgnoreFieldSelector #

The @BlocGenIgnoreFieldSelector annotation prevents a field from being included in generated field selectors.

Example

@BlocGenIgnoreFieldSelector()
String get privateField;

BlocHydratedField #

The @BlocHydratedField annotation marks a field to be persisted in a hydrated state. If you generate code for a hydrated state, you must use a logger for debugging. For more details, see Utils.

Example

@BlocHydratedField()
String get userToken;

When using @BlocHydratedField, ensure your BLoC class includes the HydratedMixin and _$ExampleBlocHydratedMixin mixins, and call hydrate() in the constructor to enable state hydration.

final _logger = Logger('example_bloc'); // Logger

@BlocGen()
class ExampleBloc extends Cubit<ExampleState>
    with _$ExampleBlocMixin, HydratedMixin, _$ExampleBlocHydratedMixin {
  ExampleBloc() : super(ExampleState()) {
    hydrate();
  }
}

EnumGen #

The @EnumGen annotation generates extension methods (when, whenOrNull, maybeWhen) for Dart enums, simplifying enum handling with type-safe, concise code. It reduces boilerplate and prevents compile-time errors by ensuring all enum cases are handled correctly.

Example

Add the @EnumGen() annotation to your enum.

import 'package:wc_dart_framework/wc_dart_framework.dart';

part 'example_enum.enum.g.dart';

@EnumGen()
enum ExampleEnum { enum1, enum2 }

Using The Generated Methods

final ExampleEnum en = ExampleEnum.enum1;

en.when(
  enum1: () => print('This is enum1'),
  enum2: () => print('This is enum2'),
);

Utils #

The wc_dart_framework package also provides logging utilities powered by the logging package. You don't need to import logging separately—just initialize it in your void main method, and you're ready to go.

Example

void main() {
  LoggingUtils.initialize(); // Initializes logging utilities
  runApp(MyApp());
}

Installation and Running the Code Generator

1. Add the wc_dart_framework package to your pubspec.yaml file:

dependencies:
  wc_dart_framework: latest_version

2. Add the generator to your dev dependencies:

dev_dependencies:
  wc_dart_framework_generator: latest_version

3. Run the code generator to generate the missing .g.dart files:

dart run build_runner build

Contributors #

• Ali Abbas
• Ali Hamza