Platform Hooks

Contents 1 Introduction 2 Prioritizable Interface 3 Hooks 3.1 AdditionalPropertyResolver 3.2 AdvancedQueryBuilderHook 3.3 ExtraWindowSettingsInjector 3.3.1 Example 3.4 ProcessRunnerHook 3.5 ReportLanguageHandler

Introduction

This guide contains the available platform hooks that can be used to extend or customize the standard behavior of some specific componentes of the Openbravo platform.

Before reading this guide it is important to understand the concept of dependency injection so it is recommended to read the following guide first.

Prioritizable Interface

Most of the hooks presented in this guide implements the Prioritizable interface. This is an interface that is used to define a priority between hooks so they can be executed in order when needed.

 
public interface Prioritizable {
  /**
   * @return an integer representing the priority of the object. It returns 100 by default.
   */
  public default int getPriority() {
    return 100;
  }
}

The WeldUtils class provides methods to retrieve instances of hooks that implements the Prioritizable interface sorted by their priority:

 
return WeldUtils.getInstancesSortedByPriority(ProcessRunnerHook.class, new ADProcessIDSelector(bundle.getProcessId()));

Hooks

AdditionalPropertyResolver

An extension mechanism that can be used to resolve the value of additional properties requested to the datasource which cannot be resolved through the data model and require some kind of special logic to get the property value.

 
public interface AdditionalPropertyResolver extends Prioritizable {
 
  /**
   * Determines if the value of the given property can be resolved for the business objects of the
   * given entity.
   * 
   * @param entity
   *          The entity that may be linked to the given property, although without having direct
   *          relationship through the data model
   * @param additionalProperty
   *          The additional property path
   * 
   * @return {@code true} if the value of the property can be resolved with this
   *         {@code AdditionalPropertyResolver} or {@false} in any other case
   */
  public boolean canResolve(Entity entity, String additionalProperty);
 
  /**
   * Resolves an additional property. If null or an empty map is returned, then the additional
   * property will be tried to be resolved with an {@code AdditionalPropertyResolver} with less
   * priority, if any. If there is no {@code AdditionalPropertyResolver} returning a map with
   * values, then the standard logic of the {@link DataToJsonConverter} will be used to resolve the
   * additional property.
   * 
   * @see DataToJsonConverter#toJsonObject
   * 
   * @param bob
   *          The source {@link BaseOBObject}
   * @param additionalProperty
   *          The path to the additional property to be resolved
   * 
   * @return a Map with the values resolved for the additional property where the keys are the
   *         property names and values are the property values
   */
  public Map<String, Object> resolve(BaseOBObject bob, String additionalProperty);
 
  /**
   * Provides the list of {@link DataSourceProperty} that must be included in the standard data
   * sources when the provided entity and additional property are requested. This is needed in order
   * to support filtering and sorting in the client side by the given additional property. If null
   * or an empty list is returned, then the properties will be tried to be retrieved with an
   * {@code AdditionalPropertyResolver} with less priority, if any. If there is no
   * {@code AdditionalPropertyResolver} returning a list with properties, then no data source
   * properties will be added for the given additional property.
   * 
   * @see DefaultDataSourceService#getDataSourceProperties
   * 
   * @param entity
   *          The base entity
   * @param additionalProperty
   *          The additional property path
   *
   * @return the list of {@link DataSourceProperty} to be included in the data source
   */
  public List<DataSourceProperty> getDataSourceProperties(Entity entity, String additionalProperty);
 
  /**
   * Retrieves the set of names of the additional properties that can be resolved with this
   * {@code AdditionalPropertyResolver} for the given {@link Entity}. It is used to display these
   * names as part of the list of available properties calculated by the
   * {@link ModelDataSourceService}.
   *
   * @see ModelDataSourceService#fetch
   *
   * @param entity
   *          The entity whose additional properties would be resolved
   *
   * @return the set of names of the additional properties that can be resolved for the given entity
   *         with this {@code AdditionalPropertyResolver}
   */
  public Set<String> getPropertyNames(Entity entity);
}

AdvancedQueryBuilderHook

The AdvancedQueryBuilder is class used to build the query that is executed by the datasource of the majority of the backoffice standard windows. The AdvancedQueryBuilderHook allows to modify the query by adding custom logic on some key points of the query building.

The methods of this hook receive the AdvancedQueryBuilder so it can be used to determine if the hook needs to do any modification in the query or not.

 
public interface AdvancedQueryBuilderHook extends Prioritizable {
 
  /**
   * This method can be used to modify the join clauses of the query.
   * 
   * @param queryBuilder
   *          The {@link AdvancedQueryBuilder} instance. It can be used to access to information
   *          related to the query being built
   * @param joinDefinitins
   *          The current list of {@link JoinDefinition} for the query being built
   * 
   * @return the new list of {@link JoinDefinition} of the query
   */
  public List<JoinDefinition> getJoinDefinitions(AdvancedQueryBuilder queryBuilder,
      List<JoinDefinition> joinDefinitins);
 
