Skip to main content
ExLibris
  • Subscribe by RSS
  • ExLibris Dev

    New UI Customization - Best Practices

    Introduction

    In order to provide users with the best experience in Primo discovery, Ex Libris carried out an extensive user study that included the following tasks to help redesign the 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:

    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 the Primo UI. For more information on the tool, see UI Customization Package Manager.
    To ensure that a customization package integrates properly with Primo, the package must contain the following folders:
    • css – This folder contains the custom1.css file, which is where you can include your CSS rules. These rules will override corresponding rules in the default CSS.
    • img – This folder contains all customized images for the new Primo UI. To ensure that the correct image appears in the Primo UI, make sure that you use the same file name as the original. 
    • html – This folder contains all customized HTML files for the new Primo UI. The home_en_US.html file allows you to customize the area of the page below the search box on the Primo Home page. For more information, see Home Page.
    New Primo 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).
    • To support other languages, you can create a new HTML file with the relevant language code and locale. For example: home_fr_FR.html.
    • For details on configuring Alma's View It and Get It services, see Branding the Delivery Tabs.
    To create a customization package:
    1. Open the UI Customization Package Manager (Primo Home > Primo Utilities > UI Customization Package Manager).
      UI_CustomizationPackageManager.png
    2. Select the institution (on-premises configurations only) and the view that you want to customize.
    3. Click Download to download the template package.
      DownloadPackage.png
    4. Unzip the ZIP file.
    5. If using the template file, change the name of the root folder to your view’s code.
    6. Add your customized 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 Configuration package folder.
    8. Open the UI Customization Package Manager (Primo Home > Primo Utilities > UI Customization Package Manager).
    9. Select the institution (on-premises configurations only) and the view that you want to customize.
    10. In the Upload package section, click Choose File to select the zipped package that you just created or modified for that view and institution.
      UploadPackage1.png
    11. Click Upload to upload your package to the server.
      Add image here...
    12. Click Deploy to activate your changes in the Primo UI.
      DeployPackage.png
    13. Refresh your view in the Web browser and test your changes prior to uploading the changes to the production server.

    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/home_en_US.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. Log on to the Primo Back Office.
    2. On the All Code Tables page (Primo Home > Advanced Configuration Wizards > All Code Tables), edit the Results Tile code table under the Front End subsystem.
    3. Change the description of the default.nui.frbrversion.found.link code to the following:
      <font color="green">See all versions</font>
    4. Save and deploy your changes.

    Full Record Page

    This section identifies the major components of the Full Record 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 {}

    Creating a Clickable Logo

    A clickable logo allows users to click the logo to access a page of your choice, such as your library's home page.
    1. Update your view’s package and add the following lines to the custom1.css file under the css folder:
      /* Call the clickable logo */
      prm-logo div.product-logo {
          display:none;
      }
      prm-logo div.product-logo-local {
      display: flex;
      }
      prm-logo .logo-image, prm-logo img {
          max-height: 35px;
      }
    2. Add the following lines to the custom.js file under the js folder and specify your target's URL:
      // Add Clickable Logo
      app.controller('prmLogoAfterController', [function () {
      var vm = this;
      vm.getIconLink = getIconLink;
      function getIconLink() {
                    return vm.parentCtrl.iconLink;
                   }
      }]);
       
      app.component('prmLogoAfter',{
      bindings: {parentCtrl: '<'},
      controller: 'prmLogoAfterController',
      template: '<div class="product-logo product-logo-local" layout="row" layout-align="start center" layout-fill id="banner" tabindex="0"  role="banner">' +
      '<a href="[target's_URL]"><img class="logo-image" alt="{{::(&apos;nui.header.LogoAlt&apos; | translate)}}" ng-src="{{$ctrl.getIconLink()}}"/></a></div>'
      });
      })();
    3. Upload your customized package.

    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. After the May 2017 release, you can use the Side bar (Tweak my results) position field in the Views Wizard (Primo Home > Ongoing Configuration Wizards > Views Wizard) to move the facets to either the left or the right side of the page.

    Creating a Search Box With Deep Links to the New UI

    This example creates a search box that uses a deep link to search your institution's catalog.
    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="http://<HOST_NAME>/primo-explore/search" enctype="application/x-www-form-urlencoded; charset=utf-8" onsubmit="searchPrimo()">
      <!-- Customizable Parameters -->
      <input type="hidden" name="institution" value="<INSTITUTION CODE>">
      <input type="hidden" name="vid" value="<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="<RECORDS PER PAGE, e.g. 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>
    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>
      The search box appears as follows:
      SearchBoxExample.png

    Creating a Twitter Feed

    Will be updated soon...

    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

    The new UI allows you to provide help files for each language supported by your institution. The naming convention is help_<language>.html (such as help_en_US.html). All custom help files must be paced in the html 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 files under the html directory of your view's customization package.
    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 Main Menu tile in the Views Wizard allows you to define the Help link that appears at the top of the page in the new UI.
    NewUI_HelpLink.png
    Help Link in Main Menu Tile of the New UI
    To add the Help Link:
    1. In the Views Wizard (Primo Home > Ongoing Configuration Wizards > Views Wizard), edit your view.
    2. Continue to the Tiles Configuration page and edit the Home Page > Main Menu tile.
    3. In the Create New Label section, specify the following fields and then click Add:
      • Label – Enter primo_help.
      • URL – Leave blank so that the system uses the file that you uploaded with your view's customization package.
      • Link should open in – Specify where the help page will open in the browser. Select either current window or new window/tab.
      CreateNewHelpLabel.png
      Create New Label Section - Main Menu Tile
    4. In the Contents of Main Menu Tile section, modify the Label field to change the label that displays in the Main menu of the new UI. This change updates the description for the mainmenu.label.primo_help code in the View Labels code table.
    5. Save your changes to the view and deploy your view.
    6. If necessary, update the Description column for the following codes in the View Labels code table to modify the label and label description for the help link in the new UI.
      • mainmenu.label.primo_help – Defines the label for the help link in the new UI. You can also update this value by changing the Label field of the Main Menu tile in the Views Wizard.
      • mainmenu.description.primo_help – Defines the description of the help link in the new UI.
    7. Deploy your changes to the code table.
    • Was this article helpful?
    //doorbell.io feedback widged