Ready to Learn?Ex Libris products all provide open APIs

Tech Blog

 

Primo new UI - Building customization packages vs developing independent featurs

Primo Dev on September 24th, 2017

Introduction

 

When developing the new Primo UI , and after consulting with the development community several times, we always took the community into consideration and wanted to really make the customer development process easy and robust.

To help us accomplish that we developed the Primo customization Development environment

 

https://github.com/ExLibrisGroup/primo-explore-devenv

 

This blog post will introduce you with some advanced capabilities and interesting integrations that will help us create a strong workflow for developing, sharing and using code extensions for Primo.

 

Following the link above will introduce you to the environment and will allow you to develop customization packages for your Primo views.

Once completing the development you will have a zipped package containing your entire library customizations (css, images, html and JavaScript directives).

The process will allow you a very fast and efficient way to develop your features and at the end you will be able to ship the package to your colleagues for their benefit.

But what if you can share with your colleagues in a more granular way? Since it is not likely that 2 different institutions will want the exact same customization package.

If you already experienced the new development environment then you should be familiar with community tools such as:

 

https://github.com

https://www.npmjs.com/

 

Now let’s see how we can use those tools to achieve the goals mentioned above

Developing a feature rather than a package

First, you need an idea, let’s try to add the altmetrics widget to the full display of the record.

See the documented example of the feature:

 

https://github.com/ExLibrisGroup/primo-explore-package/tree/master/VIEW_CODE/js#javascript-recipe-3---adding-the-altmetrics-widget

 

This feature requires JavaScript and css changes

Step 1: download a package

1.       Go to : https://github.com/ExLibrisGroup/primo-explore-package

2.       Download a package

3.       Copy the folder named VIEW_CODE into :

          primo-explore-devenv/primo-explore/custom
 
          In your development environment
 
4.       Rename the folder name to a name representing your feature (not your Primo view), in our case lets name it: altmetrics
 

Step 2: start your server

1.Open a command window and run the following command:

>> gulp run --view altmetrics

Notice that we didn’t use the view code but the folder name we gave our feature
 
2.       Open your browser and type in the following url:
 
http://localhost:8003/primo-explore/?vid=<your view code>
 
For example:
 
http://localhost:8003/primo-explore/?vid=Auto1
 
Notice that here we use the actual Primo view we want to develop the feature against

 

Step 3: css changes

1.Go to your css/custom1.css file and edit it

2.Add the following:

 

.full-view-section.loc-altmetrics{

   background-color: #f3f3f3;

   margin-top:0px;

   padding-left: 3em;


}

Step 4: JavaScript changes

1.Go to the js folder

2.Create a new file called custom.module.js

3.Edit the file with the following content:

 var app = angular.module('viewCustom', ['angularLoad']);

 

4.Create a new file called altmetrics.js

5.Edit the file with the following content:

 

app.controller('FullViewAfterController', ['angularLoad', function (angularLoad) {

        var vm = this;

        vm.doi = vm.parentCtrl.item.pnx.addata.doi[0] || '';


        vm.$onInit = function () {

            angularLoad.loadScript('https://d1bxh8uas1mnw7.cloudfront.net/assets/embed.js?' + Date.now()).then(function () {


            });

        };

    }]);


app.component('prmFullViewAfter', {

        bindings: {parentCtrl: '<'},

        controller: 'FullViewAfterController',

        template: `<div class="full-view-section loc-altmetrics" flex-md="65" flex-lg="65" flex-xl="65" flex>

                    <div class="layout-full-width full-view-section-content" ng-if="$ctrl.doi">

                    <div class="section-header" layout="row" layout-align="center center">

                        <h2 class="section-title md-title light-text">

                            Social Popularity Statistics (AltMetrics) :

                        </h2>

                        <md-divider flex>

                        </md-divider>

                        </div>

                        <div class="full-view-section">

                           <div class="full-view-section-content">

                                <div class="section-body" layout="row" layout-align="center center">

                                    <div class="spaced-rows" layout="column">

                                        <div ng-if="$ctrl.doi" class="altmetric-embed" data-badge-type="medium-donut" data-badge-details="right" data-doi="$ctrl.doi">

                                        </div>

                                    </div>

                                </div>

                           </div>

                        </div>

                    </div>

                    </div>`

    });

 

 

If you go back to your browser and search for an item with a doi field (examples can be found on Primo Central) and you open the full view you will see the altmetrics widget added at the bottom

 

Altemtrics

Let’s look at what happened

If we review the js folder in our package we will see the following files:

 

1.custom.js – you can see that the content of altmetrics.js was copied to this file

2.custom.module.js – a definition file for the module

3.altmetrics.js – your code

So we created a way to develop separate directives in separate files, concatenating them into the serving custom.js file, what’s next?

 

Adding your code as a project to Github

1.use a Github client of your choice, for example:

         https://desktop.github.com/

2.create a new Repository using your client

3.make sure you prefix the repository name with primo-explore, in our case:

primo-explore-altmetrics-widget

4.        It is recommended to add a README.md file at the root of your folder with explanations on how to use your widget

5.        Add a package.json file describing your project to the root folder of your widget, in our case:

primo-explore-devenv/primo-explore/custom/altmetrics/package.json

with the content:

 

{

 "name": "primo-explore-altmetrics-widget",

 "version": "0.0.1",

 "description": "add an altmetrics widget to the primo full view",

 "author": "<your user id>",

 "repository": {

   "type": "git",

   "url": "<your repository url>.git"

 }


}

 

6.Add/Commit your files (just the source files)to the Github project, in our case:

primo-explore-devenv/primo-explore/custom/altmetrics/css/custom1.css

primo-explore-devenv/primo-explore/custom/altmetrics/js/altmetrics.js

primo-explore-devenv/primo-explore/custom/altmetrics/README.md

 

 

 

Sharing your code on npm

1.Open a new command line window

2.Navigate to the altmertics Github folder:

3.Run npm publish

4.It will take the following files:

 

primo-explore-devenv/primo-explore/custom/altmetrics/css/custom1.css

primo-explore-devenv/primo-explore/custom/altmetrics/js/altmetrics.js

primo-explore-devenv/primo-explore/custom/altmetrics/README.md

 

and create the npm package.

 

Using your code in your view package

1.     Repeat Step 1: download a package
 
2.     Rename the folder to your view code
 
3.    Add a package.json file in your customization package folder root.
 
For example, if you are developing a package for the Auto1 view
 
Add the file under
 
primo-explore-devenv/primo-explore/custom/Auto1
 
The content of the file should be:
 
 
{


  "name": "<your view code>",


  "version": "<your version>",


  "description": "",


  "author": "",


  "devDependencies": {


    "primo-explore-altmetrics-widget": "0.0.2"


  }


}
 
5.    Go to your command line (in windows: type cmd in the start > run box)
 
6.    Navigate to the location of the package.json file
 
  cd primo-explore-devenv/primo-explore/custom/Auto1
 
7. type:
 
    npm install
 
you will see a new folder was added in the same location named node_modules
 
8. start your environment from the command line :
 
        gulp run --view Auto1
 
Now you can see the widget in your full view once you find a record with a doi field
 
 
 
Altemtrics
 
 
 
 

Summary

 
This Blog introduced an exciting new way to write your Primo new UI widgets to be sharable and easily extendable by the community.
In this model you develop features in independent folders/packages, manage the code via Github and upload it as a package to npm.
 

Then, you create a package for your view which will not have to contain any actual source code , but can contain the package.json file with references to features you want to use.

Just remember to load packages with the primo-explore prefix to npm.