Extending Helix Resources

You can extend a Helix resource by:

• Adding related resources to existing resources

  This method requires adding links to existing resources.

• Overriding the functionality of an existing resource to include additional fields in an entity, remove a resource and its link, or change the functionality of a resource as required

For a tutorial on extending Helix resources, see the Tutorials repository. In the ep-commerce-examples directory for this version, select the examples branch and search for extend Helix.

Adding New Resources

This section explains adding a new resource with an example extending carts resource. The default alias defined for a customer cart is defaultcart, however you can add a new custom alias, such as awesomecart, for the custom cart.

note

In Cortex, all XML files for a family must be contained within a single resource bundle.

To implement awesomecart, create a new resource bundle and a new family name.

For the family name ext-carts, with name of the resource bundle, ext-carts-api, and the name of the prototype bundle ext-carts, the new definition is as in the following example:

<family>
    <name>ext-carts</name>

    <resource>
        <name>awesome-cart</name>
        <description><![CDATA[Alias to the awesome cart for the current shopper.]]></description>
        <uri>{base.family}/{base.scope}/awesome</uri>
        <alias>carts.cart</alias>
    </resource>
</family>

The newly defines wiring extends the AbstractHelixModule as in the following example:

@Named
public class ExtCartWiring extends AbstractHelixModule {
    @Override
    protected String resourceName() {
        return AwesomeCartResource.FAMILY; //Note the family name is “ext-carts”
    }
}

You may define links to and from an existing carts resource or any other resources to the new resource. After performing this step, the system creates the following:

• Bundles
  • carts-api
  • ext-carts-api
• Prototype bundles
  • carts
  • ext-carts

Overriding Existing Resource

After adding the new alias, awesomecart, delete the default alias, defaultcart, by implementing a new resource bundle ext-carts. This section provides step-by-step instructions with an example.

1. To remove the defaultcart alias, create a new prototype bundle such as, override-carts.

2. Override appropriate prototypes by using @PrototypeExtension.

   Following is an example to implement RootToDefaultCartRelationship.LinkTo:

   @PrototypeExtension
   public class RemoveDefaultCartImpl implements RootToDefaultCartRelationship.LinkTo {
       @Override
       public Observable<DefaultCartIdentifier> onLinkTo() {
           return Observable.empty();
       }
   }
   

3. Implement DefaultCartResource.Read with an error to display when accessing the resource directly.

   @PrototypeExtension
   public class DisableReadDefaultCartPrototype implements DefaultCartResource.Read {
       @Override
       public Single<CartIdentifier> onRead() {
           return Single.error("defaultcart has been removed, use awesomecart instead");
       }
   }
   

4. Add the resource wiring module as in the following example:

   @Named
   public class ExtCartWiring extends CartWiring {
       // The inherited resourceName() will return the family name "carts"
   
       /**
        * Tell Cortex to use the `permission.properties` file from this resource instead of the original resource.
        */
       @Override
       protected int permissionsLookupRank() {
           return 200;
       }
   }
   

   You can configure the family name in the wiring module.

   note

   The default permissions lookup rank is 100. Cortex will read the permission.properties file from the wiring module for a given family name with the highest value. If you do not override the permissionsLookupRank method, you will see errors in Cortex like the following:

   Permission lookup for server carts already exists with rank 100
   

5. Add a permission.properties to the module as in the following example:

   relos.role.PUBLIC=ADVISE_READ,ADVISE_CREATE,ADVISE_UPDATE,ADVISE_DELETE,LINK,CREATE,READ,DELETE,INFO:*
   

   note

   Usually the best approach is to copy the permission.properties file from the original module, and modify it as needed.

   For more information, see Configuring Bundle Permissions.

After performing this step, the system consists of the following:

• Bundles
  • carts-api
  • ext-carts-api
• Prototype bundles
  • carts
  • ext-carts
  • override-carts