Meet us at Print 18. Chicago, IL. Sept. 30 - Oct. 2.

Private Image Gallery

When you integrate Customer's Canvas with your application, you may need to manipulate files in the private user gallery. For example, you may want to upload files without using the image manager or move/delete these files programmatically. You can directly access the ~\UserDataFolder\<userId>\images\ folder, but this can be difficult or even impossible in some cases. To solve this problem, Customer's Canvas provides the Gallery controller described in this topic.

Note

Do not confuse this controller with the UserImages controller, which you can use to extract user files from a state file.

It is recommended to download the code sample demonstrating how to work with the private gallery and authentication API and refer to this sample when reading this topic.

Photos uploaded by the user are usually quite sensible information. An irresponsible attitude to security in the API development can lead to Privacy violation. Therefore, authorization is required to use this API. You must create a token on the server and pass it in each request as described in the Authentication with Tokens topic. In the code sample, you can see how to work with these tokens.

Function Request type URL
Get a file list GET ~/api/Gallery/Private/{userId}/files
Upload files POST ~/api/Gallery/Private/{userId}/files
Get a preview GET ~/api/Gallery/Private/{userId}/files/{filePath}
Rename and move a file PUT ~/api/Gallery/Private/{userId}/files/{filePath}
Delete a file DELETE ~/api/Gallery/Private/{userId}/files/{filePath}
Create a folder POST ~/api/Gallery/Private/{userId}/folders
Get a folder list GET ~/api/Gallery/Private/{userId}/folders
Rename or move a folder PUT ~/api/Gallery/Private/{userId}/folders/{folderPath}
Delete a folder DELETE ~/api/Gallery/Private/{userId}/folders/{folderPath}

Getting a File List

To get a list of user images, you can use the ~/api/Gallery/Private/{userId}/files URL. This GET request takes the userId required parameter. Also, you can pass the following optional parameters.

URL Parameters

The Gallery controller can take the following parameters when retrieving the list of user images:

  • Path - the folder to retrieve images, relatively to the ~\UserDataFolder\<userId>\images\ folder. The default value is null that means the controller returns files from the \images\ folder.
  • PageSize - the number of images that fit one page. The maximum value is 100. The default value is 20.
  • Page - the requested page. The default value is 0.
  • OrderBy - the sort order, either Name, Date, or Size. The default value is null that means the controller returns unsorted files.
  • OrderByDescending - enables the descending sort order. The default value is false.
  • SvgAction - the way of processing SVG files, either Vector or Shape. The default value is Vector.

The Request Example

JavaScript
var getFilesList = function(user, token) {
    var params = "?";
    for (var i = 2; i < arguments.length; i++) {
       if (arguments[i].val() != "") params += arguments[i].attr("id") +"=" + arguments[i].val() + "&";
    }
    params = params.slice(0, -1);
    console.log(params);
    $.ajax({
        url: "https://example.com/SimplePolygraphy/api/Gallery/Private/" + user + "/files" + params,
        type: "GET",
        headers: { "X-CCToken": token }
    }).
    fail(function (d) { console.log(d.statusText); console.log(d.responseText); }).
    done(function (d) { console.log("Success"); });
}

The Success Response

For example, you can get the following response for the case when the default user has only the badge.jpg file in the \images\ folder.

Status Code: 200 OK
Content:
{  
  "success": true,
  "total": 1,
  "page": 0,
  "pageSize": 20,
  "items": [{  
    "storageId": "4F9957DEABA2E5FBED4B2CACA5C7E5FB.jpg",
    "name": "badge.jpg",
    "path": "",
    "width": 750.0,
    "height": 1050.0,
    "dateCreated": "2017-06-20T07:41:25.000",
    "editingEnabled": true,
    "isUserImage": true,
    "isVector": false,
    "previewUrl": "https://example.com/api/Gallery/Private/default/files/badge.jpg",
    "deleteUrl": "https://example.com/api/Gallery/Private/default/files/badge.jpg",
    "pageIndex": 0,
    "linkedPages": [ ]
  }]
}

