Skip to content

Actions: front, top, primary, secondary, property, tile

Jump to bottom
elvin-fms edited this page Feb 18, 2021 · 3 revisions

This page describes some possible types of actions that can be performed and how to achieve them. Here you will learn how to create, add and customize action in different places such as on the standalone or embedded centre, or as a tile on the main menu. Learn how to create different types of actions: primary, secondary and property action.

  1. Actions Overview
  2. Front Actions
  3. Top Actions
  4. Primary Actions
  5. Secondary Actions
  6. Property Actions
  7. Tile Actions

Actions Overview

In TG-based application actions can be located in different places. Actions can be standard or custom.

Standard functions include: creation of a new instance of an entity, editing of an existing instance, deletion of an existing instance, export of selected entities.

More complex functionality requires the creation of Custom functions. For example, CopyWorkActivityAction - will create a copy of work activity and also will link same documents and attachments if a user chooses this options; JobPackAction - functional entity that will create for selected work activities a JobPack jasper reports, combine them into one PDF file and will open it for the user to review and print if necessary.

Entity New Action

The different approach should be used when adding new action depending on the place it is called from: standalone or embedded centre and what entity master would be evoked: simple or compound. StandardActions should be used if action is placed on the standalone centre and utility class Compound for the embedded centre.

  1. To add new entity (that has simple master used for data population) from standalone centre StandardActions.NEW_ACTION.mkAction(EntityTypeName.class); should be used.

This is the most basic new action example. Method mkAction can be specified with computation or dimensions for master (or both). For new action by default circled plus icon is used. For icon customization it is recommended to use mkActionWithIcon method. Also specific pre-action - mkActionWithPreAction could be provided.

  1. To add new entity (that has simple master used for data population) from embedded centre StandardActions.NEW_WITH_MASTER_ACTION.mkAction(EntityTypeName.class); should be used. It also can be customized by using mkActionWithIcon and mkActionWithPreAction methods.

  2. To add new entity (that has compound master used for data population) from standalone centre Compound.openNew(OpenEntityTypeMasterAction.class, "icon-name", "Short desc", "Long desc", MASTER_DIM); should be used.

  3. To add new entity (that has compound master used for data population) from embedded centre Compound.openNewWithMaster(OpenEntityTypeMasterAction.class, "icon-name","Short desc", "Long desc", MASTER_DIM); should be used.

Entity Edit Action

A similar approach should be used when adding edit action.

  1. StandardActions.EDIT_ACTION.mkAction(EntityTypeName.class); should be used for entities with simple master.
  2. Compound.openEdit(OpenEntityTypeNameMasterAction.class, "Short desc", "Long desc", MASTER_DIM); should be used for entities with compound master.
  3. For sequential editing of few entities with simple master StandardActions.SEQUENTIAL_EDIT_ACTION.mkAction(EntityTypeName.class); should be used. The default icon for editing is represented as a pencil icon, but this can be customized.

Entity Delete Action

The most common delete action is using StandardActions.DELETE_ACTION.mkAction(EntityTypeName.class); However, mkAction method can be specified with computation. There are also mkActionWithIcon and mkActionWithPreAction methods that provide more flexibility. Circled minus icon is used as default for delete action.

Entity Export Action

  1. To provide export functionality for selected entities from standalone centre StandardActions.EXPORT_ACTION.mkAction(EntityTypeName.class); should be used.
  2. To provide export functionality for selected entities from embedded centre StandardActions.EXPORT_EMBEDDED_CENTRE_ACTION.mkAction(EntityTypeName.class); should be used.

In both cases, additional customization is possible (i.e. computation, pre-action, icon).

Custom Action

To represent Functional Entity as action in TG based system EntityActionBuilder should be used.

For example:

final EntityActionConfig action = EntityActionBuilder.action(FunctionalEntityType.class)
                .withContext(context().withSelectedEntities().build())
                .icon("icons:icon")
                .withStyle("color:#0288D4")
                .shortDesc("Action Description")
                .longDesc("More Specific Action Description")
                .build();

The action above can be created with less or more parameters specified, i. e. we can omit .withStyle and .longDesc and simply write something like this:

final EntityActionConfig action = EntityActionBuilder.action(FunctionalEntityType.class)
                .withContext(context().withSelectedEntities().build())
                .icon("icons:icon")
                .shortDesc("Action Description")
                .build();

Sometimes we need to make sure that some specific post action will take place after successful action execution. In the following case system will clear selected items in centre.

final EntityActionConfig action = EntityActionBuilder.action(FunctionalEntityType.class)
                .withContext(context().withSelectedEntities().build())
                .postActionSuccess(() -> new JsCode("self.$.egi.clearPageSelection(); \n"))
                .icon("icons:icon")
                .shortDesc("Action Description")
                .build();

But, on the other hand, some parts, like .withContext, cannot be skipped and are mandatory.

Context can contain different information:

  • .withSelectedEntities() — selected entities will be included into the context. Usually used when developing top action that will perform some data manipulation on a set of instances;
  • .withCurrentEntity() — used for primary or secondary actions, or top action that requires exactly one selected entity;
  • .withMasterEntity() — for actions located in embedded centre/master;
  • .withSelectionCrit() — can be used for actions that need to provide access to a centre selection criteria.

If action requires computation it should do it through the context, i.e.:

final EntityActionConfig action = EntityActionBuilder.action(FunctionalEntityType.class)
                .withContext(context().withSelectedEntities().withComputation((entity, context) -> CENTRE_COMPUTATION).build())
                .icon("icons:icon")
                .shortDesc("Action Description")
                .build();

Front Actions

Front actions are located in the left top corner of centre selection criteria, as per image above. They have to be specified during centre creation and added by using addFrontAction() method:

