Skip to Content

This blog deals with creating custom Web DynPro controls for a Mobile 7.1 device in a disconnected scenario.

Overall, custom controls can be tricky to create and deploy initially. In addition, there are many steps, such as memory disposal, that you must take care of yourself. Custom controls add significant flexibility to your application, however, the standard SAP controls are easier and quicker to implement.

 

The following is largely based on documentation sent to me from SAP. I’ve gone through and modified it to add my own thoughts and experiences.

 

 

h2. Creating a simple SWT custom control


Overview


There are three pieces needed to integrate a custom into
WebDynpro Lite framework. The following classes must be made:

  • IUIElementFactory: To instantiate
    and configure the control during runtime.
  • UiElementMethodCallAdapter:
    For interaction with the WebDynpro Lite framework, e.g. for context
    binding


Requirements for native controls


There are no special requirements for native controls, especially because it
is possible to write all needed code to instantiate it inside an
IUIElementFactory. Every SWT control needs to be a subclass of org.eclipse.swt.widgets.Control. Of
course it must not contain the SWT main loop itself.

Custom controls can be simple widgets like buttons but also composite widgets
or even complete SWT applications. Be careful: Larger widgets are more
independent of WebDynpro Lite. This can be an advantage or a disadvantage.


Create the IUiElementFactory


Please refer to the Javadocs of UIElementFactory to see an
extensive description.

 

 public class SampleFlatButtonCustomWidgetFactory implements IUIElementFactory {

        /**
         * Sample Implementation for an IUIElementFactory. Please see implementation and comments below for details.
         */
        public UIElement createNewInstance(int type, String subType, UIContainer parent,
                Map style) {

            //create the native control, and (important) specify parent cotainer, also apply all style parameters
            Button button = new Button(getSwtCompositeForWdliteContainer(parent),
                    SWT.BORDER);

            //The custom control has to provide a
            //implementation of an UiElementMethodCallAdapter. It contains all code for interaction between the custom control and the WebDynpro Lite framework
            FlatButtonAdapter flatButtonAdapter = new FlatButtonAdapter(button);
            //Adds the UiGenericElement which the wdlite framework used for communication with the custom control.
            //This UiGenericElement needs a UiElementMethodCallAdapter as argument.
            UiGenericElement wdliteElement = new UiGenericElement(
                    flatButtonAdapter);
            flatButtonAdapter.setUiGenericElement(wdliteElement);

            //The GenericSwtControlWrapper is needed for the SWT abstraction of the wdlite framework. Main purpose
            //is to store the control and listen and forward to events.
            //Please see Javadocs of UiElementFactory to see how events work
            GenericSwtControlWrapper wrappedSwtControl = new GenericSwtControlWrapper(
                    parent, wdliteElement, button);
            wdliteElement.setUiWidgetAndParent(wrappedSwtControl, parent);

            return wdliteElement;
        }

        public UIElement createNewInstance(int type, String subType,
                UIContainer container, Map style, String glyph) {
            return createNewInstance(type, subType, container, style);
        }

        private Composite getSwtCompositeForWdliteContainer(UIContainer parent) {
            return SWTUtils.getSwtComposite(parent);
        }
    }

 


Create the UiElementMethodCallAdapter


Please refer to the Javadocs of UiElementMethodCallAdapter
to see an extensive description. 

 