Here, the path property contains subfolders in which this item is located, relative to \images\. The linkedPages array contains page names for multipage PDF files, and pageIndex is the page number of this item in the PDF file.

The Error Response

You can obtain the following error responses:

  • Status Code: 403 Forbidden
    Content: Invalid Security Token
    
  • Status Code: 403 Forbidden
    Content: Invalid Security Key
    
  • Status Code: 404 Not Found
    Content: Folder does not exist
    

Uploading Files

To upload images, you can use the ~/api/Gallery/Private/{userId}/files URL. This POST request takes the userId required parameter.

URL Parameters

The Gallery controller can take the following two parameters when uploading user images:

  • Path - the destination folder for uploading images, relatively to the ~\UserDataFolder\<userId>\images\ folder. The default value is null that means the controller uploads files to the \images\ folder.
  • OverwriteExistingFiles - enables overwriting files if this file name already exists. By default, this value is false, and the controller adds a suffix to the file name, for example, _1, _2, and so on.

The Request Payload

You can pass a number of files as multipart/form-data in this POST request.

The Request Example

JavaScript
var uploadFile = function(user, token, filesToUpload) {
    var formData = new FormData();
    for (var i = 0; i < 3; i++) {
        if (filesToUpload[i].files[0]) formData.append("userfiles[]", filesToUpload[i].files[0]);
    }
    $.ajax({
        url: "https://example.com/SimplePolygraphy/api/Gallery/Private/" + user + "/files",
        type: "POST",
            
        enctype: 'multipart/form-data',
        data: formData,
        processData: false,
        cache: false,
        contentType: false,

        headers: { "X-CCToken": token }
    }).
    fail(function (d) { console.log(d.statusText); console.log(d.responseText); }).
    done(function (d) { console.log("Success"); });
}

The Success Response

This request results in the same success response described in the previous section.

The Error Response

You can obtain the following error responses:

  • Status Code: 400 Bad Request
    Content: Invalid file
    
  • Status Code: 403 Forbidden
    Content: Invalid Security Token
    
  • Status Code: 500 Internal Server Error
    Content: Error while uploading file
    

Getting a Preview

To preview user images, you can use the ~/api/Gallery/Private/{userId}/files/{filePath} URL. This GET request takes the userId and filePath required parameters.

URL Parameters

The Gallery controller can take the following two parameters when rendering previews of user images:

  • X-CCToken - the authentication token.
  • Width - the maximum width of this preview, in pixels. The default value is 500.
  • Height - the maximum height of this preview, in pixels. The default value is 500.
  • PsdAction - the way of processing PSD files, either Design or Merged. The default value is Design.
  • SvgAction - the way of processing SVG files, either Vector or Shape. The default value is Vector.
  • PageIndex - the index of a page in a PDF file, starting from 0. The default value is 0.
  • ThemeConfig - the object representing Product Themes. You need to pass this object when a private gallery may contain PSD templates with the <THMB> marker.
  • ThemeName - the theme name that you define in the clientConfig.json file.

The Request Example

JavaScript
<script>
    var previewFile = function(user, fileName) {
        var params = "?";
        var baseURL = "https://example.com/SimplePolygraphy/";
        for (var i = 2; i < arguments.length; i++) {
           if (arguments[i].val() != "") params += arguments[i].attr("id") +"=" + arguments[i].val() + "&";
        }
        params = params.slice(0, -1);
        console.log(params);
        $("#preview").html("<img src='" + baseURL + "api/Gallery/Private/" + user + "/files/" + fileName + params + "' />");
    }
</script>
<div id="preview"></div>

The Success Response

Status Code: 200 OK
Content-type: image/jpeg

The Error Response

You can obtain the following error responses:

  • Status Code: 400 Bad Request
    Content: Width/Height is out of range
    
  • Status Code: 403 Forbidden
    Content: Invalid Security Token
    

Renaming and Moving a File

To rename or move user images, you can use the ~/api/Gallery/Private/{userId}/files/{filePath} URL. This PUT request takes the userId and filePath required parameters.

URL Parameters

The Gallery controller can take the following optional parameters:

  • Name - the new file name.
  • Path - the new file path, relatively to the ~\UserDataFolder\<userId>\images\ folder.

