6.7.5 Implementation of a Side Panel Application with HTML and JavaScript

NWBC provides an application programming interface (API) that is accessible in the HTML document object model (DOM). This API is called DataContext. It can be accessed by using JavaScript variable Window.external.DataContext.

For reference, you can view a sample application in NWBC. In NWBC, hold the CTRL key and open the Help menu. Choose  Tools  Side Panel  Data Context AppData Viewer . Then choose View Source from the context menu.

The data context is a data container for exchanging data between the application in the content area and the side panel application. The data (simple key-value pairs) is organized in namespaces. NWBC reserves the following prefixes of namespaces:

• SHELL_

• CANVAS_

• SIDEPANEL_

• NWBC_

• LSAPI_

• LSHAPE_

• __global__

Applications that write data into their own data context must use namespaces that do not start with these reserved prefixes.

The following namespaces are filled by NWBC:

• SHELL_currentSystem

  This namespace contains information about the current system, user, language, and so on.

• SHELL_currentApp

  This namespace contains information about the current application.

• CANVAS_appData

  This namespace contains data written without an explicit namespace parameter in the following ways:

  • SAP GUI extraction

  • ABAP LSAPI calls (to extract data that is not displayed in dynpros)

JavaScript code that writes directly into the data context has to specify the namespace="CANVAS_appData" parameter. The easiest way to receive the complete data context content as XML after changes is to subscribe to the relevant EPCM event. For more information about events, see 6.7.3 Refresh and Pin .

The DataContext API includes the following interfaces:

• IDataContext

  This interface provides the following methods:

  Return Value	Method (Parameters) Description
  string	read (string name,[Optional, DefaultParameterValue(null)] string @namespace,[Optional, DefaultParameterValue(null)] string namespaceReadKey) Read access of a single entry's value. To access other parameters of the entry, for example, data type, use entry . Parameters: name : mandatory name of the entry namespace : optional name of the entry's namespace. If not specified or null, the entry belongs to the __global__ namespace namespaceReadKey : optional read access key for the namespace Returns: the value of the entry or null if the given namespace or key does not exist Exceptions: UnauthorizedAccessException if the given namespace already has a different read key than the given one
  IDataContextEntry	write (string key, string value,[Optional, DefaultParameterValue(null)] string @namespace,[Optional, DefaultParameterValue(null)] string namespaceWriteKey,[Optional, DefaultParameterValue(null)] string namespaceReadKey) Write access of a single entry. The first write access to a namespace creates it. A given (or left out!) write key is used throughout the whole lifetime. A namespace is automatically destroyed if no entries exist any longer. An entry can be removed explicitly or implicitly if the original writer (for example, a DataContextUser plugin extension or a side panel application) runs out of lifetime. The lifetime of an entry is identical to the lifetime of the application in the content area. Caution Do not create namespaces starting with the reserved namespace prefixes described above. Parameters: key : mandatory name of the entry value : mandatory value, may be null namespace : optional name of the entry's namespace; If not specified or null, the entry belongs to the __global__ namespace. namespaceWriteKey : optional write access key for the namespace namespaceReadKey : optional read access key for the namespace Returns: the written entry that can be used to set or access additional attributes Exceptions: UnauthorizedAccessException if the given namespace already exists and has a different write key than the given one
  void	remove (string key,[Optional, DefaultParameterValue(null)] string @namespace,[Optional, DefaultParameterValue(null)] string namespaceWriteKey) Deletion of a single entry or all entries of a given namespace Parameters: key : mandatory name of the entry. * denotes all entries (only in combination of a namespace). namespace : optional name of the entry's namespace. If not specified or null, the entry is only searched in the __global__ namespace namespaceWriteKey : optional write access key for the namespace Exceptions: UnauthorizedAccessException if the given namespace has a different write key than the given one
  void	publishChanges ( ) Signals the end of writing to the data context. This call is mandatory after modifying (write or delete) the data context. Without this call, other listeners do not get an update notification!
  IDataContextEntry	entry (string name,[Optional, DefaultParameterValue(null)] string @namespace,[Optional, DefaultParameterValue(null)] string namespaceReadKey,[Optional, DefaultParameterValue(null)] string namespaceWriteKey) (Advanced) read access of a single entry. To access the value of the entry, use read . Parameters: name : mandatory name of the entry namespace : optional name of the entry's namespace; If not specified or null, the entry belongs to the __global__ namespace. namespaceReadKey : optional read access key for the namespace namespaceWriteKey : optional write access key for the namespace, needed when later trying to modify the entry Returns: the entry object that gives further access to all the parameters Exceptions: UnauthorizedAccessException if the given namespace already has a different read key than the given one NotSupportedException if the given name does not exist in the given namespace
  ImmutableArray *	listNamespaces ( ) Generic API to enumerate all namespaces Returns: the names of all contained namespaces
  ImmutableArray *	listKeys (string @namespace,[Optional, DefaultParameterValue(null)] string namespaceReadKey) Generic API to enumerate all entries within a namespace. Parameters: namespace : the name of the namespace namespaceReadKey : optional read key Returns: the names of all fields of the corresponding namespace Exceptions: UnauthorizedAccessException if the given read key does not match the read key of the namespace
  void	asyncRefresh ( ) Asynchronously refreshes the core set of content. Among this, it triggers an update of a DataContextUser plug-in extension (if available) and SAP GUI data extraction. Only if the data context has changed, this leads to a ChangedWithXml event.
  string	toXml ( ) Generic API to access the whole data context. Only entries without read protection are returned, that is, from namespaces that do not have a read key set. Returns: an XML string containing all freely accessible entries, structured by namespace
  void	fromXml (string xml, bool mergeWithExisting) Import whole data context except for namespaces SHELL_currentSystem and SHELL_currentApp. Parameters: xml : XML in the same format as returned by toXml mergeWithExisting : keep existing entries and add new entries, overwrite identical entries only
  void	subscribe (string @namespace, string callbackMethod,[Optional, DefaultParameterValue(null)] object callbackObj) As soon as somebody calls publishChanges , the JS handler is called. Note If the bag is not created yet, the subscription is remembered and as soon as the next bag with this name is created, the subscriptions are set for this new bag. This should guarantee the same behavior from consumer side if the side panel application is executed earlier and executed later than the application in the content area. Parameters: namespace : unique name of a namespace that need not exist yet. It can be created later. callbackObj : object whose method is called. If null, the global JS function callbackMethod is executed. callbackMethod : name of JS function that is called when somebody calls publishChanges . If the JS function is already described, nothing is to be done.
  void	unsubscribe (string @namespace, string callbackMethod,[Optional, DefaultParameterValue(null)] object callbackObj)

  * Return value ImmutableArray provides the following:

  • Method object at (int index)

  • Property int count [get]

• IDataContextEntry

  This interface provides the following properties:

  • string value [get, set]

  • string dataType [get, set]