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.

Webinar
How to Optimize for Page Load Speed

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:

Copy to clipboard
# 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:

Copy to clipboard
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:

Copy to clipboard
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:

Copy to clipboard
<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:

Copy to clipboard
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

Create Lightweight Sites With Low-Code and No-Code Technology

Consumers expect modern websites to be mainly visual. But, the more compelling and complex the related media is, the more data is involved, compounding the site’s weight. In today’s content-craving world, delivering unoptimized media can cost you because it leads to sluggish page loads, resulting in visitors abandoning your site in search of a faster alternative. In fact, a page load that takes more than three seconds can cause as many as 40% of your visitors to bounce. Given this competitive, digital-first environment, you can’t afford to lose page views, for time is of the essence.

Read more
A Blueprint for AWS-Secured Webhook Listeners for Cloudinary

tl;dr: An AWS-secured and optimized Cloudinary webhook listener for extending the Cloudinary service

Code: Github

A webhook is a communication medium for sending notifications from one platform to another about events that occurred. In place are user-defined HTTP callbacks that are triggered by specific events. When a triggered event takes place on the source site, the webhook listens to the event, collects the data, and sends it to the URL you specified in the form of an HTTP request.

Read more
New Accessibility Features for Cloudinary’s Product Gallery Widget

Cloudinary’s Product Gallery widget, which launched in 2019, has enabled many brands to effectively and efficiently showcase their products in a sleek and captivating manner, saving countless hours of development time and accelerating release cycles. By adding Cloudinary’s Product Gallery widget with its customizable UI to their product page, retailers reap numerous benefits, often turning visitors into customers in short order.

Read more
Why Successful Businesses Engage With and Convert Audiences With Visual Media

Most business buyers prefer to research purchase options online, as do many shoppers. No wonder online retail sales in the U.S. rose by 32.4% in 2020—an impressive gain of $105 billion.

For B2B and B2C businesses, text-heavy websites are no longer adequate in attracting shoppers. Instead, engaging visual media—spin images, videos, 3D models, augmented reality—are becoming a must for conveying eye-catching details and differentiators about products or services.

Read more
Making User-Generated Content (UGC) Shoppable With Cloudinary

User-generated content (UGC) is a powerful marketing tool. Not only does video complement marketing efforts for e-commerce by enabling customers to explore products in greater detail, but UGC also adds an element of trust. As a bonus, user-generated video is an exceptional opportunity for e-businesses to attract website traffic without their marketing team having to create promotional videos from scratch. User-generated content drives conversions and brand loyalty as a direct result of authentic interaction.

Read more