Understanding the File Structure of a Customization Package

Your customization package must be structured as follows to ensure that it integrates properly with Primo VE:

<View_Code> – The top folder of your customization package. Ensure that you change the name of the top folder to your institution's view code, which must be in the following format: <institution_code>-<view_code>. This folder must include the following folders:

• assets – All of the NDE customization is done within the following subfolders:

  • css – This subfolder contains the custom.css file, which includes your formatting rules for the NDE UI (except for the Landing Page). These rules override corresponding rules in the default CSS.

  • header-footer – The header.html and footer.html are used to customize the header and footer of your view, respectively. For more information, see Adding Headers and Footers.

  • homepage – This folder contains the HTML and CSS files for the landing page only: homepage_en.html and homepage.css. For more information, see Customizing the Landing Page.

  • icons – This subfolder contains all customized icons for the NDE UI: favicon.ico and custom_icons.svg. For more information, see Customizing Icons.

  • images – This subfolder contains the customized images for the NDE UI: library-logo.png and icon_<resource_type_code>.png. For more information, see Customizing Image Files.

  • js – This subfolder contains the custom.js file, which includes only the JavaScript code used to load the NDE UI. This file is used differently from the original UI. It is no longer used to add custom Angular components hooked to a specific component. To implement that configuration, see Advanced Customization Capabilities and Managing Add-Ons for the NDE UI. 

Creating and Deploying a Customization Package

The Manage Customization Package tab downloads/uploads the customization package between the Primo VE server and your local machine. Before you update an existing customization package, it is recommended that you download it from the server to ensure that you are using the latest copy. If you are creating a customization package, you are recommended to download the template.

For more information, see Managing Customization Packages.

1. Edit your view on the Views List page (Configuration > Discovery > Display Configuration > Configure Views).

2. Select the Manage Customization Package tab.

   

   Manage Customization Package Tab for the NDE UI

3. If this is the first time, download the template package in the Download Package section. Otherwise, download the current package to ensure you use the latest version.

4. Unzip the file.

5. Ensure 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. Customize the configuration files and folders associated with your Landing Page, images, and CSS as needed. You must retain the file structure and names of files that you are overriding. For more information, refer to the remaining sections in this document.

7. Zip the <View_Code> folder.

   For Windows users, we recommend using 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 in the Upload Package section.

9. Select Save to deploy the changes.

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

Customizing the Landing Page

The Landing Page is the entry point for library discovery and typically includes an empty search box.

Institutions are encouraged to add or customize the following information on the page:

• Quick access links, such as library hours.

• A welcome message and search tips.

• An option to embed a showcase carousel will be available via configuration after the General Release in May 2025.

• An option to customize the background image of the Landing Page.

• Customize the title in the banner using the following code in the Search Tile Labels code table (Configuration > Discovery > Display Configuration > Labels):

  nde.landing.header—Your Discovery Begins Here

The homepage folder in your customization package includes the following files to customize the content and styles for the Landing page:

• homepage_en.html —This HTML file customizes the area below the search box on your Landing Page. To support other languages, you can create and upload new HTML files with the relevant language code—for example, homepage_fr.html. A template file is provided as an example.

• homepage.css —This CSS file configures the formatting specifically for your Landing Page. A template file is provided as an example.

• homepage_background.svg — This SVG file configures the Landing page's background image.

In the following example, the background image and the text in the "About the Library" section were updated:

1. Create the homepage_en.html file with the changes to the "About the Library" section (see attached HTML file):

   <!DOCTYPE html>
   <html lang="en">
   <head>
     <base href="/">
     <meta charset="UTF-8">
     <meta content="width=device-width, initial-scale=1.0" name="viewport">
     <title>Library Page</title>
     <link href="./homepage.css" rel="stylesheet">
   </head>
   <body>
   <main class="main-landing-page display-flex flex-column flex-layout-center-center">
     <div class="menu-container width-100">
       <ul role="list" class="menu width-100">
         <li role="listitem">
           <a id="Opening_hours_link" aria-label="Opening hours" role="link">
             <div class="icon display-flex">
               <img alt="" src="assets/images/homePageImages/clock.svg">
             </div>
             <span>Opening hours</span>
           </a>
         </li>
         <li role="listitem">
           <a id="FAQ_link" aria-label="FAQ" role="link">
             <div class="icon display-flex">
               <img alt="" src="assets/images/homePageImages/search.svg">
             </div>
             <span>FAQ</span>
           </a>
         </li>
         <li role="listitem">
           <a id="Ask_a_librarian_link" aria-label="Ask a librarian" role="link">
             <div class="icon display-flex">
               <img alt="" src="assets/images/homePageImages/book.svg">
             </div>
             <span>Ask a librarian</span>
           </a>
         </li>
         <li role="listitem">
           <a id="Search_tips_link" aria-label="Search tips" role="link">
             <div class="icon display-flex">
               <img alt="" src="assets/images/homePageImages/comp_search.svg">
             </div>
             <span>Search tips</span>
           </a>
         </li>
         <li role="listitem">
           <a id="Study_room_link" aria-label="Study room" role="link">
             <div class="icon display-flex">
               <img alt="" src="assets/images/homePageImages/book.svg">
             </div>
             <span>Study room</span>
           </a>
         </li>
       </ul>
     </div>

     <div class="flex-row flex-layout-space-between width-100 welcome-announcements-container">
       <div class="welcome display-flex flex-column flex-layout-start">
         <h2 aria-level="2" role="heading" class="welcome-title mat-headline-medium ">Welcome to the library</h2>
         <span class="welcome-content">Access your account by signing in and enabling more capabilities</span>
         <a id="myLibraryCard" tabindex="0" aria-label="Go to my library card" role="link">Go to my library card</a>
       </div>
       <div class="announcements display-flex flex-column">
         <header class="flex-column gap-1">
           <h2 class="mat-title-medium" role="heading" aria-level="2">Announcements:</h2>
           <h3 role="heading" aria-level="3" class="announcements-item-title mat-headline-medium">New library resources</h3>
         </header>
         <article>
           <p class="mat-body-large">Lorem ipsum dolor sit amet consectetur. Varius ipsum amet elit convallis. Egestas arcu volutpat morbi urna
             cursus amet.</p>
         </article>

       </div>
     </div>

     <div class="about display-flex width-100">
       <div class="about-content flex-row">
         <div class="about-text flex-column flex-space-between ">
           <h2 role="heading" aria-level="2" class="about-text-title mat-headline-large">Customized Landing Page </h2>
           <p class="about-text-description">
             Please make sure to custom your text here as this is a demo customization example  .</p>
           <div class="help-sign-in-container flex-column gap-05">
             <span>Primo also helps you manage your research. Sign in to:</span>
             <ul role="list">
               <li role="listitem">
                 <img alt="Library image" src="assets/images/homePageImages/success.svg">
                 <span> Reserve and renew books</span>
               </li>
               <li role="listitem">
                 <img alt="Library image" src="assets/images/homePageImages/success.svg">
                 <span> Create favorites lists</span></li>
               <li role="listitem">
                 <img alt="Library image" src="assets/images/homePageImages/success.svg">
                 <span> Reserve and renew books</span></li>
               <li role="listitem">
                 <img alt="Library image" src="assets/images/homePageImages/success.svg">
                 <span> View full search results</span></li>
             </ul>
           </div>
         </div>
         <div class="about-image flex-layout-center-center">
           <img alt="" src="assets/images/homePageImages/about_image.svg">
         </div>
       </div>
     </div>
   </main>
   </main>
   </body>
   </html>

