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 insrc/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 theuv-pagingheaderpanel-module
. This has a default width of113px
insrc/modules/uv-pagingheaderpanel-module/css/styles.less
, but is overridden insrc/themes/uv-cy-GB-theme/header-panel.less
to140px
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 thatembed.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 ofsc: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.