Filestack Tutorial For Beginners: Part 2 Watermark

Welcome Back!

Hello, and welcome back to the Filestack Tutorial For Beginners. If you have not seen the first half then check it out here. Otherwise, let’s keep making progress on our watermarking application.

Perform a Transformation: Watermark

Working with Uploaded Files: The Filestack Handle

At this point you are probably wondering: “Okay, I understand how to upload files, and can even change uploading options. How do I actually work with the files that have been uploaded?” Well, the answer is the result returned after your Filestack upload. The Filestack API calls return a standard JSON object containing information such as the successfully uploaded files, any failed upload file data (it is rare but can happen), and most importantly your file handles (a one-to-one ID for Files uploaded to Filestack). We will use the handles to work with our uploaded files.

//Function pickMark() will receive the result object back 
function pickMark() {
 console.log("Picking Watermark");
 client.pick({
 accept:'image/*',
 maxFiles: 1,
 }).then(function(result) {//Taking the result object in as 'result'
 //Putting the result in a string, and printing it to the console
 console.log(JSON.stringify(result));
 });
}

(Receiving the result object, and printing it to the console.)

 

(Example Result Object printed out to the console.)

The result given back after the API call to Filestack has all the information we need to work with uploaded files. To get information from the result, we need to identify if it is an array or not. In the example above, it has ‘filesUploaded:’ followed by brackets (‘[ ]’) and inside of the brackets is the information of the file uploaded. These brackets indicate the result could have returned multiple files, and is thus an array and therefore we need to access it like so. Later in this tutorial we will see an example where it does not return an array and we access information differently than here (when we use the storeURL API call on our watermarked image). In this current instance we need the results handle, and will access it by calling result.filesUploaded[index].handle where the index is the number of the file uploaded(0 if it is the first file, 1 if it is the second, etc). I will provide a concrete example of this after we analyze the structure of the URL transformation process.

The URL Transformation Process

The Filestack transformation process uses URL’s to direct processing engines. To put a file through a transformation, you must construct the URL specifying how the file is to be transformed. The transformation URL’s basic formula is the Filestack CDN address, followed by the transformation, and then the handle of the file to be transformed. You could also use an external file in a transformation, in which case the formula is the Filestack address, an API key, the transformation, and then the URL of the external file.

Filestack Transformation URL standard form with a Handle: 
https://cdn.filestackcontent.com/[1]/2 
1 = Conversion Task(s) 
2 = Filestack Handle 
Read about our transformations, <a href="https://www.filestack.com/docs/api/processing/#overview">here</a>.

The URL transformation process requires the file handle to work with the uploaded file, so we will create a variable called watermarkHandle, which we will use to hold the handle. Now, once we get the results back after we upload the watermark file, we will set the variable equal to the handle with the line: watermarkHandle = result.filesUploaded[0].handle;. This line goes into the ‘then(function(result)) area taking in the results, accesses the first element of it by going to index 0, and sets the variable called ‘watermarkHandle’ equal to the file’s handle. To make sure this works, I passed the ‘watermarkHandle’ to the console so I can compare it to the handle printed within the results object.

<script>
   var client = "Your_API_Key_Here";
   //variable to hold the watermark handle 
   var watermarkHandle = '';

   //Function pickMark() will not receive the result object back 
   function pickMark() {
      console.log("Picking Watermark");
      client.pick({
         accept:'image/*',
         maxFiles: 1,
      }).then(function(result) {//Taking the results object in as 'result'
         //Putting the result in a string, and printing it to the console
         console.log(JSON.stringify(result));
         //Sets the watermark handle to the handle of the first file in the result
         watermarkHandle = result.filesUploaded[0].handle;
         //Logs the new watermark handle in the console
         console.log(watermarkHandle);
      });
    }
</script>

(Creating and setting variable to hold the watermark file handle.)

Apply the Watermark Transformation

 

To actually perform the watermark transformation, you must repeat the progress we have made to get another file uploaded, and get its’ handle. This is the image that will be watermarked. I suggest you create a pickImage() function, and implement everything else the same way we just did with the watermark. Once you have completed this, and you have a handle for both the watermark and image to be watermarked we can continue.