2. Create the homepage_background.svg Landing page's background file with the new background image (see attached SVG file).

3. Since no CSS was added, the default formatting from the view is used.

4. Zip and upload your updated customization package in the Manage Customization Package tab for your view.

After the deployment, the Landing page appears as follows:

Adding Headers and Footers

Headers and footers are areas at the top and bottom of the NDE UI. You can display common information on all pages in the UI in these areas if added to the following files in your customization package: header.html and footer.html. If you support languages other than English, use the following format to include the language's two-digit code in the file name: header_<language_code>.html and footer_<language_code>.html.

For example, add the following code to the footer.html file to display links for your institution's privacy policy, accessibility statement, and Terms of Use:

When deployed, the footer appears at the bottom of the UI:

Customizing a Color Theme

If you have selected one of our out-of-the-box color themes but require minor changes to match your brand, you can modify specific variables (such as --sys-primary) with your customization package.

1. Determine which attribute you want to change. To see a list of currently used attributes, inspect the nde-color-theme-*.css source file using the browser's Development Tools (F12). 

   

   Inspect Color Variables in Browser

2. Edit the variable in your customization package's custom.css file. For example:

   :root {
     --sys-primary: #b51a57;  
   }

3. Zip and upload your customization package. For more information, see Creating and Deploying a Customization Package.

Customizing Image Files

The images folder contains the images used to customize the library logo and resource type thumbnails. To add the image files, use the PNG format and ensure that you adhere to the guidelines and the following naming formats:

• library-logo.png – When added to the images folder, it overrides the default image for the library logo that appears in the Main Menu:

  

  Library Logo in NDE UI

• icon_<resource_type_code>.png – When added to the images folder, it overrides the default thumbnail for a resource when there is no cover for the image. For example: icon_audio.png.

Customizing Icons

The icons folder contains the icons used to customize the favicon and various icons used in the NDE UI (such as the search icon ). To customize the icons, use the SVG format and the following files:

• favicon.ico – When added to the icons folder, it overrides the default favicon for your view:

  

  Favicon in NDE UI Tab

•  custom_icons.svg – Add the icons (based on the ID of the default icon) to this file using the SVG format. You can add as many icons as needed using the <symbol> element for each.

  

  Search Icon in the NDE UI

  To determine the ID of an icon, use a browser's Development Tools to inspect the icon you want to customize. After selecting Inspect Element option and the icon, the ID of the icon appears in the data-mat-icon-name field:

  

  Inspecting the Icon for the ID

  For example, the custom_icons.svg file may appear as follows with a single icon:

  <?xml version="1.0" encoding="UTF-8"?>

  <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="0" height="0">

    <symbol id="Search" height="24px" viewBox="0 -960 960 960" width="24px" fill="">

      <path d="M440-240q116 0 198-81.5T720-520q0-116-82-198t-198-82q-117 0-198.5 82T160-520q0 117 81.5 198.5T440-240Zm0-280Zm0 160q-83 0-147.5-44.5T200-520q28-70 92.5-115T440-680q82 0 146.5 45T680-520q-29 71-93.5 115.5T440-360Zm0-60q55 0 101-26.5t72-73.5q-26-46-72-73t-101-27q-56 0-102 27t-72 73q26 47 72 73.5T440-420Zm0-40q25 0 42.5-17t17.5-43q0-25-17.5-42.5T440-580q-26 0-43 17.5T380-520q0 26 17 43t43 17Zm0 300q-75 0-140.5-28.5t-114-77q-48.5-48.5-77-114T80-520q0-74 28.5-139.5t77-114.5q48.5-49 114-77.5T440-880q74 0 139.5 28.5T694-774q49 49 77.5 114.5T800-520q0 64-21 121t-58 104l159 159-57 56-159-158q-47 37-104 57.5T440-160Z"/>

    </symbol>

  </svg>

  Example of custom_icons.svg File