final EntityActionConfig standardNewAction = StandardActions.NEW_ACTION.mkAction(EntityTypeName.class);

final EntityCentreConfig<EntityTypeName> ecc = EntityCentreBuilder.centreFor(EntityTypeName.class)
                .addFrontAction(standardNewAction)
               
                ...

Top Actions

Top actions are located in the left top corner of the centre view. They have to be specified during centre creation and added by using addTopAction() method:

final EntityActionConfig standardNewAction = StandardActions.NEW_ACTION.mkAction(EntityTypeName.class);

final EntityCentreConfig<EntityTypeName> ecc = EntityCentreBuilder.centreFor(EntityTypeName.class)
                .addTopAction(standardNewAction)
                ...

Primary Actions

These actions are located at the start of an entity instance line in a centre view, pencil icon just after a checkbox. They have to be specified during centre creation and added by using .addPrimaryAction() method almost in the end of centre creation, after adding criteria and properties:

final EntityActionConfig standardEditAction = StandardActions.EDIT_ACTION.mkAction(EntityTypeName.class);

final EntityCentreConfig<EntityTypeName> ecc = EntityCentreBuilder.centreFor(EntityTypeName.class)
                .addCrit("this").asMulti().autocompleter(EntityTypeName.class).also()
                .addCrit("status").asMulti().autocompleter(EntityStatus.class).also()
                ...
                .addProp("this").order(1).desc().width(92)
                    .withSummary("total_count_", "COUNT(SELF)", "Count:The total number of matching ETs").also()
                .addProp("status").minWidth(110).also()
                ...
                .addPrimaryAction(standardEditAction)
                .build();

        return new EntityCentre<>(MiEntityTypeName.class, EntityTypeName.class.getSimpleName(), ecc, injector, null);

Primary actions can be skipped if not required. Multi-actions can be used as primary actions.

Secondary Actions

These actions are located at the end of an entity instance line in a centre view. They should be added after primary action if present:

final EntityActionConfig standardEditAction = StandardActions.EDIT_ACTION.mkAction(EntityTypeName.class);
final EntityActionConfig customAction = EntityActionBuilder.action(FunctionalEntityType.class)
                .withContext(context().withCurrentEntity().build())
                .icon("icons:icon")
                .shortDesc("Action Description")
                .build();

final EntityCentreConfig<EntityTypeName> ecc = EntityCentreBuilder.centreFor(EntityTypeName.class)
                ...
                .addPrimaryAction(standardEditAction).also()
                .addSecondaryAction(customAction)
                .build();

return new EntityCentre<>(MiEntityTypeName.class, EntityTypeName.class.getSimpleName(), ecc, injector, null);

Secondary actions can be skipped if not required. Multi-actions can be used as secondary actions.

Property Actions

Property actions can be located on the master or centre. On the master they should be placed near some editor (first image below) or simulate on-click action on the column in the centre (second image below).

When adding property action on the master first specify it and than add it to the configuration by using withAction(customAction) method:

final EntityActionConfig customAction = EntityActionBuilder.action(FunctionalEntityType.class)
                .withContext(context().withCurrentEntity().build())
                .icon("icons:icon")
                .shortDesc("Action Description")
                .build();

final IMaster<EntityTypeName> masterConfig = new SimpleMasterBuilder<EntityTypeName>().forEntity(EntityTypeName.class)
                .addProp("key").asSinglelineText().withAction(customAction).also()
                ...
                .done();

return new EntityMaster<>(EntityTypeName.class, masterConfig, injector);

Property action in a centre should be specified first and than included when adding a new column by using withAction(customAction) method:

final EntityActionConfig standardEditAction = StandardActions.EDIT_ACTION.mkAction(EntityTypeName.class);

final EntityCentreConfig<EntityTypeName> ecc = EntityCentreBuilder.centreFor(EntityTypeName.class)
                .addProp("this").order(1).desc().width(92)
                    .withSummary("total_count_", "COUNT(SELF)", "Count:The total number of matching ETs")
                    .withAction(standardEditAction).also()
                .addProp("status").minWidth(110).also()
                ...
                .build();

        return new EntityCentre<>(MiEntityTypeName.class, EntityTypeName.class.getSimpleName(), ecc, injector, null);

The default behaviour for EGI is to associate the "open master" action with all entity-typed properties. However, in some cases the developer may wish to override this default behaviour.

A typical example would be an entity with a composite key, where key members are entities themselves - e.g. LocationSusbsystem or Rotable. Such entities usually have their key members added separately to the EGI, but upon clicking either of these members, the master for the composite entity should open.

An action supplier should be used in such cases. As usual, the master for this entity has to be already registered.

                ...
                .addProp("locationSubsystem.location").width(60)
                    .withActionSupplier(builder.getOpenMasterAction(LocationSubsystem.class)).also()
                .addProp("locationSubsystem.subsystem").width(80)
                    .withActionSupplier(builder.getOpenMasterAction(LocationSubsystem.class)).also()
                ...

Tile Actions

Tile actions are located on the main menu directly. They should be added during app-specific IWebApp implementation to some module tile (left top corner, as on the image before), for example:

  @Override
    public void initConfiguration() {
        super.initConfiguration();
        ...
        final EntityTypeWebUiConfig entityTypeWebUiConfig = EntityTypeWebUiConfig.register(injector(), builder);
        configMobileMainMenu()
            .addModule(Modules.TILE1.title)
                .description(Modules.TILE1.desc)
                .withAction(entityTypeWebUiConfig.newAction)
                .icon("menu:tile1")
                ...
             .done()
             ...

Per aspera ad astra

Clone this wiki locally