Cloudinary Blog

Cloudinary Image Gallery with Stencil Custom Components

Cloudinary Image Gallery with Stencil Custom Components

When you need to build small custom web components that can be used across all frameworks - Angular, React, Vue vanilla JS and others - Stencil is an ideal tool. Stencil enables you to create platform-independent components that can be exported as a true web component and used anywhere.

Check out our StencilJS Posts:

This article shows how to build an image gallery with Cloudinary-stored images using Stencil. Cloudinary is an end-to-end image and video management solution. The Cloudinary Image API is very easy to use and exposes image manipulation techniques via HTTP URLs. If you have never used Stencil, you can get started with this article.

Setup a Media Library and a Stencil Project

Let's start with uploading some images to the Cloudinary server and setting up a Stencil project.

Create a Cloudinary Account

We will upload images using the Cloudinary dashboard. In real projects, however, you should have a server that uses the Cloudinary SDK to upload these images.

  1. Create a Cloudinary account by signing up for the free plan, offering 300,000 images.
    Cloudinary Sign Up
  2. On your server dashboard/console, click on Media Library in the navigation bar.
  3. Use the image upload widget on the Media Library page to add images to your server.
    Cloudinary Media Library

Create a Stencil Project

The first thing we need to do with Stencil is to set up a boilerplate for a Stencil project. Fortunately, the Ionic team provides a starter template to simplify this setup process. All you need to do is clone this starter template, install the template and start your new project:

# Clone
git clone https://github.com/ionic-team/stencil-starter.git cl-gallery

# Enter project
cd cl-gallery

# Remove original Github history
git remote rm origin

# Install dependencies
npm install

Create a Gallery Data Source

A typical gallery app or widget requires a data source. Most real situations would probably require fetching these data from a server or an API endpoint. There is no need for that in this app. We are going to create a mock data that looks like what a server would send to us.

Create db.ts in your src directory with the following content:

Full code available HERE

Just an export of an array of gallery images. Each gallery item is represented as an object with an image ID, collector/author and description about the image. The image ID (imageId) is the same ID you get when you upload an image to Cloudinary server. We can use the these IDs to fetch the images from Cloudinary.

Deliver and Transform Images with Cloudinary SDK

The browser will not understand an image ID. We need to use the Cloudinary SDK to convert image IDs to URLs. This process is known as “delivery.”

We also need to define a width and quality attribute for the image. This process is done with the SDK and referred to as “transformation.”

Before we dive into these, let's first create a container component to serve as our app shell and interact with Cloudinary. Create a folder site in the components directory with the following contents:

  • app-site.scss
  • app-site.tsx

Then update theapp-site.tsx file with the following content:

import { Component } from '@stencil/core';
import cloudinary from 'cloudinary-core';
import data from '../../db';

@Component({
  tag: 'app-site',
  styleUrl: 'app-site.scss'
})
export class Site {

  cloudinary = null;
  galleryImages = [];

  componentWillLoad() {
    this.cloudinary = cloudinary.Cloudinary.new({
      cloud_name: ''
    })
    this.galleryImages = data.map(this.transform.bind(this));
  }

  transform(image) {
    const imageUrl =
      this.cloudinary.url(image.imageId, { width: 300, crop: "fit", quality: 'auto', secure: true });
    return Object.assign(image, { imageUrl });
  }

  render() {
    return (
      <div class="wrapper">
        <nav>
          <div>CL Gallery</div>
        </nav>
        <div class="gallery-images">
          {this.galleryImages.map(image => 
            <cl-gallery-item image={image}></cl-gallery-item>
          )}
        </div>
      </div>
    );
  }
}
  • Stencil looks very much like React because it uses JSX and has a resemblance in syntax. A component is defined as a class, but it is decorated with the Component decorator that we imported from the Stencil core above. The tag in the decorator is what is used to mount this component in a containing template, while the styleUrl is the SCSS file that defines the component's styles.
  • The class has two properties, cloudinary and galleryImages. cloudinary is going to keep a reference to the configured Cloudinary instance. This configuration happens when the component is about to be mounted in componentWillLoad. galleryImages keeps references to the array of images from our data source.
  • componentWillLoad is executed before component loads, so we are setting up Cloudinary and our data store before the component is rendered. To configure Cloudinary, pass in the cloud name from your Cloudinary server.
  • The data store is transformed before being passed to galleryImages. It's transformed with a transform method, which generates a URL and transforms the image using the object passed as second argument.
  • Finally, we use JSX to render a child component, cl-gallery-item that receives each item from the galleryImages via props.

