alghwalbi_core_app

Table of contents

• Features
• Architecture
• Requirements
• Installation
• Quick start
• Networking
  • Setting up DioApiService
  • Making requests
  • Caching strategies
  • Request cancellation
  • OperationResult<T>
• Push notifications
• Navigation
• Form Builder
  • Supported field types
  • Rendering a form
  • Dynamic dropdowns
  • Visibility rules
  • Calculated fields
  • Repeating groups
• Utilities
• Widgets
• API reference
• Project structure
• License

Features

Architecture

The package ships as a single library (package:alghwalbi_core_app/alghwalbi_core_app.dart). Everything the host app needs is exported from that one import.

flowchart TB
    App["Host Flutter app"]

    subgraph Core["alghwalbi_core_app"]
        direction TB
        Router["AppRouter<br/><sub>navigation, dialogs</sub>"]
        subgraph Services
            Api["IApiService<br/><sub>DioApiService / HttpApiService</sub>"]
            Push["PushNotificationService"]
            Net["InternetConnectionService"]
        end
        subgraph FormBuilder["Form Builder"]
            Models["Field models<br/><sub>JSON to typed fields</sub>"]
            Engine["Engine<br/><sub>scope, visibility, calculation</sub>"]
            Views["FormFieldWidget<br/><sub>per-type renderers</sub>"]
        end
        Utils["Utils<br/><sub>toast, date, location, camera, layout...</sub>"]
        Widgets["Reusable widgets<br/><sub>buttons, dropdowns, app bar...</sub>"]
    end

    Backend[("Backend API")]
    FCM[("Firebase Cloud Messaging")]

    App --> Router & Api & Push & Views & Utils & Widgets
    Models --> Engine --> Views
    Api --> Backend
    Push --> FCM

Design principles

Requirements

Installation

Add the package to your pubspec.yaml. Pinning to a tag or commit is recommended so upgrades are deliberate:

dependencies:
  alghwalbi_core_app:
    git:
      url: https://github.com/ahmedabdelrahmanalghwalbi/alghwalbi_core_app.git
      ref: master # or a specific tag / commit

Then fetch dependencies:

flutter pub get

And import the library:

import 'package:alghwalbi_core_app/alghwalbi_core_app.dart';

Quick start

Wire the package's navigatorKey into your MaterialApp. Toasts, modal sheets, dialogs and navigation all resolve their context through it.

import 'package:flutter/material.dart';
import 'package:alghwalbi_core_app/alghwalbi_core_app.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: AppRouter.navigatorKey,
      navigatorObservers: [AppRouter.routeObserver],
      home: const HomePage(),
    );
  }
}

Anywhere in the app:

AppRouter.navigateTo(() => const DetailsPage(), animationType: AnimationTypes.slide);
ToastUtils.showSuccess('Saved successfully');

Networking

Setting up DioApiService

DioApiService delegates everything app-specific (headers, tokens, error mapping) to an IApiServiceHelpers implementation that you own.

sequenceDiagram
    autonumber
    participant UI as Screen
    participant S as DioApiService
    participant H as IApiServiceHelpers (yours)
    participant C as Cache store
    participant B as Backend

    UI->>S: get<T>(url, dataKey, cacheType)
    S->>H: buildHeadersMethod(addToken, contentType...)
    H-->>S: headers
    S->>C: lookup (per cacheType)
    S->>B: HTTP request
    B-->>S: response
    alt 401 Unauthorized
        S->>H: unauthrizedCallback(response)
    end
    S-->>UI: OperationResult<T>

final apiService = DioApiService(
  dio: Dio(),
  apiServiceHelper: MyApiServiceHelpers(), // implements IApiServiceHelpers
  cancelTokenManager: DioApiCancelTokenManagerService(),
  connectionTimeout: 30, // seconds
  receiveTimeout: 30,
  sendTimeout: 60,
  enableCache: true,
);

class MyApiServiceHelpers implements IApiServiceHelpers {
  @override
  void Function(dynamic response)? unauthrizedCallback = (_) {
    // e.g. clear the session and route to login
  };

