FlutterArtist StorageBackendAction ex1

Structure of the example
ProjectContributor84aShelf
StorageBackendAction

In FlutterArtist, StorageBackendAction enables the execution of backend actions (such as creating, editing, or deleting resources). Once completed, this event is broadcast to Listeners throughout your entire application. These listeners — including Block(s), Scalar(s), and even Activity(s)—can react by automatically Re-querying to fetch the latest data.

final action = AddContributors84aStorageBackendAction(
  projectId: projectInfo.id,
  needToConfirm: true,
  actionInfo: 'Add Multi Contributors to Project("${projectInfo.name}")',
);
await FlutterArtist.storage.executeBackendAction(
  actionConfirmationType: ActionConfirmationType.custom,
  action: action,
  navigate: null,
);

No ADS

Example Scenario: Demo84a

Imagine a complex project management system. You are in a "remote area" (e.g., an EndDrawer or a system config screen) and add personnel to a project. How does the personnel list on the main screen know it needs to reload?

That is when StorageBackendAction shows its power: It doesn't just work with the server; it wakes up listeners "sleeping" on other Shelf(s) to synchronize reality.

Download FlutterArtist Demo
FlutterArtist Code Flow Viewer

1. Structure of the example

2. ProjectContributor84aShelf

In the FlutterArtist design, a StorageBackendAction is essentially an event occurring within the Storage but outside the Shelf(s). Therefore, it is categorized as an External Shelf Event — similar to an event happening on a different Shelf from the current one.

To enable Contributor84aBlock to "hear" these external noises, we must configure an event recipient:

project_contributor84a_shelf.dart

class ProjectContributor84aShelf extends Shelf {
  @override
  ShelfStructure defineShelfStructure() {
    return ShelfStructure(
      filterModels: {},
      blocks: [
        Project84aBlock(
          name: Project84aBlock.blkName,
          description: null,
          config: BlockConfig(),
          filterModelName: null,
          formModel: null,
          childBlocks: [
            Contributor84aBlock(
              name: Contributor84aBlock.blkName,
              description: null,
              config: BlockConfig(
                onExternalShelfEvents: ExternalShelfEventBlockRecipient(
                  blockLevelReactionOn: [
                    Event(ContributorInfo),
                    Event(ContributorData),
                  ],
                ),
              ),
              filterModelName: null,
              formModel: null,
              childBlocks: null,
            ),
          ],
        ),
      ],
    );
  }

  Project84aBlock findProject84aBlock() {
    return findBlock(Project84aBlock.blkName) as Project84aBlock;
  }

  Contributor84aBlock findContributor84aBlock() {
    return findBlock(Contributor84aBlock.blkName) as Contributor84aBlock;
  }
}

FlutterArtist Projections (***)

3. StorageBackendAction

In this example, AddContributors84aStorageBackendAction performs the task of adding multiple contributors to a project.

AddContributors84aStorageBackendAction

class AddContributors84aStorageBackendAction extends StorageBackendAction {
  final _contributorRestProvider = ContributorRestProvider();

  final int projectId;

  AddContributors84aStorageBackendAction({
    required this.projectId,
    required super.needToConfirm,
    required super.actionInfo,
  });

  @override
  Future<ApiResult<dynamic>> performBackendOperation() async {
    return await _contributorRestProvider.addMultiContributors(projectId);
  }

  @override
  CustomConfirmation? createCustomConfirmation() {
    return null;
  }

  @override
  StorageBackendActionConfig initDefaultConfig() {
    return StorageBackendActionConfig(
      emitEvents: [
        Event(ContributorInfo), //
        Event(ContributorData), //
      ],
    );
  }
}

performBackendOperation()

This method is the "long arm" reaching out to the server to execute the business logic.

performBackendOperation()

@override
Future<ApiResult<dynamic>> performBackendOperation() async {
  return await _contributorRestProvider.addMultiContributors(projectId);
}

StorageBackendActionConfig

This is where you define which "signals" will be broadcast after a successful action. Registered listeners (like Contributor84aBlock above) will catch these signals and automatically perform a Re-query.

initDefaultConfig()

@override
StorageBackendActionConfig initDefaultConfig() {
  return StorageBackendActionConfig(
    emitEvents: [
      Event(ContributorInfo), //
      Event(ContributorData), //
    ],
  );
}

Let's look at the definition of Contributor84aBlock. This block will react to events outside the Shelf at the block level (blockLevel), or in other words, this event will cause Contributor84aBlock to be re-queryed.

project_contributor84a_shelf.dart (**)

Contributor84aBlock(
  name: Contributor84aBlock.blkName,
  description: null,
  config: BlockConfig(
    onExternalShelfEvents: ExternalShelfEventBlockRecipient(
      blockLevelReactionOn: [
        Event(ContributorInfo),
        Event(ContributorData),
      ],
    ),
  ),
  filterModelName: null,
  formModel: null,
  childBlocks: null,
),

No ADS

How to execute a StorageBackendAction:

_addMultiContributor()

Future<void> _addMultiContributor() async {
  FlutterArtist.codeFlowLogger.addMethodCall(
    ownerClassInstance: this,
    currentStackTrace: StackTrace.current,
    parameters: null,
  );
  ProjectContributor84aShelf shelf = FlutterArtist.storage.findShelf();
  Project84aBlock project84aBlock = shelf.findProject84aBlock();
  ProjectInfo? projectInfo = project84aBlock.currentItem;
  if (projectInfo == null) {
    return;
  }
  final action = AddContributors84aStorageBackendAction(
    projectId: projectInfo.id,
    needToConfirm: true,
    actionInfo: 'Add Multi Contributors to Project("${projectInfo.name}")',
  );
  await FlutterArtist.storage.executeBackendAction(
    actionConfirmationType: ActionConfirmationType.custom,
    action: action,
    navigate: null,
  );
}

Similarly, we have RemoveContributor84aStorageBackendAction, used to remove a Contributor from a Project.

RemoveContributor84aStorageBackendAction

class RemoveContributor84aStorageBackendAction extends StorageBackendAction {
  final _contributorRestProvider = ContributorRestProvider();

  final ContributorInfo contributor;

  RemoveContributor84aStorageBackendAction({
    required this.contributor,
    required super.needToConfirm,
    required super.actionInfo,
  });

  @override
  Future<ApiResult<dynamic>> performBackendOperation() async {
    return await _contributorRestProvider.delete(contributor.id);
  }

  @override
  CustomConfirmation? createCustomConfirmation() {
    return null;
  }

  @override
  StorageBackendActionConfig initDefaultConfig() {
    return StorageBackendActionConfig(
      emitEvents: [
        Event(ContributorInfo), //
        Event(ContributorData),
      ],
    );
  }
}

No ADS

FlutterArtist StorageBackendAction ex1

1. Structure of the example

2. ProjectContributor84aShelf

3. StorageBackendAction

FlutterArtist

FlutterArtist

Newest Articles