Skip to main content
ExLibris
  • Subscribe by RSS
  • Ex Libris Knowledge Center

    Primo VE Customization - Best Practices

    Return to menu

    Introduction

    In order to provide users with the best experience in Primo VE, Ex Libris carried out an extensive user study that included the following tasks to help redesign the classic Primo user interface:
    • Analyzed search logs
    • Conducted surveys of librarians during workshops
    • Interviewed users at different academic levels and from various countries and disciplines 
    During the design and development of the new interface, accessibility was tested as well as its responsiveness on several devices to make sure that the new design met the goals based on the results of the user study.
    Because every library has its own needs and brand, we have implemented a new customization framework that allows customers to tap into predefined hooks for each UI component, thus allowing them to customize each component as needed.
    In order to ensure a quality user experience and optimal system performance, we encourage customers to test every change that they make for both accessibility and responsiveness in their staging environments before uploading any packages to their production environment.

    Additional Resources

    The following resources may be helpful in the customization of the new Primo UI:

    Inspecting Web Elements with Your Browser

    Most Web browsers provide developer tools that allow you to inspect the currently-loaded HTML and find specific elements on a page. In most browsers, you can either click F12 or right-click the page and then select the Inspect Element option.

    In order to customize Primo VE, you should be familiar with the following: CSS, HTML, JavaScript, and AngularJS. Depending on your experience with each of these languages and frameworks, you will be able to perform more complex customizations.

    AlmaCustomization.png

    Full Display Page - Get It Section

    The following procedure shows how to use the browser's inspect tool to locate the code table used to define a label in Primo VE.

    To locate a label on the page:
    1. On the page that you want to inspect, press F12.

    2. Click the inspect item button (#1) and then click the label (#2) that you want to modify. Each component should highlight as you move the cursor over the item.

      InspectElementExample.png

      Inspection Brief Results Page
    3. In the HTML tab, you should see the label and its corresponding code (#3). If you don’t see a translate parameter, you can instead search for the label’s description on the All Code Tables page.

    4. On the All Code Tables page (Configuration Menu > Discovery > Display Configuration > Labels), either search for the code or description (the actual display label).

      The following figure shows and example of a search for a code:

      PVE_AllCodeTables_Search_For_Code.png

      Code Search Example

      The following figure shows and example of a search for a label:

      PVE_AllCodeTables_Search_For_Label.png

      Label Search Example

    Using the UI Customization Package Manager

    The Customization Package Manager allows you to upload and manage customization packages, which allow you to brand and further customize Primo VE. If no packages are loaded, the system will use only the out-of-the-box configurations.

    • Database files (.db) are not permitted in your customization package. If the following error occurs while uploading your ZIP file, remove all .db files:

      Validation error: File type db is not allowed in the zip file
    • You may have to change an option in Windows to display hidden files if you cannot see any .db files in your customization package folder.

    To ensure that a customization package integrates properly with Primo VE, make sure that its ZIP file is structured as follows:

    PVE_CP_Structure.png

    Customization Package Structure
    • <View_Code> – The top folder of your customization package. Make sure that you change the name of the top folder to your institution's view code, which should be in the following format: <institution_code>-<view_code>.

    • css – This subfolder contains the custom1.css file, which includes your CSS rules. These rules will override corresponding rules in the default CSS.

    • img – This subfolder contains all customized images for Primo VE. To ensure that the correct image appears in Primo VE, make sure that you use the same file name as the original.

    • js – This subfolder contains the custom.js file, which includes your scripts.

    • html – This subfolder contains the following subfolders, which store all customized HTML files for Primo VE:

      • homepage – The homepage_en.html file allows you to customize the area of the page below the search box on the Primo VE Home page. To support other languages, you can create and upload new HTML files with the relevant language code. For example: homepage_fr.html. For more information, see Home Page.

        Primo VE Home Page
        • The system will not use content inside <script> tags.

        • Since this code will be nested inside the main HTML code, it is recommended to wrap this code with a <div> tag (insets of the <html> tag).

      • help – The help_en.html file allows you to create a help page for your view. To support other languages, you can create and upload new HTML help files with the relevant language code. For example: help_fr.html. For more information, see Creating a Custom Help Page. Since a help page is not provided out of the box, you will need to add the help directory to your customization package.

    You can create a customization package from either the View Configuration page or Primo Studio, but you will need to use the View Configuration page to deploy the customization package for both methods. For more information, see the following sections:

    Accessing Primo Studio

    Primo Studio allows you to interactively customize some aspects of your view and create a customization package for deployment with the View Configuration page in Primo VE. For more information, see Primo Studio for Primo VE.

    To access Primo Studio:
    1. Edit your view on the View Configuration page (Configuration Menu > Discovery > Display Configuration > Configure Views).

    2. Select the Manage Customization Package tab.

    3. Select Go to Primo Studio in the Create a Customization Package section.

    Creating a Customization Package

    To create a customization package:
    1. On the Views List page (Configuration Menu > Discovery > Display Configuration > Configure Views), edit your view.

    2. Click the Manage Customization Package tab.

      PVE_PrimoStudio_ManageCustomizationPackageTab.png

      Manage Customization Package Tab
    3. Click Download to download the customization package. If this is the first time, download the template package. Otherwise, download the current package to make sure that you are using the latest version.

    4. Unzip the file.

    5. Make sure that the top folder of your package's zip file is the <View_Code> folder, which must have the following format: <institution_code>-<view_code>. For example: PRMO_OAP_INST-Alma.

    6. As needed, customize the configuration files and folders that are associated with the home page, images, and CSS. You must retain the file structure and names of files that you are overriding. Refer to the following sections for details on how to brand and make simple changes to your view:

    7. Zip the view code folder.

      PVE_CustomZippedPackage.png

      Zipped View Code Folder

      For Windows users, it is recommended that you use a compression tool such as 7zip or Winrar instead of Windows Send to > Compress folder to avoid upload errors.

       

      For Mac users, use the following procedure to zip and remove any hidden .DS_Store files:

      1. Open the Terminal application under Applications > Utilities.

      2. Move to the parent directory of the folder that you want to compress. For example: cd /Users/<user name>/<parent folder>

      3. Enter the following command to compress the file: zip –r <target file>.zip <My_View> -x "*.DS_Store"

    8. Specify the name of the zipped package and click Upload.

    9. Click Save to the deploy the changes.

    10. Refresh your view in the Web browser and test your changes prior to uploading the changes to the production server.

    Adding a Clickable Logo

    The Manage Customization Package tab on the View Configuration page (Configuration Menu > Discovery > Display Configuration > Configure Views) allows you to upload a new logo and define a link that opens a page when user's click the logo. The following image formats are supported: PNG and SVG.

    IE11 may not fully support the display of SVG images.

    To upload a new logo:
    1. Edit your view on the View Configuration page (Configuration Menu > Discovery > Display Configuration > Configure Views).

    2. Select the Manage Customization Package tab.

    3. In the Upload Logo section, perform the following steps:

      1. Select an image to upload in the Upload Logo File field.

        The system places the following restrictions on the logo file:
        • The file format of the image must be .png or .svg.

        • The height of the image cannot exceed 100 pixels.

        • The width of the image cannot exceed 300 pixels.

        • The size of the image cannot exceed 30 KB.

      2. Select Upload.

        If you want to remove the clickable logo, select Remove Logo.

      3. If you want the image to be clickable, specify the redirection URL in the Logo Clickable URL field.

    4. Select Save to save changes to the customization package.

    Customizing Image Files

    Any of the out-of-the-box images can be customized by creating or modifying a view’s package, placing the customized image under the img folder, uploading the updated package to the server, and then deploying the package. Here are some of the commonly customized images for the purpose of branding:
    • library-logo.png – Contains the library logo.
    • favicon.ico – Contains the favicon.
    • icon_<resource_type>.png – Contains the image for the specified resource type <resource_type>. For example: icon_audio.png

    CSS Components and Customizations

    This section identifies the major CSS components for each page of the new UI and provides an example of how to move the facets to the left side of the page using CSS.

    Home Page

    This section identifies the major components of the Home page.

    HomePage_CSS2.png

    Home Page Components
    1. .prm-primary-bg.prm-hue1, prm-search-bar.prm-hue1, prm-spinner.prm-hue1.overlay-cover.light-on-dark:after, prm-topbar .top-nav-bar{}
    2. .prm-primary-bg, prm-search-bar, prm-spinner.overlay-cover.light-on-dark:after{}
    3. view_code/html/homepage_en.html
    If you want to display drop-down lists for the view's default tab and search scope in the search box initially, include the tab parameter as follows in the new UI's URL:
    http://<Primo_URL>/primo-explore/search?vid=<view_code>&tab=<default_tab_name>
    If you want to display a drop-down list for a specific search scope initially, include the search_scope parameter as follows in the new UI's URL:
    http://<Primo_URL>/primo-explore/search?vid=<view_code>&tab=<default_tab_name>&search_scope=<scope_name>

    Brief Results Page

    This section identifies the major components of the Brief Results page.
    BriefResultsPage_CSS.png
    Brief Results Page Components
    1. .alert-bar{}
    2. md-content, md-content.md-primoExplore-theme{}
      1. .section-title {}
      2. .section-content .md-chips .md-chip strong{}
      3. .md-autocomplete-suggestions .suggestion-scope, .text-italic{}
      4. .link-alt-color, .section-title prm-icon {}
    3. prm-search-result-list .results-title {}
      BriefResultsItem_CSS.png
      Brief Result Item Components
    4. prm-brief-result-container .list-item-primary-content {}
      1. prm-brief-result .item-title{}
      2. prm-brief-result .item-detail{}
      3. .item-expanded .secondary-content-holder .md-tab:nth-child(2), .item-expanded .secondary-content-holder md-tab-item:nth-child(2){}
      4. .item-expanded .secondary-content-holder .md-tab:nth-child(3), .item-expanded .secondary-content-holder md-tab-item:nth-child(3) {}
      5. .item-expanded .secondary-content-holder .md-tab:nth-child(4), .item-expanded .secondary-content-holder md-tab-item:nth-child(4) {}
      6. .item-expanded .secondary-content-holder .md-tab:nth-child(5), .item-expanded .secondary-content-holder md-tab-item:nth-child(5) {}
      7. .item-expanded .secondary-content-holder .md-tab:nth-child(6), .item-expanded .secondary-content-holder md-tab-item:nth-child(6) {}
      8. .item-expanded .secondary-content-holder .md-tab:nth-child(7), .item-expanded .secondary-content-holder md-tab-item:nth-child(7) {}
      9. .item-expanded .secondary-content-holder .md-tab:nth-child(8), .item-expanded .secondary-content-holder md-tab-item:nth-child(8) {}

    Hiding the Sign-In Link

    To hide the "Sign in to get complete results and to request items" link:
    .alert-bar {
    display:none;
    }

    Changing the Color of the Versions Link

    To change the color of the "See all versions" link:
    1. Open the Discovery UI Labels code table (Configuration Menu > Discovery > Display Configuration > Label).

    2. Edit the Results Tile Labels code table.
    3. Change the description of the nui.frbrversion.found.link code to include your color settings. For example:
      <font color="green">See all versions</font>

    Full Display Page

    This section identifies the major components of the Full Display page. For details on configuring Alma's View It and Get It services, see Branding the Delivery Tabs.
    FullRecordPage_CSS.png
    Full Record Page Components
    1. prm-full-view prm-brief-result-container{}

    Upper Menu

    This section identifies the major components of the Upper Menu.
    UpperMenu.png
    Upper Menu Components
    1. view_code/img/library-logo.png
    2. .layout-align-end-center { }
    3. prm-topbar .md-button:not(.md-icon-button) {}

    Hiding the Language Menu

    To hide the language menu:
    prm-change-lang {
      display: none;
    }

    Disabling Automatic Capitalization of Main Menu Links

    To disable the automatic capitalization of all characters in the main menu links:
    prm-topbar .md-button {
         text-transform: none;
    }

    Search Bar

    This section identifies the major components of the Search Bar.
    SearchBar_CSS.png
    Search Bar Components
    1. prm-search-bar{}
    2. /* the text color in the search box */
      input::-webkit-input-placeholder { }
      input:-moz-placeholder { /* Firefox 18- */}
      input::-moz-placeholder {  /* Firefox 19+ */}
      input:-ms-input-placeholder {}
    3. md-autocomplete-wrap input {}
    4. prm-search-bar .simple-search-wrapper .search-actions .md-button {}
    5. prm-search-bar .search-switch-buttons .md-button {}

    Moving the Facets to the Left Side

    Out of the box, the new UI displays the facets on the right side of the results page. Use the Side bar (tweak my results) position option in the General tab on the View Configuration page (Configuration Menu > Discovery > Display Configuration > Configure Views) to move the facets to either the left or the right side of the page.

    Creating a Search Box With Deep Links to Primo VE

    This example creates a search box that uses a deep link to search your institution's catalog.
    PVE_NewSearchBox.png
    Search Box
    To create a search box:
    1. Create an HTML file and include the following lines, making sure that you fill in the host name, customizable parameters (such as view code), and the fixed parameters (such as bulk size):
      <html>
      <head>
      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
      <!-- Script that converts the query string into valid parameter -->
      <script type="text/javascript">
      function searchPrimo() {
      document.getElementById("primoQuery").value = "any,contains," + document.getElementById("primoQueryTemp").value.replace(/[,]/g, " ");
      document.forms["searchForm"].submit();
      }
      </script>
      </head>
      <body>
      <form id="simple" name="searchForm" method="get" target="_self" action="https://<host_name>/discovery/search" enctype="application/x-www-form-urlencoded; charset=utf-8" onsubmit="searchPrimo()">
      <!-- Customizable Parameters -->
      <input type="hidden" name="vid" value="<inst_code:view_code>">
      <input type="hidden" name="tab" value="<tab_code>">
      <input type="hidden" name="search_scope" value="<scope_name>">
      <input type="hidden" name="mode" value="basic">
      <!-- Fixed parameters -->
      <input type="hidden" name="displayMode" value="full">
      <input type="hidden" name="bulkSize" value="10">
      <input type="hidden" name="highlight" value="true">
      <input type="hidden" name="dum" value="true">
      <input type="hidden" name="query" id="primoQuery">
      <input type="hidden" name="displayField" value="all">
      <!-- Enable this if "Expand My Results" is enabled by default in Views Wizard -->
      <input type="hidden" name="pcAvailabiltyMode" value="true">
      <input type="text" id="primoQueryTemp" value="" size="35">
      <!-- Search Button -->
      <input id="go" title="Search" onclick="searchPrimo()" type="button" value="Search" alt="Search" style="height: 22px; font-size: 12px; font-weight: bold; background: #DE6E17; color: #ffffff; border: 1px solid;">
      </form>
      </body>
      </html>

      Example search query:

      https://my-inst.primo.exlibrisgroup.com/discovery/search?query=any,contains,herring&tab=Everything&search_scope=MyInst_and_CI&vid=PRIMO_OAP_INST:MyInst&lang=en&offset=0

      If you are displaying multiple search boxes on a page, you must define separate functions and forms for each search box, making sure that the red names and IDs are unique for each search box.

    2. To test the search box, open the HTML file in a browser and perform a search. If you saved the HTML file on a Web server, use the following URL to access the search box:
      http://<web_server>/<path>/<filename.html>

    Creating a Twitter Feed

    This procedure creates a link on the home page, which opens your Twitter feed in a new tab.

    PVE_TwitterExample.png

    Link to Twitter Feed on Home Page
    To add a Twitter feed:
    1. Create an HTML link based on your Twitter feed. For details, see https://publish.twitter.com/.

    2. Edit the homepage_en.html file and embed the HTML link created in the previous step.

      For example:

      <div flex-xs flex="40" layout="column">
       <md-card class="default-card">
       <md-card-title>
       <md-card-title-text>
       <span class="md-headline">Twitter</span>
       </md-card-title-text>
       </md-card-title>
       <md-card-content>

      <a class="twitter-timeline" href="https://twitter.com/ExLibrisGroup?ref_src=twsrc%5Etfw">Tweets by ExLibrisGroup</a> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
       </md-card-content>
       </md-card>
       </div>

    3. Compress, upload, and deploy your updated customization package. For more information, see Using the UI Customization Package Manager.

    Creating a Custom Help Page

    The new UI allows you to create and embed a custom help page, which contains information on how to utilize the interface to access services provided by your institution. To provide a custom help page, you will have to create the help file, upload the help file to the server, and add a link in the new UI to allow users to access the help page.

    Creating and Uploading the Help File

    Primo VE allows you to provide help files for each language supported by your institution. The naming convention is help_<language>.html (such as help_en.html). All custom help files must be paced in the html/help directory of your view's customization package.
    To create and upload the help files:
    1. Download your view's customization package (see Modifying a View-Level Package).
    2. For each language supported, create an HTML help file (using the naming convention mentioned above).
    3. Save the help files under the a html/help directory of your view's customization package. You may need to create the help directory first.
    4. Compress your view's package and upload it to the server (see Modifying a View-Level Package).

    Adding the Help Link to the UI

    The Links Menu tab on the Views Configuration page allows you to define the Help link that appears at the top of the page in Primo VE.
    PVE_AddHelpLink_To_Menu.png
    Help Link in the Main Menu
    To add the Help link:
    1. On the View Configuration page (Configuration Menu > Discovery > Display Configuration > Configure Views), edit your view.
    2. Select the Links Menu tab.
    3. Click Add Link to open the Edit Link Menu page.
    4. Specify the following fields:
      • Code – Enter primo_help.
      • URL – Enter static-file/help.
      • Label – Enter the display label for the help link (such as Help). Click the Translate icon PVE_TranslateIcon2.png to define a language-specific label.
      • Description – Specify the text that displays when users hover the cursor over the link. Click the Translate icon PVE_TranslateIcon2.png to define a language-specific description.
      PVE_EditMenuLink2.png
      Edit Link Menu Page
    5. Click Save.

    Disabling Short Permalinks in Primo VE 

    By default, the Send To action Permalink, which appears on both the Brief and Full Display pages, creates a shortened URL that includes the institution code, record ID, and a key:

    <Primo Domain>/permalink/<institution_code>/<key>/<record_ID>

    When the shortened URL is entered in a browser, Primo will convert the URL to its full URL and display the record's full details.

    • Short format –

      https://inst.primo.exlibrisgroup.com/permalink/11INST_INST/12345/alma991004075889705106

    • Long format –

      https://inst.primo.exlibrisgroup.com/discovery/fulldisplay?docid=alma991004075889705106&context=L&vid=11INST_INST:inst&search_scope=MyInstitution&tab=LibraryCatalog&lang=en

    To disable short permalinks:

    This enhancement is enabled by default. If you would like to revert to the long format, add the following lines to the CSS file in your customization package:

    .__xs prm-permalink .layout-column>.long-permalink, prm-permalink .layout-column>.long-permalink {

        display: inherit;

    }

     

    .__xs prm-permalink .layout-column>.short-permalink, prm-permalink .layout-column>.short-permalink {

        display: none;

    }

    • Was this article helpful?