  @override
  Future<Map<String, String>> buildHeadersMethod({
    Map<String, dynamic>? additionalHeaders,
    bool? addToken = true,
    bool? addSessionCookie = false,
    bool isBasicAuth = false,
    String? basicUsername,
    String? basicPassword,
    RequestContentType contentType = RequestContentType.json,
    RequestAcceptanceType acceptanceType = RequestAcceptanceType.json,
  }) async {
    final token = await secureStorage.read(key: 'access_token');
    return {
      'Accept': acceptanceType == RequestAcceptanceType.json ? 'application/json' : '*/*',
      'Content-Type': contentType == RequestContentType.json
          ? 'application/json'
          : 'application/x-www-form-urlencoded',
      if (addToken == true && token != null) 'Authorization': 'Bearer $token',
      ...?additionalHeaders?.map((k, v) => MapEntry(k, '$v')),
    };
  }

  @override
  OperationResult<T> handleDIOBadResponse<T>({
    required DioException error,
    required String endpoint,
    required StackTrace stackTrace,
  }) => OperationResult<T>(
        statusCode: error.response?.statusCode ?? 500,
        message: 'Something went wrong. Please try again.',
      );

  // ...implement the remaining handle* methods the same way.
}

Making requests

Every method takes a currentPageKeyForCancelTokens (used to cancel in-flight requests when a page is disposed) and a dataKey.

final result = await apiService.get<Map<String, dynamic>>(
  '$baseUrl/profile',
  currentPageKeyForCancelTokens: 'ProfilePage',
  dataKey: 'data',
  addToken: true,
  cacheType: RequestCacheTypes.refreshForceCache,
);

if (result.success) {
  final profile = Profile.fromJson(result.data!);
} else {
  ToastUtils.showError(result.message ?? 'Unable to load profile');
}

Caching strategies

Caching is honored by DioApiService when constructed with enableCache: true. The strategy is chosen per request and never mutates global state.

Request cancellation

@override
void dispose() {
  apiService.cancelCurrentPageRequests(currentPageKeyForCancelTokens: 'ProfilePage');
  super.dispose();
}

Use cancelAllRequests() to abort everything, for example on logout.

OperationResult<T>

Push notifications

PushNotificationService handles the Firebase Cloud Messaging lifecycle. You supply three callbacks; the service handles the rest.

flowchart LR
    A["init()"] --> B{"Permission<br/>granted?"}
    B -- No --> X["Log warning<br/>and stop"]
    B -- Yes --> C["Configure foreground<br/>presentation"]
    C --> D["Get FCM token"]
    D --> E["registerDeviceTokenToServerMethod"]
    E --> F["Listen for messages<br/>and token refresh"]
    F --> G["onReceiveNotification"]

final pushService = PushNotificationService(
  registerDeviceTokenToServerMethod: ({required notificationDeviceToken}) async {
    await myApi.registerDevice(notificationDeviceToken);
  },
  unregisterDeviceTokenToServerMethod: () async => myApi.unregisterDevice(),
  onReceiveNotification: ({required message}) async {
    // Route the user or refresh data based on message?.data
  },
);

await Firebase.initializeApp();
await pushService.init();

Badge control is available through NotificationBadgeUtils:

await NotificationBadgeUtils.setNotificationBadgeCount(3);
await NotificationBadgeUtils.clearNotificationBadge(isIOSOnly: true);

Navigation

AppRouter is a static, context-free router built on AppRouter.navigatorKey.

AppRouter.navigateTo(() => const HomePage(), replaceAll: true, animationType: AnimationTypes.fade);
AppRouter.goBack(result: selectedItem);
AppRouter.goBackUntil(routeName: '/');

final confirmed = await AppRouter.showConfirmMessageWithLogo(
  // ...title, message, icon
  confirmText: 'Delete',
  denyText: 'Cancel',
);

Form Builder

The Form Builder turns a JSON form definition into a fully interactive Flutter form. Each field is parsed into a typed model, the engine resolves visibility and calculations within the correct scope, and FormFieldWidget renders it.

flowchart LR
    J["JSON schema"] -->|"FormFieldModel.getFormFieldByType"| M["Typed field models"]
    M --> C{"FormSchemaCapabilities.detect"}
    C -- "static form" --> R["Flat renderer"]
    C -- "rules, groups or calculations" --> E["Dynamic engine"]
    E --> V["FormVisibilityUtils<br/><sub>evaluate, prune</sub>"]
    E --> K["FormCalculationUtils<br/><sub>derive, compute, aggregate</sub>"]
    V & K --> W["FormFieldWidget"]
    R --> W
    W -->|"onChanged"| E

