Tutorial: Displaying a Pro Gallery on Your Site Using the Pro Gallery Backend API

Before You Start

Before you start working with the Wix pro gallery in code, make sure to add a Pro Gallery to your site. In the steps below, we'll first take a look at the code piece by piece to understand what it's doing.

Important: Note the following limitations when converting backend gallery items to the frontend $w() Gallery items format:

• Backend galleries that contain text items can't be imported to your page code. Trying to do so throws an error, and breaks the gallery on your live site. This is because text items can't be converted to the frontend gallery items format, as the frontend $w() Gallery items currently only support image and video types.
• Backend galleries items that contain a link with text don't appear on your site. This is because the text property in the item's link object can't be converted to the frontend gallery items format, as the frontend $w() Gallery items object doesn't contain a link with text property.

Step 1: List All Pro Galleries on the Backend

In our example, we import the Pro Gallery API from the wix-pro-gallery-backend module. We then call the listGalleries() function to get a list of all existing galleries in our site's backend.

Here is sample backend code that we put in a web module (.jsw file):

import { proGallery } from 'wix-pro-gallery-backend';

export async function myListGalleriesFunction() {
  try {
    let galleryList = await proGallery.listGalleries();
    return galleryList;
    
  } catch (error) {
    console.error(error);
    // Handle the error
  }
}

Line 1: First, we import the pro gallery API from the wix-pro-gallery-backend module.

Lines 3-6: Next we create and export the myListGalleriesFunction() that awaits and returns the listGalleries() function.

Lines 7-11: We catch and handle any potential errors.

Important: The function in this web module is used for functional testing only. If you don't want to expose all your backend gallery contents, change the function's permissions to "Admin".

Step 2: Select a Gallery to Display on Live Site

Next we use functional testing to run the code above. The code returns list of backend galleries. We then select the gallery we want to display on our live site, recording its ID to be able to identify it in a later step. In our case, we want the ID shown below. Your list of backend galleries should look something like this:

Now that we know which gallery we want to use, we create a new function. This function calls the getGallery() function with the ID of the gallery that we chose. It then returns the gallery object that we selected.

export async function mySelectGalleryFunction() {
  const selectedGalleryId = "63ffd8e7-101b-49be-9498-00c2e6f5b65c";
  try {
    const selectedGallery = await proGallery.getGallery(selectedGalleryId);
    
    // Function continues below

Line 1: We create and export the mySelectGalleryFunction() that awaits the getGallery() function. Lines 2-6: We declare the gallery ID that we chose in step 1 as a variable, and pass it as a parameter in the getGallery() function.

Step 3: Convert Backend Gallery Items to Frontend Format

We need to take the backend gallery that we chose, and convert the items to the frontend $w() Gallery items.

    // Function continued from above

 // Convert the selected backend gallery's items to the frontend gallery items format.
    const convertedItems = selectedGallery.items.map(item => convertToFrontend(item));
 
    return convertedItems;

  } catch (error) {
    console.error(error);
    // Handle the error
  }
}

function convertToFrontend(item) {
  return {
    slug: item._id,
    type: item.type,
    src: item.image ? item.image.imageInfo : item.video.videoInfo,
    description: item.description,
    title: item.title,
    link: item.link ? item.link.url : undefined
  }
}

Lines 1-6: We map the selected backend gallery object's items to the frontend gallery object's items. We do this by calling the convertToFrontend() function that we create later on. Then we return these converted items.

Lines 7-12: We catch and handle any potential errors.

Lines 13-23: We create a function to convert the backend gallery items to the frontend gallery items. Note that the src is either image or video only, as the frontend $w() Gallery object doesn't support text items.

Step 4: Import Converted Gallery Items to our Page Code

To bring the converted gallery items to the frontend, we need to import the mySelectGalleryFunction function to our page code. We add a button element to our page, and call the imported mySelectGalleryFunction() function on button click. Then we set the frontend gallery element's items to the converted gallery items.

We add the following code to our page code:

import { mySelectGalleryFunction } from 'backend/myWebModuleFile';

$w('#galleryButton').onClick(async () => {
  try {
    // Call the mySelectGalleryFunction function to select the backend gallery and convert the backend gallery's items to the frontend items format. 
    const newlyConvertedGalleryItems = await mySelectGalleryFunction();
 
    // Set the frontend gallery element's items to the converted backend gallery items. 
    $w("#myGalleryElement").items = newlyConvertedGalleryItems; 
   
  } catch (error) {
    // Gallery not created
    console.error(error);
  }
});

Line 1: First, we import the mySelectGalleryFunction function from our module (myWebModuleFile.jsw file).

Line 2-6: We add an onClick() event handler to the button element on our page. In the event handler, we call the mySelectGalleryFunction() function.

Lines 7-9: Still in the event handler, we set the frontend gallery element's items to the newly converted gallery. This occurs when the button is triggered.

Lines 10-15: We then catch and handle any potential errors.

Important: Setting the frontend gallery element's items to the converted gallery items temporarily overrides the frontend gallery element's items with the converted backend gallery items. However, the pro gallery element's ID remains the same. For example, if you call the getGallery() function with the gallery element's ID, the original gallery element's items are returned, and not the converted backend gallery items.

All The Code

Here is the complete backend code (.jsw file) for this example:

import { proGallery } from 'wix-pro-gallery-backend';

export async function myListGalleriesFunction() {
  try {
    let galleryList = await proGallery.listGalleries();
    return galleryList;
    
  } catch (error) {
    console.error(error);
    // Handle the error
  }
}

export async function mySelectGalleryFunction() {
  const selectedGalleryId = "63ffd8e7-101b-49be-9498-00c2e6f5b65c";
  try {
    const selectedGallery = await proGallery.getGallery(selectedGalleryId);
    });
    
    // Convert the selected backend gallery's items to the frontend gallery items format.
    const convertedItems = selectedGallery.items.map(item => convertToFrontend(item));
 
    return convertedItems;

  } catch (error) {
    console.error(error);
    // Handle the error
  }
}

function convertToFrontend(item) {
  return {
    slug: item._id,
    type: item.type,
    src: item.image ? item.image.imageInfo : item.video.videoInfo,
    description: item.description,
    title: item.title,
    link: item.link ? item.link.url : undefined
  }
}

Here is the complete page code for this example:

import { mySelectGalleryFunction } from 'backend/myWebModuleFile';

$w('#galleryButton').onClick(async () => {
  try {
    // Call the mySelectGalleryFunction function to select the backend gallery and convert the backend gallery's items to the frontend items format. 
    const newlyConvertedGalleryItems = await mySelectGalleryFunction();
 
    // Set the frontend gallery element's items to the converted backend gallery items. 
    $w("#myGalleryElement").items = newlyConvertedGalleryItems; 
   
  } catch (error) {
    // Gallery not created
    console.error(error);
  }
});