Specialized component - ExternalSection

Availability of functionality depends on the license and may not be available in all deployments.

Component properties

Eximee Designer property	Attribute name in the Source	Description
Resource URL	url	Allows specifying the resource URL to be embedded inside the specialized component.

External data source for the specialized component

The content of the specialized component, apart from providing the resource URL, can be supplied via an external data source of type SECTION. The procedure for configuring the data source is described in the chapter Example of binding the service in the component.

ExternalSection in the GWT channel

For all ExternalSection that create the DOM and use the old GWT classes, you should:

• for proper styling:

  • assign a class to these elements in Eximee Designer (styleName): legacy (e.g. in ExternalSection a button is drawn, there is a slider styled the old way)
  • or add in the ExternalSection a class on the root element: legacy (transparent for old forms)
• assign the following class to the element in Eximee Designer: external-section-content (ExternalSection without class external-section-content will not take up space in the application. They will also not cause a small spacer separating the components.)

In legacy not all styles are supported.

With legacy will be consistent with the new forms (a class that can style part of the application structure).

For old ES, in addition to the two classes mentioned above, you can also assign new ones. For new ones, you can use the above or assign new ones.

Figure 1. Example appearance of the component in Eximee Designer

If components are inserted from now on (without using the old classes), you can assign any (new) class; if you use the old ones, you must add legacy.

Creating a service returning ExternalSection content in Java

New ServiceProxy API (since version 0.63.0)

Input parameters:

• The input is an object of type ExternalSectionInput containing the following fields:

  • params (accessible via the method getParams()) - map of parameters mapped to the service on the application template
  • targetApplication (accessible via the method getTargetApplication()) - identifier of the channel invoking the service. Current channels:

    • "W4" - webforms application (old GWT webforms)
    • "ex-forms" - ex-webforms application (new Angular application)
• Additionally, the parameter "componentId" is always passed in the parameter map, indicating the identifier of the component on which the service is embedded

Output parameters:

• The output is an object ExternalSectionOutput containing the following fields:

  • output (also passed in the single-argument constructor) - service output in HTML (UTF-8 encoding)

package pl.consdata.eximee.examples;
  
import org.apache.felix.scr.annotations.Component;
import org.apache.felix.scr.annotations.Service;
  
import pl.consdata.iew.serviceproxy.api.exceptions.ServiceProxyException;
import pl.consdata.iew.serviceproxy.api.section.AbstractExternalSection;
import pl.consdata.iew.serviceproxy.api.section.ExternalSectionInput;
import pl.consdata.iew.serviceproxy.api.section.ExternalSectionOutput;
import pl.consdata.iew.serviceproxy.api.types.ServiceProxyField;
  
@Component
@Service(AbstractExternalSection.class)
public class NewApiExampleExternalSection extends AbstractExternalSection {
  
   public NewApiExampleExternalSection() {
      this.name = "NewApiExampleExternalSection";
      this.inputFields.add(new ServiceProxyField(ENTRY_PARAM));
   }
  
   @Override
   public ExternalSectionOutput callServiceForExternalSection(ExternalSectionInput externalSectionInput)
         throws ServiceProxyException {
      String param = getSingleValue(externalSectionInput.getParams(), ENTRY_PARAM, "default value");
      if ("W4".equals(externalSectionInput.getTargetApplication())) {
         return new ExternalSectionOutput(String.format("<b>Webforms GWT</b><br><b>Input parameter:</b>%s<br>",
               param));
      } else if ("ex-forms".equals(externalSectionInput.getTargetApplication())) {
         return new ExternalSectionOutput(String.format("<b>EX-webforms</b><br><b>Input parameter:</b>%s<br>",
               param));
      } else {
         return new ExternalSectionOutput(String.format("<b>Channel: %s</b><br><b>Input parameter:</b>%s<br>",
               externalSectionInput.getTargetApplication(),
               param));
      }
   }
  
   static final String ENTRY_PARAM = "inputParameter";
}

Old ServiceProxy API (marked as deprecated since version 0.63.0)

Input parameters:

• targetApplication (accessible via the method getTargetApplication()) - identifier of the channel invoking the service. Current channels:

  • W4 - webforms application (old GWT webforms)
  • OTHER (since API version 0.63.0) - any channel other than W4
• params - map of parameters mapped to the service on the application template
• additionally, in the parameter map the parameter "componentId" is always passed in the parameter map, indicating the identifier of the component on which the service is embedded

Output parameters:

• The output is an object of type String, containing the service output in HTML (UTF-8 encoding)

package pl.consdata.eximee.account.szkolenie;
  
import static org.apache.commons.lang3.StringUtils.EMPTY;
  
import java.util.List;
import java.util.Map;
import org.apache.felix.scr.annotations.Component;
import org.apache.felix.scr.annotations.Service;
  