/**
     *

     * This class is a sample adapter for usage with
     * {@link SampleFlatButtonCustomWidgetFactory}. It allows to set the button
     * texts.
     *

     *
     * @author D044859
     *
     /<br />    public class FlatButtonAdapter extends BaseWdliteUiElementMethodCallAdapter implements SelectionListener, IEventSource {<br /><br />        /*
         * The native widget, needed for interaction, registering events, …
         /<br />        private final Button button;<br />        <br />        /*
         * Needed to forward events
         /<br />        private UiGenericElement wdliteUiGenericElement;<br /><br />        private IWDNode node;<br /><br />        private String buttonProb = “”;<br />     <br />        /*
         * The constructor just stores the native control and add an event listener
         * @param b
         /<br />        public FlatButtonAdapter(Button b) {<br />            this.button = b;<br />            b.addSelectionListener(this);<br />        }<br /><br />        <br />        /*
         * Do sth when a property is changed. Proeprties can be manually bound context
         * attribute values or  text / value properties specified in the ui or in the wdDoModify() method
         */
        public void onPropertyChange(String name,Object value){           
            System.out.println(“property changed: ” + name +  “, value: ” + value);
            if (“textProp”.equals(name) && value != null){
                button.setText(value.toString());
                buttonProb = value.toString();
            }
        }

        //just a setter
        public void setUiGenericElement(UiGenericElement wdliteUiGenericElement) {
            this.wdliteUiGenericElement = wdliteUiGenericElement;
        }

        //just store the context node. Do anything you like with it…
        public void setContextNode(IWDNode node) {
            this.node = node;
        }

        //Translates a call from wdliteFramework to the native control
        //Please note: setText is just a typesafe convenient method of setProperty()
        public void setText(String text) {
            button.setText(text);

        }

        public void widgetDefaultSelected(SelectionEvent arg0) {
        }
       
        public void setWidth(int width) {
            System.out.println(“width: ” + width);
        }

     
    }

 


Context Mapping


The context mapping for custom controls works exactly the
same way as for “normal” WebDynpro Lite controls, so any
documentation for these apply also for custom control. In general each custom
control gets access to one complete com.sap.tc.mobile.wdlite.progmodel.core.context.ContextNode
which can contain any number of child nodes.

 

In other words, if the control needs access to several WebDynpro context nodes, than  those nodes must be child nodes of a single parent node. The custom control must be binded to the larger parent node.

 

Please note the following addition to the setNode method of the adapter

 

//just store the context node. Do anything you like with it…
    public void setContextNode(final IWDNode node) {
            final IContextNodeCursorListener listener = new IContextNodeCursorListener()   {
            public void listenContextNodeCursorChanged(ContextNode node) {
                TUsersNode inputNode = (TUsersNode) node;
                composite.setUserNode(inputNode);           
            }
        };
        ((ContextNode)node).addContextNodeElementListener(listener);
           
        DisposeListener disposeListener = new DisposeListener() {
            public void widgetDisposed(DisposeEvent arg0) {
                ((ContextNode)node).removeContextNodeElementListener(listener);
            }
        };
        composite.addDisposeListener(disposeListener);
   
    }

 


Listening and registering for Events


Implementing the event handling code of the custom control:

The custom control developer has to handle and listen to all events of the
custom control manually. This means writing the usual SWT code in the
implementation of UiElementMethodCallAdapter of the control. Events which needs
to be forwarded to the ui must be additionally wrapped into an UIEvent and forwarded
to the doHandleCustomControlEvent() method of the according UIGenericElement,
just take a look at the provided examples on howto doing this.

Note: Since only one event type (onAction) is supported, the custom control
developer has to add additional data so an application developer can
distinguish between multiple events of a custom control.

//SWT Event Listener: Translate the native SWT event into a wdlite event an forward it. Note you have to implement the empty IEventSource interface to do this.
public void widgetSelected(SelectionEvent arg0) {
        UIEvent wdliteUiEvent = new UIEvent(this, IEvent.EVENT_ONACTION);
//add any data to the event, can be accessed by application developer
wdliteUiEvent.setEventData("someEventData", "yourcustomData");
//allows to distinguish between multiple events of a custom control
wdliteUiEvent.setEventData("eventType", "btnClick");
wdliteUiGenericElement.doHandleCustomControlEvent(wdliteUiEvent);
}

 

 

h4. Don’t forget to clean up!

Add dispose listeners to your composites where you dispose of all of your UI elements.

 

 


Adding a custom control into a wdlite application.


Following steps are necessary to do this:


Add the custom control to a view


All custom controls are represented by the Interactive Form
control. You can find it in the list of controls in the Integration folder. If
the Interactice Form is not present there you have to manually delete or rename
the ProjectProperties.wdproperties file from /src/packages folder. After this
you need to restart your ide or atleast close and reopen the current project.
After doing this many new controls (most of them can not be used) are present
in the control list.