The Request Example

JavaScript
var renameFile = function(user, token, fileName, newFileName, whereTo) {
    url = "https://example.com/SimplePolygraphy/api/Gallery/Private/" + user + "/files/" + fileName;
    if (whereTo == "")
        // Only rename the file.
        url += "?Name=" + newFileName;
    else
        if (newFileName == "")
            // Only move the file.
            url += "?Path=" + whereTo;
        else
            // Rename and move the file.
            url += "?Name=" + newFileName + "&" + "Path=" + whereTo;

    // Make the request.
    $.ajax({
        url: url,
        type: "PUT",
        headers: {"X-CCToken": token }
    }).
    fail(function (d) { console.log(d.statusText); console.log(d.responseText); }).
    done(function (d) { console.log("Success"); });
}

The Success Response

Status Code: 200 OK

The Error Response

You can obtain the following error responses:

  • Status Code: 400 Bad Request
    Content: File path required
    
  • Status Code: 400 Bad Request
    Content: Either name or path must be provided
    
  • Status Code: 403 Forbidden
    Content: Invalid Security Token
    
  • Status Code: 404 Not Found
    Content: File not found
    
  • Status Code: 409 Conflict
    Content: Can not move or rename the file because a file with the same name already exists
    

Deleting a File

To delete user images, you can use the ~/api/Gallery/Private/{userId}/files/{filePath} URL. This DELETE request takes the userId and filePath required parameters.

The Request Example

JavaScript
var deleteFile = function(user, token, fileName) {
    $.ajax({
        url: "https://example.com/SimplePolygraphy/api/Gallery/Private/" + user + "/files/" + fileName,
        type: "DELETE",
        headers: { "X-CCToken": token }
    }).
    fail(function (d) { console.log(d.statusText); console.log(d.responseText); }).
    done(function (d) { console.log("Success"); });
}

The Success Response

Status Code: 200 OK

The Error Response

You can obtain the following error responses:

  • Status Code: 400 Bad Request
    Content: File path required
    
  • Status Code: 403 Forbidden
    Content: Invalid Security Token
    
  • Status Code: 404 Not Found
    Content: File not found
    

Creating a Folder

To create a folder in the private user gallery, you can use the ~/api/Gallery/Private/{userId}/folders URL. This POST request takes the userId required parameter.

URL Parameters

The Gallery controller can take the following parameters when creating a folder:

  • Name - the folder name to be created.
  • Path - the parent folder. If you omit this parameter, this controller creates the subfolder in the ~\UserDataFolder\<userId>\images\ folder.

The Request Example

JavaScript
var createFolder = function(user, token, folderName, path) {
    var params = "";
    var baseURL = "https://example.com/SimplePolygraphy/";
    if (path != "") params = "&path=" + path;
    $.ajax({
        url: baseURL + "api/Gallery/Private/" + user + "/folders?Name=" + folderName + params,
        type: "POST",
        headers: { "X-CCToken": token }
    }).
    fail(function (d) { console.log(d.statusText); console.log(d.responseText); }).
    done(function (d) { console.log("Success"); });
}

The Success Response

Status Code: 200 OK

The Error Response

You can obtain the following error responses:

  • Status Code: 400 Bad Request
    Content: The Name parameter is required
    
  • Status Code: 403 Forbidden
    Content: Invalid Security Token
    
  • Status Code: 409 Conflict
    Content: Folder already exists
    

Getting a Folder List

To get a list of folders, you can use the ~/api/Gallery/Private/{userId}/folders URL. This GET request takes the userId required parameter. Also, you can pass the following optional parameters.

URL Parameters

The Gallery controller can take the following parameters when retrieving the list of folders:

  • Path - the folder to retrieve subfolder names, relatively to the ~\UserDataFolder\<userId>\images\ folder. The default value is null that means the controller returns subfolder names from the \images\ folder.
  • PageSize - the number of subfolders that fit one page. The maximum value is 100. The default value is 20.
  • Page - the current page. The default value is 0.
  • OrderBy - the sort order, either Name or Date. By default, this controller returns the subfolder list sorted by names.
  • OrderByDescending - enables the descending sort order. The default value is false.