  /**
   * This method is used to provide an alternative way of parsing a simple filter clause. Note that
   * this method may return null which means that the filter clause may be parsed by another
   * {@code AdvancedQueryBuilderHook} with less priority, if exists. In case there is no hook
   * returning a not null value, then the filter clause will be parsed with the standard logic of
   * the {@link AdvancedQueryBuilder}.
   * 
   * @param queryBuilder
   *          The {@link AdvancedQueryBuilder} instance. It can be used to access to information
   *          related to the query being built
   * @param fieldName
   *          The name (it can be a path) of the property being filtered
   * @param operator
   *          The filtering operator
   * @param value
   *          The value to filter the property
   * 
   * @return a String containing the parsed filter clause or null in case this hook is not able to
   *         parse the filter clause
   */
  public String parseSimpleFilterClause(AdvancedQueryBuilder queryBuilder, String fieldName,
      String operator, Object value);
 
  /**
   * This method is used to provide an alternative way of parsing a part of the order by clause.
   * Note that this method may return null which means that the part of the order by may be parsed
   * by another {@code AdvancedQueryBuilderHook} with less priority, if exists. In case there is no
   * hook returning a not null value, then the order by clause will be parsed with the standard
   * logic of the {@link AdvancedQueryBuilder}.
   * 
   * @param queryBuilder
   *          The {@link AdvancedQueryBuilder} instance. It can be used to access to information
   *          related to the query being built
   * @param orderByPart
   *          One of the parts of order by clause of the query being built
   * 
   * @return a String with the parsed filter clause or null in case this hook is not able to parse
   *         the filter clause
   */
  public String parseOrderByClausePart(AdvancedQueryBuilder queryBuilder, String orderByPart);
}

ExtraWindowSettingsInjector

This hook is called after the loading of each backoffice window, at the end of the execution of the WindowSettingsActionHandler action handler. It is implemented by extending the ExtraWindowSettingsInjector class which has just one method to implement: doAddSetting. This method receives two parameters:

parameters

the parameters Map of the current WindowSettingsActionHandler execution.

json

the JSONObject response instance of the WindowSettingsActionHandler.

It returns a Map<String, Object> with all the extra settings desired to be included in the WindowSettingsActionHandler response. These extra settings are included in the callbacks response data object inside the extraSettings property. If the WindowSettingsActionHandler.EXTRA_CALLBACK key is used with a String or List<String> as value it is possible to return some JavaScript function names that are executed on the callback of the WindowSettingsActionHandler. These JavaScript functions can be implemented to use the extraSettings included in the Map. These function only receipt the original data object of the callback as argument.

Example

This example shows an alert every time the Product window is loaded. You can find the code described below in the org.openbravo.platform.features module.

The java implementation add an extra setting called showAlert with the boolean true as its value. It also adds the OB.OBPF.showAlert JavaScript function using the extraCallbacks key.

public class ExtraSettingsInjectorExample implements ExtraWindowSettingsInjector {
 
  @Override
  public Map<String, Object> doAddSetting(Map<String, Object> parameters, JSONObject json)
      throws OBException {
    Map<String, Object> extraSettings = new HashMap<String, Object>();
    String strWindowId = (String) parameters.get("windowId");
    if ("140".equals(strWindowId)) {
 
      // Set extraSettings
      extraSettings.put("showAlert", true);
 
      // Set extraCallbacks
      List<String> callbackList = new ArrayList<String>();
      extraSettings.put("extraCallbacks", callbackList);
 
      // Add extraCallbacks
      callbackList.add("OB.OBPF.showAlert");
    }
    return extraSettings;
  }
}

The JavaScript implementation shows an alert in case the extraSettings.showAlert is true.

OB.OBPF = OB.OBPF || {};
 
OB.OBPF = {
  showAlert: function (data) {
 
    if (!data|| !data.extraSettings || !data.extraSettings.showAlert) {
      return;
    }
    alert("Window opened");
  }
};

ProcessRunnerHook

The ProcessRunner class is used to execute some of the processes defined in the Application Dictionary. With a ProcessRunnerHook it is possible to execute custom logic once the ProcessRunner has finished with the execution of a process.

  
public interface ProcessRunnerHook extends Prioritizable {
  /**
   * Executed when the processrunner ends successfully
   * 
   * @param bundle
   *          a collection with the processRunner args and the system process data
   * 
   */
  public void onExecutionFinish(ProcessBundle bundle);
}

The classes implementing this interface must be annotated with the @ADProcessID to specify the process that they are linked to.

ReportLanguageHandler

Provides a way to overwrite the standard logic to retrieve the language of the report and select a different language based on some ad-hoc logic.

  
public interface ReportLanguageHandler extends Prioritizable {
 
  /**
   * Returns the language value based on an ad-hoc logic.
   * 
   * @param parameters
   *          Report parameters with the required information to to get the language based on the
   *          implemented logic
   * 
   * @return Language to use in the desired report
   */
  public String getLanguage(Map<?, ?> parameters) throws OBException;
}

Classes that implement this interface should be annotated with the @ReportLanguage.Qualifier annotation in order to define the report that they can handle.