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.

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

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