import pl.consdata.iew.serviceproxy.api.exceptions.ServiceProxyException;
import pl.consdata.iew.serviceproxy.api.section.AbstractExternalSectionServiceProxy;
import pl.consdata.iew.serviceproxy.api.section.ExternalSectionTargetApplication;
import pl.consdata.iew.serviceproxy.api.types.ServiceProxyField;
  
@Component
@Service(AbstractExternalSectionServiceProxy.class)
public class ExampleExternalSection extends AbstractExternalSectionServiceProxy {
  
    public ExampleExternalSection() {
        this.name = "ExampleExternalSection";
        this.description = "ExampleExternalSection description";
        this.inputFields.add(new ServiceProxyField(INPUT_FIELD));
    }
  
    @Override
    public String callServiceForExternalSection(
            ExternalSectionTargetApplication targetApplication,
            Map<String, List<String>> params) throws ServiceProxyException {
        String input = getSingleValue(params, INPUT_FIELD, EMPTY);
        return String.format("<script>alert('%s')</script>", input);
    }
  
    private static final String INPUT_FIELD = "input";
  
}

Designing specialized components

The service powering a specialized component can return two types of content:

• Resource URL,
• Content to be embedded in the displayed application.

Resource URL

A service returning the resource URL responds with a single-line message of the form:

URL:resourceUrl

For example:

URL:http://image.server.address/photo.png

A specialized component powered by a URL displays static content.

Content to be embedded in the displayed application

The content returned by the service will be embedded directly in the displayed application. The specialized component can take the form of:

• an HTML document,
• a JavaScript script:

  • written in <script>...</script> tags

    • it is possible to provide multiple consecutive <script /> tags one after another
  • written in <script src="..." /> tags

    • it is possible to provide multiple consecutive <script /> tags one after another
• a combination of an HTML document and <script /> tags.

Application eximee WebForms by default provides the jQuery, which can be used when designing the specialized component. External libraries must be provided independently by adding the appropriate <script src="..." /> tags.

The prepared specialized component is embedded directly in the DOM tree of the displayed application, and during rendering on all <script /> tags, the eval.

Saving the specialized component value

A specialized component can be a rich application written in JavaScript that can update the application model with its value. In this way, the saved value is taken into account when calculating component conditions, updating dependent components, powering services, saving when submitting the application, etc.

To set the value of a specialized component, call the global method provided by the eximee WebForms:

updateExternalSectionValue(SpecializedComponentIdentifier, NewComponentValue);
updateExternalSectionValue(externalSection.attr('id'), 'newValue');

The construction externalSection.attr('id') means that on the DOM tree node corresponding to the specialized component, the attribute id = specialized component identifier is set.

Its invocation updates the model of the displayed application and notifies all components dependent on the specialized component about the changes.

Integration at the application frontend level

The specialized components API enables, among other things, integration with the application in which the application is embedded (e.g. in the case of a WWW channel embedded as a portal element) at the JavaScript level. The API provides methods for reading and writing the state of components in the application.

Retrieving the value of another component

To retrieve the value of another component, call the getComponentValue("ID_OF_THE_COMPONENT_WHOSE_VALUE_WE_WANT_TO_READ") function from the ExternalSection script, e.g.:

var textfieldValue = getComponentValue("GesTextField1");

However, the following limitations should be kept in mind:

• To read session variables, they must have the "exposed" property checked,
• Only the client model can be read - i.e. components from already visited pages, potentially unvalidated fields.

Setting the value of another component from a script

All fields that can be changed by the specialized component code must be added to the writableFields component that we set on the application in the Source. A request to change the value of a component not included in the parameter writableFields, will be ignored by the platform.

To set values for other components from JavaScript, call the function below:

/**
 * @param externalSectionId - the id of externalSection that will want to call setComponentValue
 * @param componentId - id of the component for which we want to set a new value. Webforms sends it automatically to each component under the key componentId
 * @param newValue - new value for this component
 */
setComponentValue(externalSectionId,componentId, newValue);

The set of components to which we can set a new value includes:

• GesTextField
• GesRadioGroup (important! set a value that is within the radio group's domain. Otherwise, we will get an error in the application).
• GesCheckboxSection
• GesCheckbox
• GesTextArea
• GesStatementPopup
• Combobox (id of the item we want to set)
• Slider (value from the appropriate range)
• StepSlider (value from the appropriate range)
• PlusMinus (value from the appropriate range)
• DatePicker (Long value)

Function parameters setComponentValue then Strings. An example call to the function is shown below:

setComponentValue('GesComplexComponent1.GesExternalSection1','GesComplexComponent1.GesTextField3', 'aaaaaa');

Passing a value to GesStatementPopup:

• the value should be a string containing a JSON object with the following structure: { MID_OŚWIADCZENIA1 : value, MID_OŚWIADCZENIA2 : value ... }
• the value passed in the object must be of type boolean (true / false)
• will be changed only in the object
• example call:

  setComponentValue('GesComplexComponent1.GesExternalSection1','GesComplexComponent1.GesStatementPopup1', '{ "GesComplexComponent1.item1": true }')