imagevault.client.js

This library is distributed with ImageVault UI and can be used to make authentication for the REST API a bit easier.

Requirements

It requires the following JavaScript libraries.

Authentication

See authentication for more detailed information.

Examples

Using ImageVault client identity (sdk user)

In this example the ImageVault.Client points to the core instance and are using the client identity (sdk user) Aladdin with password "open sesame".

var core = new ImageVault.Client({
    core: "https://imagevault.local:8001",
    username: "Aladdin",
    password: "open sesame"
});

Acting as another user

If we want to make our calls in another user context, we can pass the impersonate_as and roles properties to impersonate this function.

var core = new ImageVault.Client({
    core: "https://imagevault.local:8001",
    username: "Aladdin",
    password: "open sesame",
    impersonate_as: "epiadmin",
    roles: "webadmins,webeditors"

Using Resource owner password credentials grant

To use the OAuth resource owner password credentials grant method, you supply the client credentials as username/password and the resource owner credentials as resourceOwnerUsername/resourceOwnerPassword. You need to set the grant_type to password.

var core = new ImageVault.Client({
    core: "https://imagevault.local:8001",
    username: "Aladdin",
    password: "open sesame",
    resourceOwnerUsername: "johndoe",
   resourceOwnerPassword: "supersecret",
   grant_type: "password"

Reusing current user authentication

If we don't want to hard code user names, passwords, impersonate information in the web page we can use the RestHandler that is available when we are using the ImageVault for Episerver plug-in. The rest handler is available automatically in Episerver 7 if you just have the ImageVault.EPiServer.Common.dll in your bin folder. (You get this if you add the ImageVault.EPiServer7 NuGet package to your solution) In Episerver 6, the handler gets added to the web.config by the installation program.

If we use this handler (default URL is ~/imagevaultws) we only configure the client to use that URL as core. We also specify the authMethod "none" to block the normal access token procedure. The rest handler will automatically add an access token for the currently logged in user in EpiServer. If you aren't logged into Episerver. then you will get an error (401, access denied).

var core = new ImageVault.Client({
    core: "http://imagevault.local/imagevaultws",
    authMethod: "none",
});

Usage

When you have created the client, you can use it to call methods in the REST API services.

.json(service,args,callback)

The client has a method (json) that you use to call a REST method in the API. The method takes three arguments

service

The service argument is the name of the service/method that you would like to invoke. The name of the service is the same name as the interface without the leading I. The name of the method is the same as the method on the service interface that you would like to invoke.

Example: If you would like to invoke the IMediaService.Find you use the following service name

"MediaService/Find"

args

The args argument is the argument(s) to pass along with the method call. If the method is parameterless, you can skip this parameter and supply the callback as argument 2.

Example:

client.json("LanguageService/GetAllLanguages",function(data){...});

If the method only takes one parameter, supply it as a single value.

Example:

client.json("LanguageService/Create","sv", function(lang){...});

If the method takes more than one parameter, wrap all parameters in an object with members named exactly as the parameters in the interface.

Example:

client.json("MediaContentService/StoreContentInVault",{uploadFileId:"abc123", filename: "myfile.jpg", contentType: "image/jpeg", vaultId: 1}, function(item){...});

callback

The callback argument is a function that will be called when the API call is completed. It will be called regardless if the method worked as intended or if it returned an error.

The function takes one argument that will contain any return value from the API call.

Example: In the example below we call the IMediaService.Find that returns a list of MediaItems

core.json("MediaService/Find", {
    Filter: { SearchString: searchString, Take:10 },
    Populate: {
        MediaFormats: [
            {  
                \$type: "ImageVault.Common.Data.ThumbnailFormat,ImageVault.Common", 
                Effects:[{\$type:"ImageVault.Common.Data.Effects.ResizeEffect, ImageVault.Common",Width:200,Height:200,ResizeMode:'ScaleToFill'}]
            }
        ]
    }    
}, function (d) {
    \$("#searchResultInfo").text("Found " + d.length + " hits.");
    for (var i = 0; i < d.length; i++) {
        var item = d[i];
        var thumbnail = item.MediaConversions[0];
        \$("#searchResult").append("<div style='float:left;text-align:center;'><img src='" + thumbnail.Url + "'/><br/>"+item.Name+"</div>");
    }
});
Errors

If the method call throws an exception, this can be detected using the getLastErrorMessage() method. This will, if the last call resulted in an error, return an error object. Often the error object has some properties that can be examined for more information about the error. When we have oauth authentication errors, they have the prroperties error and error_description Example:

core.json("MediaService/Find", {
    Filter: { SearchString: searchString, Take:10 },
    Populate: {
        MediaFormats: [
            {  
                \$type: "ImageVault.Common.Data.ThumbnailFormat,ImageVault.Common", 
                Effects:[{\$type:"ImageVault.Common.Data.Effects.ResizeEffect, ImageVault.Common",Width:200,Height:200,ResizeMode:'ScaleToFill'}]
            }
        ]
    }    
}, function (d) {
    var error = core.getLastErrorMessage();
    if (error) {
        \$("#searchResultInfo").text(error.error + ":" + error.error_description);
        return;
    }
    \$("#searchResultInfo").text("Found " + d.length + " hits.");
    for (var i = 0; i < d.length; i++) {
        var item = d[i];
        var thumbnail = item.MediaConversions[0];
        \$("#searchResult").append("<div style='float:left;text-align:center;'><img src='" + thumbnail.Url + "'/><br/>" + item.Name + "</div>");
    }
});

Note: Some bugs in the imagevault.client.js script results in that some errors escape the handling above and instead causes console errors.

comments powered by Disqus