The Interactive Form control is a placeholder for any custom control. It is
used because it is not possible to add new controls to WebDynpro. After adding
the Interactive Form to the view you can change the common properties in the
properties view. All properties which are specific to a custom control can not
be changed here. This must be done in code.

h4. Add events mapping to custom control (optional)

Select your custom
control in the Layout tab of your View and open its properties. Create an
action method for the onSubmit event (onCheck event can not be used). The
defined action listener will be called for all events of a custom control. You
just have to implement the needed code in this action listener method.

Note: There is only one action method available which must be used for all
events of a single custom control. 


Setting and adapting the custom control properties


All non standard properties of a custom control must be set
manually in the #wdDoModifyView(App1ViewView view, boolean firstTime) method of
the corresponding *View class. It is possible to use the
*ViewView#getViewItem(name) method or a typesafe one to access the single
ViewElement.

You have to do two things here: Setting the id of the customControl (1) to do
the association and set any number of properties (2).

//wdDoModifyView of an View: Allows to set the type of a custom control, forward properties and bind to context attributes
public void wdDoModifyView(App1ViewView view, boolean firstTime) {
//@@begin wdDoModifyView()
  //important: application will fail if not set. The custom control has to document the id to use.
idOfCustomControl  = "FlatButton";
view.getSomeCustomControlViewItem().setUIControlSubType(idOfCustomControl);
  //set a custom parameter which is forwarded to the custom control
  view.getSomeCustomControlViewItem().setPropertyValue("nameOfFancyHeadline", value)
 
  //bind to a context attribute: binds the attribute someAttribute of the node someNode to the custom control property someProperty
   view.getSomeCustomControlViewItem().bindProperty("someProperty",(ContextNode)someNode, "someAttribute");
 
//@@end
}


Declare the dependencies inside the application


Right now only the id(s) of the custom control(s) is associated
with elements in the application. To be able to instaniate the controls, the
container also needs the classnames of the factories which create the controls.
This information is specified in the file custom_controls.properties which must
be located in the root classpath of the application (e.g. placed inside the
/src folder). This file contains your custom control factories and a comma seperated list of control IDs recognized by that factory. Sample content:

Wdlite-custom-control-factory-class-1=com.sap.SampleFlatButtonCustomWidgetFactory

Wdlite-custom-control-factory-ids-1=FlatButton,SomeOtherControl

This will specify class com.sap.SampleFlatButtonCustomWidgetFactory is responsible for
creating the custom controls with ids “FlatButton” and “SomeOtherControl”. You can
find detailed information in the Javadocs of
com.sap.tc.mobile.wdlite.customcontrols.detector.CustomControlsPropertiesLoader.


<!>

<!></p>


Packaging


Custom controls must be packaged either inside an
application or as individual component (preferred). For doing the first one it
sufficient to copy all the custom controls classes to the application and add
the needed dependencies. This approach is easy but has several disadvantages, mainly
the more difficult maintanance.

The 2nd way is slightly more complicated but allows one to easily reuse the custom
control into any number of applications. Following steps are needed:

  1. Creating a new java dc
  2. Add the code of the custom
    control to the java dc
  3. Declare all needed
    dependencies and ensure the DC compiles without errors: Tc/mobile/oca/api
    + tc/mobile/wdlite/customcontrols/api + tc/mobile/wrapper/eswt

Create a new assembly public part and ensure
     that the complete code is contained in this public part, e.g. by exporting
     the whole Java Package Tree.

Create a new Mobile
     Application as wrapper for the custom control. This is necessary since the
     custom control is no separate deployable unit, this will probably change
     in future (not in 2007) but for now this additional step is necessary. Add


     the previously created custom control java dc as dependency to this
     application component. Note:
     You have to do this inside the Development Component Perspective since it
     is not supported inside the Mobile Application View right now. This
     application component needs at least one public part (can be empty) to be
     able to be used as mcd dependency (else mcd dependency will not be
     created, verify this in the OCA perspective: Point to SomeComponent –and
     select “Deployment Descriptors” in the context menu)