Rendering Images with Child Component

Create another component folder, cl-gallery-item with the following files:

  • cl-gallery-item.scss
  • cl-gallery-item.tsx

The following logic should be in your TSX file:

import { Component, Prop } from '@stencil/core';


@Component({
  tag: 'cl-gallery-item',
  styleUrl: 'cl-gallery-item.scss'
})
export class ClGalleryItem {

  @Prop() image: any;

  render() {
    return (
      <div class="cl-gallery-item">
        <img src={this.image.imageUrl} alt=""/>
        <h3>{this.image.collector}</h3>
        <p>{this.image.description}</p>
      </div>
    );
  }
}

The only change here is that we decorate a property with Prop. This property is called image and maps to the property that was passed to this component from the parent component, app-site.tsx. The property holds a gallery item, which we can then display using JSX.

Update App's Entry Point

Originally, this project has one component, which is the default component. The component is named my-name. Open index.html and you will see it's right there, so even if you keep running the app with all these changes, the visuals will never update.

Update the index.html and replace my-name component with app-site and we are good to go:

<html dir="ltr" lang="en">
<head>
 ...
</head>
<body>

  <app-site></app-site>

</body>
</html>

Run the following command to see the app running at port 3333:

npm start

You should see a simple grid like the one shown below:

Stencil final example

Feel free to check out the code on GitHub.

Conclusion

Stencil is quite promising and it stands out because of its ability to export components that are compatible with any other JavaScript environment. It enables you to write light components for widgets, like a Cloudinary Gallery; export the components; and import them in your Angular, React or Vue project. Cloudinary offers more than what we just discussed, including file upload, image manipulation, image optimization, and more. You can learn about all these features or get started for free.

Recent Blog Posts

Rotating Or Removing Image Backgrounds With Cloudinary

As a rule, user interfaces, whether for mobile or desktop apps, encompass a significant amount of visual media (images and videos), necessitating close collaboration among designers and front-end developers. The process for building UIs entails a designer-to-developer handoff, at which the designer transfers to the developer blueprints produced with such tools as Photoshop, InVision, and Sketch. The developer then implements the blueprints with Cascading Style Sheets (CSS).

Read more

Open Hack Week: Building for the Future

By Obinna Ekwuno
Open Hack Week in Lagos, Nigeria: Building for the Future

Between July 29 and August 3, the Google Developer Student Community of the University of Lagos, Nigeria participated in a week-long hackathon called Open Hack Week (OHW). Sponsored by Cloudinary, Interswitch, the Ogundipe Foundation, and other notable organizations, OHW comprised 14 teams, five developers each. After six days of brainstorming and coding, the teams successfully built the minimum viable products (MVPs) for their projects, which they subsequently presented to all the attendees.

Read more
Compress Images for Web and Boost Performance on Your Site

Slow-loading web content and problematic media displays that involve seemingly interminable scrolling tick off users to no end. Compressing online images is, without question, a critical task for spearheading customer retention for websites. Keep in mind that small images can still look sharp. This article shows you how to achieve that by mastering the techniques of compressing images for the web.

Read more
Customize your video player with Cloudinary Studio

Steve Forbes, editor of Forbes Magazine, once said, “Your brand is the single most-important investment you can make in your business”. That bold statement is spot on, especially with respect to digital media. Furthermore, consistency in brand experience is crucial for building trust with users.

Read more
How to Create WordPress Responsive Images

With the advent of technology and the attendant fast-growing demand for feature-rich computing devices (laptops, smartphones, iPads), their manufacturers are rising to the occasion by producing high-resolution machines with screens of various sizes and device-pixel ratios. Thus was born the impetus behind the need for and creation of responsive images, which automatically optimize their online display according to the size and resolution of the device screen, ensuring sharpness and crispness—a delightful user experience.

Read more