FormSchemaCapabilities.detect(fields).usesDynamicEngine tells you whether a form needs the scope-aware engine. Forms that use none of the dynamic features render exactly as before, with no configuration.

Supported field types

The field type comes from the name property of each field in the schema. Several spellings are accepted (for example radio_group, radio-group, radiogroup).

Every field shares these base properties from FormFieldModel:

{
  "key": "customer_name",
  "name": "input",
  "title": "Customer name",
  "placeholder": "Enter the customer name",
  "required": { "value": true, "validationMessage": "Customer name is required" },
  "requiredWhenVisible": false,
  "visibilityRules": null,
  "css": {}
}

Rendering a form

final fields = (schema['fields'] as List)
    .map((json) => FormFieldModel.getFormFieldByType(json))
    .toList();

final scope = FormFieldScopeUtils.flatten(fields);

ListView(
  children: FormVisibilityUtils.visibleFields(fields, scope)
      .map((field) => FormFieldWidget(
            fieldModel: field,
            scopeFields: scope,
            primaryColor: Theme.of(context).primaryColor,
            locale: context.locale,
            spacing: 16,
            innerSpacing: 8,
            fieldRadius: 12,
            fieldFillColor: Colors.white,
            fieldBorderSize: 1,
            fieldBorderColor: Colors.grey.shade300,
            fieldHeight: 52,
            fieldIconSize: 20,
            fieldLabelTextStyle: textTheme.titleSmall!,
            fieldTextStyle: textTheme.bodyMedium!,
            fieldHintStyle: textTheme.bodyMedium!.copyWith(color: Colors.grey),
            mainAxisAlignment: MainAxisAlignment.start,
            crossAxisAlignment: CrossAxisAlignment.start,
            onChanged: (key, value) {
              FormVisibilityUtils.pruneForm(fields);
              FormCalculationUtils.recalculateForm(fields);
              setState(() {});
            },
          ))
      .toList(),
);

FormFieldWidget also exposes per-type customization, including labels for date pickers, photo sources, signature pads, uploaders and repeating groups, so every visible string can be localized by the host.

Dynamic dropdowns

Dropdowns arriving with data.queryKey: "dynamic" and a data.entityConfig are parsed as DynamicDropdownFormFieldModel. Their options come from the backend entity endpoint (GET /api/v1/form-entities/{entityKey}/data) rather than the form definition.

The package does not perform the HTTP call. The host supplies a DynamicDropdownOptionsFetcher, so authentication and base URL stay under the app's control:

FormFieldWidget(
  // ...existing parameters
  dynamicDropdownOptionsFetcher: (request) async {
    final response = await apiClient.get(
      '/api/v1/form-entities/${request.entityKey}/data',
      queryParameters: request.toQueryParameters(),
    );
    return DynamicDropdownOptionsPageModel.fromJson(response.data);
  },
  // Required for dependent dropdowns: return the current value of the parent field.
  dynamicDropdownParentValueResolver: (parentFieldKey) => formValues[parentFieldKey],
  dynamicDropdownSearchHintText: 'Search',
  dynamicDropdownRetryButtonText: 'Retry',
  dynamicDropdownNoResultsText: 'No results',
  dynamicDropdownLoadFailedText: 'Failed to load options',
)

sequenceDiagram
    autonumber
    actor U as User
    participant P as Parent dropdown
    participant C as Child dropdown
    participant F as Your fetcher
    participant API as Backend

    U->>P: Select "Region A"
    P-->>C: Parent value changed, clear selection, enable
    U->>C: Open and type "cai"
    C->>F: request(entityKey, search, offset=0, parentValue)
    F->>API: GET /form-entities/{entityKey}/data
    API-->>F: { items, hasMore: true }
    F-->>C: DynamicDropdownOptionsPageModel
    U->>C: Scroll to end
    C->>F: request(offset=50)

Behavior