You do not (this changed from previous description) have to add a
     dependency from the component of your wdlite application to the application component which wraps the
     custom control. This has to be done in the DC Perspective since the OCA
     designtime does not support this yet. Without doing this the custom
     control is not accessible for the application on runtime.

Add a manual dependency in the mcd.xml of the UI component to the
     application dc which wraps the custom control.


<mcd_dependencies> </mcd_dependencies>

  1. Please note also the
    custom_controls.properties exists only in the ui components root classpath
    and verify it is *not present on any
    other place in the classpath* (e.g. in a 2nd cc in the /lib folder) !!!
    If the custom_controls.properties is present more than one time, only the
    first found can be loaded. This can lead e.g. to the error message “Unknown
    UI Element type: -1″ when starting the application. (See the faq
    below for additional notes about this error message).
  2. In case you have errors on
    application startup (mainly class not found exceptions) you can check
    manually the deployed files: Redeploy your ui component and your custom
    control app dc and open the runime container inbox folder. Check the
    custom control app dc contains all class files of the custom control (if
    no classes are present, the custom_control java dc does not contain an assembly
    public part), Check the ui component mcd.xml contains the dependency to
    the mcd.xml. If not present create it manually and check if this solves
    the problem in the first place. (This issue can be caused by a missing
    empty compilation public part in the custom control application dc)

 

h2. Tips and Tricks

*Data binding </p><p class=”MsoNormal”> Rather than bind your control to the context, you could simply grab a reference to the node. This can be done because the context is a singleton. You can simply instantiate the context and grab data from the node. The context listener is valuable because it allows a control to react when the webdynpro UI changes values in the context.</p><p class=”MsoNormal”>For example:</p><p>ComponentController controller = ComponentController.getInstance();<br />ComponentControllerContext.TContextNode sharedContext = (ComponentControllerContext.TContextNode) controller.getContext().getRootNode(); <br />ComponentControllerContext.TUserElement userElement = (ComponentControllerContext.TUserElement) sharedContext.nodeUsers().getElementAt(0);</p><p> </p><p>Service Objects</p><p>Again, service objects are singletons. You can instantiate them directly, however, you need to make sure you add them as dependencies.</p><p> UserserviceModel model = (UserserviceModel)OcaRoot.getInstance().getModel(UserserviceModel.class.getName());<br />UserService service = model.getServiceUserService();<br />Collection areaCol = service.queryGetUsersByFirstName(“Bob”);</p><p> </p><p>Affecting the Webdynpro UI *

Webdynpro singletons can be used to alter your views from the custom control, or to invoke business methods contained in your view controller.

//Grab a reference to the view to change buttons or other UI
//elements
EditUserView view = (EditUserView) EditUserView.getInstance();
view.getBtnBackViewItem().setText(“Back”);

//Grab a reference to the view controller, perhaps to
//fire a plug or leverage business logic
EditUser editUserViewController = EditUser.getInstance();
editUserViewController.wdFirePlugToAlertView();

 

 

 

To report this post you need to login first.

4 Comments

You must be Logged on to comment or reply to a post.

  1. srikumar venkatraman
    Dear Mike Brosseau,

    Thanks for the blog that you have published. But i am not able to comprehend the same incapcitated by lack of knowledge in webdynpro, eSWT.

    The scenario that i am looking out for is to embed a signature recognition control (eSWT if provided) into a webdynpro application for MObile 7.1.

    Another point we need clarification on is on ur steps of

    1) extending org.eclipse.swt.widgets.Control to create a custom control and also

    2)class SampleFlatButtonCustomWidgetFactory implements IUIElementFactory. i am not able to documentation for the IUIElementFactory class in the eSWT documentation (eRCP 1.2 JavaDoc)

    I assume that i looking at the correct version of the document that you have given example for. if not please advice.

    thanking you,

    Srikumar V

    (0) 
    1. Mike Brosseau Post author
      1 – For more information on creating your SWT control, please check out http://www.eclipse.org/swt . There you can find several examples and tutorials.

      2 – IUIElementFactory is a class ( com.sap.tc.mobile.wdlite.renderer.api.IUIElementFactory) provided by SAP to build SWT controls within the application.

      (0) 

Leave a Reply