Default Extension

In this part of the tutorial we will be creating the uv-default-extension.


First, Fork the UV to your own Github profile.


Now follow the setup instructions to clone your fork and set up the project on your computer.


In Git Bash, create a new branch called "defaultextension":

git checkout -b defaultextension

Create the following file structure within the src/extensions directory:

uv-default-extension
├── config
│   └── en-GB.json
├── l10n
│    └── en-GB.json 
├── theme
│   └── theme.less 
├── dependencies.js
├── Extension.ts
└── Provider.ts

Copy the following code to src/extensions/uv-default-extension/config/en-GB.json:

{
    "options":
    {
        "theme": "uv-en-GB-theme"
    },
    "modules":
    {
        "footerPanel": {
            "options": {
                "downloadEnabled": false,
                "embedEnabled": false
            }
        }
    }
}

This file contains configuration settings for the en-GB locale. The root-level options object specifies global settings, such as which theme to use. The modules object lists each module that the extension uses with its applicable settings.


Copy the following code to src/extensions/uv-default-extension/l10n/en-GB.json:

{
    "localisation": {
        "label": "English (GB)"
    },
    "modules": {
        "footerPanel": {
            "content": {
                "exitFullScreen": "Exit Full Screen",
                "fullScreen": "Full Screen"
            }
        }
    }
}

This file contains the localised text used throughout the UV user interface. When building the UV it is merged with the configuration JSON file to produce a single collection of settings and content strings for the given extension.


Copy the following code to src/extensions/uv-default-extension/theme/theme.less:

@import '../../../modules/uv-shared-module/css/styles.less';
// more modules go here...

@theme-path: '../../../themes/@{theme}/';
@theme-img-path: '@{theme-path}img/';

@import '@{theme-path}theme.less';

This LESS file imports the styles.less files for each module that the extension will use. Currently this example is limited to importing generic shared styles.

The theme.less file above ends with a statement importing the current theme located in src/themes. This allows generic styles set within the module's theme to be overridden when building the UV. An example would be the .search class in the uv-pagingheaderpanel-module. This has a default width of 113px in src/modules/uv-pagingheaderpanel-module/css/styles.less, but is overridden in src/themes/uv-cy-GB-theme/header-panel.less to 140px in order to accommodate the Welsh spelling "GWELD".


The uv-default-extension does not require any extra JavaScript libraries to function. So save the following to src/extensions/uv-default-extension/dependencies.js:

define(function() {
    return {
        dependencies: []
    };
});

If a JavaScript library such as src/extensions/uv-mediaelement-extension/lib/mediaelement-and-player.js was needed as in the case of the uv-mediaelement-extension, it would be entered into the dependencies array like so:

define(function() {
    return {
        dependencies: ['mediaelement-and-player']
    };
});

Copy the following TypeScript code to src/extensions/uv-default-extension/Extension.ts:

import BaseExtension = require("../../modules/uv-shared-module/BaseExtension");
import BootStrapper = require("../../Bootstrapper");
import CenterPanel = require("../../modules/uv-shared-module/CenterPanel");
import FooterPanel = require("../../modules/uv-shared-module/FooterPanel");
import Shell = require("../../modules/uv-shared-module/Shell");

class Extension extends BaseExtension{

    centerPanel: CenterPanel;
    footerPanel: FooterPanel;

    constructor(bootstrapper: BootStrapper) {
        super(bootstrapper);
    }

    create(overrideDependencies?: any): void {
        super.create(overrideDependencies);
    }

    createModules(): void{
        this.centerPanel = new CenterPanel(Shell.$centerPanel);
        this.footerPanel = new FooterPanel(Shell.$footerPanel);
    }
}

export = Extension;

This is the 'boilerplate' code for our new extension. You will notice that we are only initialising the center and footer panels at this time. The header, left, and right panels are not needed for the purposes of this tutorial.


Copy the following code to src/extensions/uv-default-extension/Provider.ts:

import BaseProvider = require("../../modules/uv-shared-module/BaseProvider");
import BootStrapper = require("../../Bootstrapper");

class Provider extends BaseProvider{

    constructor(bootstrapper: BootStrapper) {
        super(bootstrapper);

        this.config.options = $.extend(true, this.options, {

        }, bootstrapper.config.options);
    }
}

export = Provider;

This file contains the implementation of your extension's data provider. We can leave this empty for now, but if the uv-default-extension needed to perform specialised functions on the IIIF manifest data, we would put them in here.


Now run:

grunt serve

You should see a series of messages culminating with TypeScript compilation complete. A browser window should then open to http://localhost:8001/examples/.

We have just performed a "dev" build and launched the UV examples sub-project in a browser. A dev build allows you to see the individual source-mapped TypeScript files in the F12 dev tools and to take advantage of the debugging tools.


Press F12 to open dev tools (this tutorial assumes you are using the Chrome dev tools, although Firefox and modern IE tools will work too). In the sources tab, find localhost:8001/src/App.ts (may require a refresh). This file is the entry point for the UV application (configured here <script data-main="app" type="text/javascript" src="lib/require.js"></script> in src/app.html).

src/app.html is the page that embed.js loads in to the UV iframe.

App.ts contains some requirejs configuration to include several dependencies. At the bottom of the file you can see an extensions dictionary is being created. This contains configuration objects for each type of media the UV can display, e.g.

extensions['seadragon/iiif'] = {
    type: seadragonExtension,
    provider: seadragonProvider,
    name: 'uv-seadragon-extension'
};

Here the 'seadragon/iiif' type is being associated with the corresponding extension and provider. The bootstrapper then examines the manifest to determine which extension in this dictionary to use.

Currently to determine which extension to use, the bootstrapper inspects the IIIF manifest for the @type of the first canvas in the current sequence . A future enhancement might allow the UV to use a different extension for any canvas in the manifest. IIIF currently only supports canvas types of sc:canvas.


Open App.ts in your favourite text editor and add the following code just below the pdf/iiif extension object:

extensions['default'] = {
    type: defaultExtension,
    provider: defaultProvider,
    name: 'uv-default-extension'
};

We now need to import the defaultExtension and defaultProvider libraries. Between'extensions/uv-seadragon-extension/Provider', and 'jquery'in the requirejs dependencies, add the following:

'extensions/uv-default-extension/Extension',
'extensions/uv-default-extension/Provider',

Now between the seadragonProvider,and $ requirejs imports, add the following:

defaultExtension,
defaultProvider,

Now open src/Bootstrapper.ts.

Add the following code to the end of the switch(canvasType.toLowerCase()) statement in the loadDependencies method:

default:
    extension = that.extensions['default'];
    break;

Here we are saying "if the canvas type does not match any registered extension, use the default extension".

For the sake of simplicity, we are going to assume for the purposes of this tutorial that all file types are unrecognisable. Comment out all cases in the switch statement other than the default case.

results matching ""

    No results matching ""