• Options load when the field opens, with debounced server-side search and infinite-scroll pagination driven by hasMore.
• The stored value (and the one emitted through onChanged) is { "id": ..., "displayValue": ..., "entityKey": ... }, the shape the submissions endpoint expects.
• A dropdown whose entityConfig.dependsOn is set stays disabled until its parent has a value, and is cleared whenever the parent changes. The parent id is sent as parentValue along with parentEntityKey.
• If the fetcher throws or returns null, the field shows a retry state. Without a fetcher, dynamic dropdowns are skipped with a warning log.

Visibility rules

Any field can declare when it should be shown. Conditions always refer to sibling fields in the same scope: top-level fields read top-level values, and fields inside a repeating-group item read only that item.

{
  "key": "rejection_reason",
  "name": "text_area",
  "title": "Reason for rejection",
  "requiredWhenVisible": true,
  "visibilityRules": {
    "operator": "AND",
    "conditions": [
      { "field": "decision", "operator": "equals", "value": "rejected" },
      { "field": "category", "operator": "in", "value": ["safety", "quality"] }
    ]
  }
}

• Combinators: the rule-level operator is AND (&&, the default) or OR (||).
• Shorthand and nesting: a single showWhen condition is accepted, and an entry of conditions that has its own conditions is treated as a nested group.
• Type tolerant: 49, 49.0 and "49" compare as equal.
• Meaningful values: null, false, 0, blank text and empty lists or groups count as unanswered for exists.
• Safe by default: an incomplete rule, or one pointing outside the scope, keeps the field visible so no data is hidden by mistake.
• Pruning: FormVisibilityUtils.pruneForm(fields) clears the values of hidden fields, following chains such as action → reason → reason details until nothing else changes.
• A hidden field is never required, whatever required or requiredWhenVisible says.

Calculated fields

Calculated fields are read-only and resolved by FormCalculationUtils. They give the user immediate feedback; the server recomputes them on submission and its result is authoritative.

Operators: add, subtract, multiply, divide, sum, product, min, max, avg (with aliases such as +, -, *, /, average, mean).

Chains like subtotal → additional → total settle in a single recalculateForm call, and aggregates and top-level formulas are resolved together so a formula can read an aggregate (for example the total of every item plus a call-out fee). A cycle in the definition is detected and logged rather than looping forever.

Repeating groups

A repeating group lets the user add, edit and remove items built from the template in its fields array. Each item owns its own field instances, so values, dependent dropdown options and visibility rules are independent between items.

{
  "key": "materials",
  "name": "repeating_group",
  "title": "Materials used",
  "groupConfig": {
    "itemLabel": "Material",
    "addItemLabel": "Add material",
    "minItems": 1,
    "maxItems": 10,
    "allowDelete": true,
    "allowEdit": true,
    "collapsibleItems": true,
    "collapseCompletedItems": false
  },
  "fields": [
    { "key": "material", "name": "dropdown", "title": "Material" },
    { "key": "quantity", "name": "numberinput", "title": "Quantity" }
  ]
}

The host controls item lifecycle through these FormFieldWidget callbacks:

Utilities

All utilities are static and require no setup beyond the quick start.

final isOnline = await InternetConnectionService().hasConnection;

final label = DateTimeUtils.formatReadableDate(dateTime: DateTime.now(), locale: 'ar');

LayoutUtils.bindWidget(
  context,
  mobileWidget: () => const MobileLayout(),
  tabletWidget: () => const TabletLayout(),
);

Widgets

CustomElevatedButton(
  title: 'Submit',
  backgroundColor: Theme.of(context).primaryColor,
  onPressed: () async => await submitForm(),
);

API reference

Project structure

lib/
├── alghwalbi_core_app.dart          # Single library entry point
├── router/
│   └── app.router.dart              # AppRouter, transitions, dialogs
└── core/
    ├── constants/                   # Package asset paths
    ├── models/                      # AppBaseModel, OperationResult
    ├── services/
    │   ├── api/                     # IApiService, Dio & http clients, logging
    │   ├── internet_connection/
    │   └── push_notifications/
    ├── utils/                       # Toast, date, layout, location, camera...
    ├── widgets/                     # Buttons, app bar, dropdowns, popups...
    │   └── custom_dropdown/         # Single, multi and dynamic dropdowns
    └── form_builder/
        ├── models/                  # Inputs, statics, structure, enums, rules
        ├── engine/                  # Scope, visibility, calculation
        └── views/                   # Per-type field widgets

License

Released under the MIT License.