User uploads
- 13 minutes to read
When you integrate Design Editor 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 ..\userdata\<userId>\images\ folder, but this can be difficult or even impossible in some cases. To solve this problem, Design Editor 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 sensitive information. An irresponsible attitude to security in the API development can lead to a 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 Auth tokens. 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 |
Download an image | GET | ~/api/Gallery/Private/{userId}/files/download/{filePath} |
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 endpoint. 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, relative to the ..\userdata\<userId>\images\ folder. The default value isnull
, which means the controller returns files from the \images\ folder.PageSize
- the number of images that fit one page. The maximum value is100
. The default value is20
.Page
- the requested page. The default value is0
.OrderBy
- the sort order, eitherName
,Date
, orSize
. The default value isnull
, which means the controller returns unsorted files.OrderByDescending
- enables the descending sort order. The default value isfalse
.SvgAction
- the way in which SVG files are processed, eitherVector
orShape
. The default value isVector
.
Request Example
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/cc/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"); });
}
Success Response
For example, you can get the following response for the case when the default user only has 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": "2020-06-20T07:41:25.000",
"editingEnabled": true,
"isUserImage": true,
"isVector": false,
"originalUrl": "https://example.com/api/Gallery/Private/default/files/badge.jpg",
"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.
Error Response
You can receive 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 to the user folder, you can use the ~/api/Gallery/Private/{userId}/files endpoint. 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, relative to the ..\userdata\<userId>\images\ folder. The default value isnull
, which means the controller uploads files to the \images\ folder.OverwriteExistingFiles
- enables overwriting files if this file name already exists. By default, this value isfalse
, and the controller adds a suffix to the file name, for example, _1, _2, and so on.
Request Payload
You can pass a number of files as multipart/form-data
in this POST request.
Request Example
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/cc/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"); });
}
Success Response
This request results in the same success response described in the previous section.
Error Response
You can receive 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
Downloading an Image
To download an original image or its fragment, you can use the ~/api/Gallery/Private/{userId}/files/download/{filePath} endpoint. This GET request takes the userId
and filePath
required parameters and outputs an image to a stream.
URL Parameters
The Gallery
controller can take the following parameters when downloading user images:
X-CCToken
- the authentication token.Width
- the width of the resulting image, in pixels. The default value is the width of the original image.Height
- the height of the resulting image, in pixels. The default value is the height of the original image.X
- the x-coordinate of the fragment, in pixels. The default value is0
.Y
- the y-coordinate of the fragment, in pixels. The default value is0
.OriginalWidth
- the width of the image fragment, in pixels. The default value is the width of the original image.OriginalHeight
- the height of the image fragment, in pixels. The default value is the height of the original image.Angle
- the rotation angle of the fragment relative to the fragment center, in degrees. The default value is0
.
Request Example
<script>
var downloadImage = function(user, fileName) {
var params = "?";
var baseURL = "https://example.com/cc/";
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);
$("#originalImage").html("<img src='" + baseURL + "api/Gallery/Private/" + user + "/files/download/" + fileName + params + "' />");
}
</script>
<div id="originalImage"></div>
Success Response
Status Code: 200 OK
Content-type: image/jpeg
Error Response
You can receive the following error response:
Status Code: 403 Forbidden
Content: Invalid Security Token
Getting a Preview
To preview user images, you can use the ~/api/Gallery/Private/{userId}/files/{filePath} endpoint. This GET request takes the userId
and filePath
required parameters and outputs a preview image to a stream.
URL Parameters
The Gallery
controller can take the following parameters when rendering previews of user images:
X-CCToken
- the authentication token.- Width - the maximum width of this preview, up to 500 pixels. The default value is
500
. Height
- the maximum height of this preview, up to 500 pixels. The default value is500
.PsdAction
- the way in which PSD files are processed, eitherDesign
orMerged
. The default value isDesign
.SvgAction
- the way in which SVG files are processed, eitherVector
orShape
. The default value isVector
.PageIndex
- the index of a page in a PDF file, starting from 0. The default value is0
.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.
Request Example
<script>
var previewFile = function(user, fileName) {
var params = "?";
var baseURL = "https://example.com/cc/";
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>
Success Response
Status Code: 200 OK
Content-type: image/jpeg
Error Response
You can receive 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} endpoint. 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, relative to the ..\userdata\<userId>\images\ folder.
Request Example
var renameFile = function(user, token, fileName, newFileName, whereTo) {
url = "https://example.com/cc/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"); });
}
Success Response
Status Code: 200 OK
Error Response
You can receive 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: Cannot 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} endpoint. This DELETE request takes the userId
and filePath
required parameters.
Request Example
var deleteFile = function(user, token, fileName) {
$.ajax({
url: "https://example.com/cc/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"); });
}
Success Response
Status Code: 200 OK
Error Response
You can receive 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 endpoint. 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 ..\userdata\<userId>\images\ folder.
Request Example
var createFolder = function(user, token, folderName, path) {
var params = "";
var baseURL = "https://example.com/cc/";
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"); });
}
Success Response
Status Code: 200 OK
Error Response
You can receive 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 endpoint. 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, relative to the ..\userdata\<userId>\images\ folder. The default value isnull
, which means the controller returns subfolder names from the \images\ folder.PageSize
- the number of subfolders that fit one page. The maximum value is100
. The default value is20
.Page
- the current page. The default value is0
.OrderBy
- the sort order, eitherName
orDate
. By default, this controller returns the subfolder list sorted by names.OrderByDescending
- enables the descending sort order. The default value isfalse
.
Request Example
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/cc/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"); });
}
Success Response
For example, you can get the following response for the case when the default user only has the \Europe\ subfolder in \images\.
Status Code: 200 OK
Content:
{
"total": 1,
"page": 0,
"pageSize": 20,
"folders": [{
"name": "Europe",
"path": null,
"date": "2020-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.
Error Response
You can receive 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 a folder in the private gallery, you can use the ~/api/Gallery/Private/{userId}/folders/{folderPath} endpoint. 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 ..\userdata\<userId>\images\ folder.
Request Example
var renameFolder = function(user, token, folderName, newFolderName, path) {
var params = "";
var baseURL = "https://example.com/cc/";
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"); });
}
Success Response
Status Code: 200 OK
Error Response
You can receive 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} endpoint. This DELETE request takes the userId
and folderPath
required parameters.
Request Example
var deleteFolder = function(user, token, folderName) {
var baseURL = "https://example.com/cc/";
$.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"); });
}
Success Response
Status Code: 200 OK
Error Response
You can receive 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