Go VE: Converting Your View's Customization Package to Primo VE

Main Principles and Differences between Primo and Primo VE

Before you begin to make any changes to your customization packages, it is helpful to understand its implementation differences in Primo VE:

• The structure of the html directory and the name of the main file has changed in Primo VE:

  • Primo:

    VIEW_CODE

        css

        html

            home_en_US.html

        img

        js

  • Primo VE:

    VIEW_CODE

        css

        html

            homepage

                homepage_en.html

        img

        js

• Primo VE and Primo share the exact same code base for the UI, but in some cases, functionality in the user interface was implemented differently in Primo VE. For example, the implementation of Get It and View It services are implemented with the same design as the rest of the application instead of being implemented with an iframe.

  This means that CSS customizations in the AlmaMashup via Alma will have no effect on the Primo VE services, and will mostly be unnecessary  since the services will inherit the general Primo VE theme.

• A significant part of the customization package allows customers to write their own components in angularJs and hook them to predefined “after” hooks in the UI. For more information, see The Primo New UI Customization Workflow Development Environment. in GitHub.

  For Primo VE, the mechanism used for hooking to the directives will not require any changes, but if you have customized any code, it may fail in Primo VE in the following cases:

  • If your code calls an internal Primo API with a Primo path. For more details, see Go VE: Converting Primo APIs for Use in Primo VE. 

  • If your code parses sections in the PNX response that are not part of the Primo VE PNX (such as the search and browse sections). For more details, see Go VE Converting Primo APIs for Use in Primo VE.

  • Referencing resources (such as images and HTML files) in the customization package statically using the Primo View Code.

  • Any code that relies on specific data that is not part of the out-of-the-box PNX in Primo VE (such as local fields or data source codes/record IDs).

Documentation and Training

In preparation for this task, it is recommended that you familiarize yourself with the following documentation and training videos:

• Primo VE Customization - Best Practices

• Primo Studio for Primo VE

• Configuring the User Interface

Workflows for Adjusting Your Customization Packages in Primo VE

Because each community may consist of varying levels of expertise with working with the customization packages, the CSS, and Javascript, we have provided different workflows based on expertise to adjust your customization packages:

• For librarians with a basic knowledge of CSS and are able to copy JavaScript and make simple modifications:

  1. Open your Primo and Primo VE views in side-by-side browsers to allow easy comparison.

  2. In both browsers, perform the following:

     1. Open the browser’s developer tools (F12).

     2. Examine the Network tab after browsing through different parts of the application and look for error network traffic(marked in red).

     3. Examine the console tab (filter the log with the term custom.js) to catch errors in the customizations package.

     4. Examine the functionality and look for differences.

     5. Append the &noCustomization=true flag to the URL to see what your UI looks like without any customizations. For example:
        
        https://<base-URL>/primo-explore/search?vid=NORTH&lang=en_US&offset=0&noCustomization=true
        
        if the problem persists, open a Support ticket since the issue is not related to your changes in the customization package.

  3. For each difference between Primo and Primo VE, refer to the examples below to solve the issue, and then retest.

• For skilled developers who probably use the Primo Development Environment  or a similar tool:

  1. Point your Development environment to the new Primo VE view by changing the proxy definition:

     In the gulp/config.js file, change the PROXY_SERVER parameter to the new Primo VE URL using the following format:

     var PROXY_SERVER = http://your-server:your-port

     For SSL environments, use HTTPS:

     var PROXY_SERVER = https://your-server:443

     Make sure to use your real Sandbox or Production Primo Front-End URL.

  2. For Primo VE customers, use the –ve flag when starting your server:

      gulp run --view <the VIEW_CODE folder> --ve

  3. Run your default tests (manual, automated) if exists – if not use the Procedure above to identify problems.

  4. Fix the code, create a package, and then upload it on the View Configuration page.

Example #1: Call to an Internal Primo URL

The following code has a call to an internal Primo URL with a Primo path:

The following changes need to made in the PRIMO VE URL:

• replace the primo-explore path entry with discovery.

• the tab parameter should include the correct name of the slot used in Primo VE.

Changes to the URL are in green. For example:

Example #2: Parsing an Unsupported PNX Section

The following code refers the search section in the PNX response.

To resolve this issue, you should make the following adjustments:

1. Remove the highlighted portion of the code since the recordid is stored in the control section, which is returned for both Primo and Prmo VE.

2. The TN prefix (which stands for Third Node) for the recordid in the Search section of the PNX identifies a Central Index record (PC or CDI) and is not relevant in the Control section. A better way to identify Central Index records is to use the context or adaptor entry from the item:

   

   With the adjustments, the code should change to the following:

   if (vm.parentCtrl.item.pnx && vm.parentCtrl.item.pnx.control && vm.parentCtrl.item.pnx.control.recordid &&
       vm.parentCtrl.item.pnx.control.recordid[0])

   {
       recordId = encodeURIComponent(vm.parentCtrl.item.pnx.control.recordid);
   }

   In general, you can use the following code to identify a Central Index record:

   var isCDI = item && item.context && item.context === 'PC'; 

Example #3: Static References in HTML

The following HTML code has a static reference that contains a Primo View Code:

To resolve this issue, you can use either of the following options:

• replace MyView with the view code used with the Primo VE. Note that the view code now includes both the institution ID and view ID (for example, MyInst-MyView).

• Convert the path to a relative path, depending on the actual link and resource:

  <img src="../../img/virtual_library_banner.jpg" alt="Virtual Library" width="100%" height="100%" style="margin:0px;">