The Request Example

JavaScript
var getFolderList = function(user, token) {
    var params = "?";
    for (var i = 2; i < arguments.length; i++) {
        if (arguments[i].val() != "") params += arguments[i].attr("id") +"=" + arguments[i].val() + "&";
    }
    params = params.slice(0, -1);
    console.log(params);
    $.ajax({
        url: "https://example.com/SimplePolygraphy/api/Gallery/Private/" + user + "/folders" + params,
        type: "GET",
        headers: { "X-CCToken": token }
    }).
    fail(function (d) { console.log(d.statusText); console.log(d.responseText); }).
    done(function (d) { console.log("Success"); });
}

The Success Response

For example, you can get the following response for the case when the default user has only the \Europe\ subfolder in \images\.

Status Code: 200 OK
Content:
{
  "total": 1,
  "page": 0,
  "pageSize": 20,
  "folders": [{  
    "name": "Europe",
    "path": null,
    "date": "2018-01-23T05:43:40.000",
    "fileCount": 2
  }]
}

Here, null in the path property means that the parent folder of this subfolder is \images\. The fileCount property contains the number of files in this folder, and date is when this folder was created or updated.

The Error Response

You can obtain the following error responses:

  • Status Code: 403 Forbidden
    Content: Invalid Security Token
    
  • Status Code: 403 Forbidden
    Content: Invalid Security Key
    
  • Status Code: 404 Not Found
    Content: Folder does not exist
    

Renaming and Moving a Folder

To rename or move folder in the private gallery, you can use the ~/api/Gallery/Private/{userId}/folders/{folderPath} URL. This PUT request takes the userId and folderPath required parameters.

URL Parameters

The Gallery controller can take the following optional parameters:

  • Name - the new folder name.
  • Path - the new folder path, relative to the ~\UserDataFolder\<userId>\images\ folder.

The Request Example

JavaScript
var renameFolder = function(user, token, folderName, newFolderName, path) {
    var params = "";
    var baseURL = "https://example.com/SimplePolygraphy/";
    if (path != "") params = "&path=" + path;
    $.ajax({
        url: baseURL + "api/Gallery/Private/" + user + "/folders/" + folderName + "?Name=" + newFolderName + params,
        type: "PUT",
        headers: {"X-CCToken": token }
    }).
    fail(function (d) { console.log(d.statusText); console.log(d.responseText); }).
    done(function (d) { console.log("Success"); });
}

The Success Response

Status Code: 200 OK

The Error Response

You can obtain the following error responses:

  • Status Code: 400 Bad Request
    Content: Folder path required
    
  • Status Code: 400 Bad Request
    Content: Either name or path must be provided
    
  • Status Code: 403 Forbidden
    Content: Invalid Security Token
    
  • Status Code: 404 Not Found
    Content: Folder does not exist
    
  • Status Code: 404 Not Found
    Content: New folder name should not be the same as the old one
    
  • Status Code: 409 Conflict
    Content: Folder with the same name already exists
    

Deleting a Folder

To delete folders, you can use the ~/api/Gallery/Private/{userId}/folders/{folderPath} URL. This DELETE request takes the userId and folderPath required parameters.

The Request Example

JavaScript
var deleteFolder = function(user, token, folderName) {
    var baseURL = "https://example.com/SimplePolygraphy/";
    $.ajax({
        url: baseURL + "api/Gallery/Private/" + user + "/folders/" + folderName,
        type: "DELETE",
        headers: { "X-CCToken": token }
    }).
    fail(function (d) { console.log(d.statusText); console.log(d.responseText); }).
    done(function (d) { console.log("Success"); });
}

The Success Response

Status Code: 200 OK

The Error Response

You can obtain the following error responses:

  • Status Code: 400 Bad Request
    Content: The root folder cannot be deleted
    
  • Status Code: 403 Forbidden
    Content: Invalid Security Token
    
  • Status Code: 404 Not Found
    Content: Folder does not exist
    

See Also

Manual

Downloads