Now we are going to actually build the transformation URL. We can create a base variable using the cdn URL I mentioned earlier, and adding “/watermark=file:”, because we are specifically implementing the watermark transformation. Next we can create a function called buildURL, which appends the watermark handle, the position and size of the watermark, and then the photo handle to the URL in this order. I created a button to call the function, and I execute it after I have uploaded the images and gotten both of their handles. Once this is finished you will have a final transformation URL. Go ahead and print the URL into the console, copy and paste the URL, enter the URL into a browser, and then see your watermarked photo! Congratulations on performing your first image transformation using Filestack!

var transformURL = "https://cdn.filestack.com/watermark=file:";</code>

(Variable for transformation URL.)

function buildURL() {
 //Adding the watermark handle to the transformation URL 
 transformURL += watermarkHandle;
 //Placing watermark in center of image with size 200
 transformURL += ',position:[middle,center],size:200/'
 //Adding the image handle to the transformation URL
 trasnformURL += imageHandle;
 //Logging the file transformation URL
 console.log(transformURL);
}

(Function to build the transformation URL.)

(Final watermarked photo.)

Store and Download a File

Note: It is not necessary to permanently store the transformed file to perform the watermarking or download the transformed file. If you would like to skip this section, then in the next section when we use a CDN URL to download the image file,  use the transformation URL that we just built to download it instead.

Store Transformed Files

When you upload a file, by default it is automatically stored permanently in your Filestack storage. When you performed the transformation, the file was not stored and if you wanted to access it in the future you would have to repeat the transformation. To avoid this, Filestack provides several methods of storing the transformed file. We will use the ‘storeURL()’ API method, and pass it the transformation URL. Alternatively, we could use the ‘store’ transformation, which like the Javascript API calls returns a results object we use to work with the uploaded files.

To implement storing, I created a button that calls storeURL() and passed it the URL of the transformed image to store the transformed file. Now the file will be permanently stored.

function storeWaterMarkedPhoto() {
 client.storeURL(transformURL).then(function(result) {});
}

(Function storing the watermarked photo with the URL.)

NOTE: If you want to transform, and store the photo in one step then you should use the ‘store’ transformation, and append the necessary content to the end of the transformation URL we built earlier. In this case, the original file will be transformed, and then immediately stored.

Implement Downloads

 

The transformed file is permanently stored, and the last step is to download the file. Just like the other API call we used (the client.pick(); method to upload the files) the storeURL method returns a results object. Like before, the result contains the information we need; however, last time we had to access our file using an index, and this time we do not. That is because the storeURL() function can only store one file, and so the result object necessarily only has information pertaining to that one file we just uploaded. In this case, we can simply access the information we need with: ‘result.information’ where the word information is replaced by the field we need from the result. To identify whether an API call’s result requires indexing to access the information, look at the result object and if there is a set of brackets ‘[…]’ it returned an array of results that need to be indexed through.

Another difference from last time we worked with a results object, is that we no longer need the file handle, instead we need the URL to download the file. In HTML5 there is a tag for downloading, which when clicked will execute downloading from the URL the tag points to. When we create the tag, it will not point to the URL of the stored photo, so we need to get that URL from the result we received after using storeURL on the transformed photo earlier. To do this, we can use the function document.getElementById() to find the tag (because each id is unique to its object), and then set the href field in the tag equal to the URL of the stored file.

<a id="Download Picture" href="" download> Click Here to Download! </a>

(HTML5 tag for downloading whatever href field is set to.)

function storeWaterMarkedPhoto() {
 client.storeURL(transformURL).then(function(result) {
 console.log(JSON.stringify(result));
 //Set the download tag href field to the permanently stored watermarked file
 document.getElementById("Download Picture").href = result.url;
 });
}

(Setting the href field in the download tag to download from the URL the transformed photo is permanently stored at.)

Now you are able to download files uploaded or transformed with Filestack using the HTML5 download tag. If you want to see the files that you have permanently stored with Filestack you can log into your developer portal, and click on the tab ‘assets’ to view them all.

Where to Go From Here

 

Congratulations! You have just built your first application using Filestack! There are plenty of ways you can keep improving on this project. For example, improving the design and user experience by including CSS, or using the multi file upload to watermark a group of photos at once! There are also plenty of other awesome transformations and services that Filestack offers you can make great things with.

Thank you for participating in my tutorial, and I hope you have learned something. If you have any questions or comments I would love to hear them and will do my best to respond. Also feel free to checkout my final code for this project in codepen, just do not forget to insert your API key!