Previous topic

Input Types

Next topic

Human Interface Guidelines

Version Compatibility

APS helps applications keep compatibility with various platform versions and user panels - CP and UX1.

Compatibility of Platform Versions

APS UI environment in the user panel fully supports application UI developed for the user panel of the previous versions of the platform. It means the following:

  • An application UI that works in CP of the older platform version, for example, 7.3, will continue working in the platform “7.4 / CP” environment too.

  • An application UI that works in UX1 of the current platform version 7.4 will work in UX1 of the future platform versions.

Compatibility of User Panels

Although there are many crucial differences between the user panels, they are compatible in the following way:

  • APS UI environment in UX1 fully supports an application UI initially oriented on CP. This helps applications keep an old code as reusable for both user panels.

  • View source JavaScript files created initially for UX1 can be embedded into view source HTML files used in CP as explained in the next section.

Using UX1 Views in CCP

Overview

Suppose, there are views initially developed for UX1, but you also need to use them in the customer control panel (CCP). At the same time, you do not want to invest in developing and then supporting a code specially for CCP.

The APS SDK method aps/createCCPv2ViewForCCPv1 allows you to use in CCP the JavaScript files initially created for UX1 (compliant with the single-page technology).

Note

Since APS SDK is backward compatible, UX1 will accept and work with the package created for CCP. However, the UX1 users will miss the advantages of the newer panel in terms of performance and the widget view.

To gain advantage of both user panels, select one of the following ways:

  • Create a universal package that will automatically adjust the navigation and views for the user panel currently used.

  • Clone the package for the CCP and support the two packages, one for CCP and the other for UX1.

Universal Package

The main case is to use a single APS package, compliant with and effective for both user panels to use the advantages of both panels. For that purpose, update the package originally created for UX1 as follows.

  1. Declare a separate navigation tree plugged to CCP with the same structure as the existing tree plugged to UX1. In the new tree, do the following:

    • Plug the tree to CCP.

      <plugs-to id="http://www.aps-standard.org/ui/service" />

    • Change IDs of all navigation elements (navigation, items, and views) to ensure the uniqueness of IDs in the scope of the APP-META.xml file.

    • Assign HTML files as source for all views declared in the tree.

  2. Create HTML files declared as sources for views in metadata. In every new HTML file, call the aps/createCCPv2ViewForCCPv1 method to convert and include the corresponding JavaScript file to the HTML file as illustrated by the example later in this document.

  3. Adjust the navigation to use view IDs declared in the navigation tree that is currently used. Inside a view, the has('aps-bs') function returns true if the view is loaded to UX1, otherwise it returns false. This helps you to identify the current tree and use the view IDs from this tree. For example, if in UX1 a view ID is “servers” and in CCP it will be “servers-ccp”, the gotovew call will look as follows:

    aps.apsc.gotoView(has('aps-bs') ? "servers" : "servers-ccp");

  4. In every view JavaScript code, find the widgets incompatible with CCP and find a replacement for each. In the view code, use the has('aps-bs') function to identify the user panel, either UX1 or CCP, in order to use the relevant widget. For example, the init method returns one of two sets, each defining a view layout for its current user panel:

    var widgets = [ /* Layout for UX1 */ ];
var widgetsCCP = [ /* Layout for CCP */ ];

return has('aps-bs') ? widgets : widgetsCCP;

Cloned Package

You can clone an APS package originally created for UX1 and update the cloned package to use it for CCP only. This is hard to implement on the same platform from the technical and business standpoint, since you will actually use two different APS applications with different APS IDs integrating the platform with the same cloud application. However, if the cloned package will be used in a separate platform where only CCP is used, then this might be the simplest one.

As compared with creation of a universal package, the method requires less customization steps:

  1. Plug the navigation tree into CCP.

  2. In the tree, update the declaration of views to declare HTML files as sources.

  3. Create HTML files. In every HTML file call the conversion method aps/createCCPv2ViewForCCPv1.

  4. Replace the widgets incompatible with CCP with the relevant widgets.

Example

For testing, you can take a very simple APS package, for example the one (download) created in the Get Started demo project for UX1 and walk through the following steps to make the application UI work in CCP.

  1. In APP-META.xml, make new navigation tree plugged into CCP and refer to HTML files as source, for example:

    <navigation id="ccp" label="VPS Management">
   <plugs-to id="http://www.aps-standard.org/ui/service" />
   <var type-id="http://aps-standard.org/samples/starter1p/management/1.0"
      name="management" />
       <view id="servers" label="Servers" src="ui/servers.html">
           <view id="server-new" label="New VPS" src="ui/server-new.html">
               <controls>
                   <cancel />
                   <submit />
               </controls>
           </view>
       </view>
</navigation>

    Keynotes:

    • Use the <plugs-to> element to plug the navigation tree to CCP as specified in the above code.

    • All view source files must be new HTML files instead of JavaScript files you used in the navigation tree plugged into UX1.

  2. In the ui/ folder, create all HTML files specified as source in the navigation tree. Each of those files must use the aps/createCCPv2ViewForCCPv1 method to convert and include the respective JavaScript file. The following is the content of the ui/servers.html file that converts and includes the ui/servers.js file:

    <!DOCTYPE html>
<html>
<head>
<script src="/aps/2/ui/runtime/client/aps/aps.js"> </script>
<script>
   require([
      "aps/createCCPv2ViewForCCPv1",
      "aps/ready!"
      ], function (createCCPv2ViewForCCPv1) {
          createCCPv2ViewForCCPv1('./servers.js', 'servers-view-compatibility');
   });
</script>
</head>
<body>
</body>
</html>

    The second parameter in the createCCPv2ViewForCCPv1() method is an arbitrary unique view ID.

  3. Build the new package and deploy the APS application in accordance with its deployment guide. You can use its UI in either, CCP or UX1. Keep in mind that in UX1 the widgets will look as if they are in CCP.