rulecms_widget

Flutter SDK for RuleCMS — the Flutter counterpart of @rulecms/widget-react.

Fetches a widget by token + key and renders the itemList layout tree through registered component libraries (default: rulecms_source_components).

Install

dependencies:
  rulecms_widget: ^0.2.1
  rulecms_source_components: ^0.2.1

Until rulecms_widget is on pub.dev, use a path or git dependency.

Usage

import 'package:flutter/widgets.dart';
import 'package:rulecms_widget/rulecms_widget.dart';
import 'package:rulecms_source_components/rulecms_source_components.dart';

class MyPage extends StatelessWidget {
  const MyPage({super.key, required this.token, required this.publishedKey});

  final String token;
  final String publishedKey;

  @override
  Widget build(BuildContext context) {
    return RuleCMSWidgetProvider(
      token: token,
      libraries: {'default': rulecmsSourceComponentsLibrary},
      child: RuleCMSWidget(publishedKey: publishedKey),
    );
  }
}

• Staging/Production: plain token + environmentId---widget-… published key → widget-cache
• Development: dev.… token + draft widget-… key → rulecms.com live drafts

Same routing rules as @rulecms/widget-react.

Host componentProps

Pass extra props — a click handler, a callback — to one component instance by its column id. A key may be a bare id (every copy of a repeated collection) or a /-path of enclosing collection columns ending at the target (one embedding). Longest match wins.

RuleCMSWidget(
  publishedKey: publishedKey,
  componentProps: {
    'b721c4e2-…': {'onClick': handleCta},
    'holder-a/inner-col': {'onClick': openBookingDrawer},
  },
)

r-button reads onClick from the bag. The renderer never inspects the contents. In debug, a key that addresses no column in the widget is printed once so typos are visible while building.

Host mounts

Register a Flutter widget factory from your app so a Custom (r-mount) slot in the composer can render it by name. The name is a map key, not a string that becomes code. A miss is a placeholder.

RuleCMSWidget(
  publishedKey: publishedKey,
  mounts: {
    'booking-form': (props) => BookingForm(
      variant: props['variant'] as String?,
    ),
  },
)

Tell the marketer the exact name and the props the component reads. Event handlers still go through componentProps at that column's id — authored prop rows cannot become onClick. See __docs__/CONTRACT_mounts.md and Mount Your Own Components.

Develop locally

cd widget-flutter
flutter pub get
flutter test
flutter analyze

Publishing

This package publishes to pub.dev when a vX.Y.Z tag is pushed. GitHub Actions uses pub.dev automated publishing (OIDC). Do not run dart pub publish locally after the first upload.

flutter pub get
flutter analyze
flutter test
dart pub publish --dry-run
./tool/bump_version.sh patch   # or minor / major
git push && git push --tags

See __docs__/RUNBOOK_version-bump-and-release.md.

License

Proprietary — RuleCMS, LLC