File and Image Management

Kibo eCommerce provides you with a few file management tools. The main tool is File Manager, which allows you to upload files to Kibo eCommerce, but you also have access to tools that allow you to refresh the cache and manipulate images with URL or Hypr tag parameters.

The File Manager stores files for your site on the CDN in a folder structure. This allows product images to be managed at the master catalog level, including being tagged for easy searching and filtering. For example, you could create a folder for Apparel with subfolders of Shirts and Pants for images associated with Products in those categories.

Access this tool at Main > Content > Files.

Tree Navigation

File Manager's folder structure is a tree hierarchy, which is displayed on the left side of the UI and lists all folders within the master catalog. The current master catalog can be changed in the top header - each master catalog can maintain a different tree and set of files.

Clicking a folder on the left will display its files and information (image icon, date created, name, size, type, and any tags) in the main view of the UI.

Use the search bar to perform a global search across all folders by file name. Or, search by tags by expanding the Advanced Filter icon on the search bar. Enter a tag value in the text field and click Filter to view all files tagged with that value.

In the file view, you can sort the files by ascending/descending File Name by clicking the arrows in that column header. You can also customize which columns are shown or hidden by selecting or deselecting them in the drop-down menu in the top right.

Manage Folders

When you have selected a folder in the tree navigation menu, the Actions menu allows you to create a new folder, delete the selected folder, rename the selected folder, move the selected folder, or upload files to that folder. If a folder has not been selected, then the only available actions will be creating a new folder or uploading files to the root Files folder.

This Files folder is the ancestor of all other folders you create, and will always exist in your file structure. The only actions that can be taken on Files are Create (to create a new child folder) and Upload (which will store the new files directly under the Files folder).

When creating a folder, you will be prompted to name the new folder. Click Create to add it to the tree hierarchy, at which point you will be able to navigate to it and add files.

If moving an existing folder, you will be prompted to select a new destination folder. The source folder and all of its subfolders and files will then be relocated to the destination.

Upload Files

To upload files to a selected folder, click Upload from the folder actions in the tree navigation menu. If a folder is not selected, then uploaded files will be placed in the root Files folder.

Click Choose to open your operating system's file manager and select files from your computer, then click Upload once files have been chosen.

There are some restrictions and behaviors to keep in mind when uploading files:

• You can add files of most file types up to 20 MB directly to File Manager for use in any catalog or site. There is no limit on the amount of files that can be uploaded at any time.
• You can upload .jpeg, .jpg, .png, and .tiff files. PDFs can be uploaded for storage purposes but will not be rendered as images. Video files are not supported.
• There is no character limit on file names, but tags have a limit of 100 characters.
• Duplicate file names in the same folder are not allowed. If you upload a file with the same name then File Manager will append a number to the name such as {NAME}_1.
• All files (such as images) you add through product settings pages are automatically added to File Manager under the Files root folder.
• You can visit File Manager at any time to view file names, file creation times, file sizes, URLs, and other details about your CDN files.
• Files on the CDN are cached for two weeks, but if your theme developer creates the links to the files using the make_url tag with the cdn mode, you can refresh the cache at any time using the Bust Cache feature available in General Settings.

Manage Files

In the main file view of the UI, there are a set of buttons that allow you to perform the following options when a file is selected: Delete (which will remove the file from File Manager), Get URL (see the Link to an Uploaded File section), Copy (which will allow a file to be pasted to another location as a duplicate), and Move (which will change the file's location).

When moving a file, a modal will appear that lets you select the new destination. Click Move when you have highlighted the new location to confirm.

To rename a file or manage tags, click the pencil icon on the far right of a file. This will make the name field editable, as well as add a blank editable field for a new tag. Any existing tags can be clicked to remove them. After making changes, click Save.

Tags help organize your files by making them easily identifiable and searchable. For instance, if you have a number of apparel images then you could tag them with "jacket" or "jersey" to distinguish them. Then, you could search File Manager for the "jacket" tag and quickly retrieve all jacket images.

Set Product Images

After files have been added to File Manager, they can be selected as product images as well as added to the storefront via widgets. When setting an image for a product in the catalog, click Upload from File Manager to select one of your files.

This will open a modal that mimics the File Manager interface. This picker allows you to navigate your file structure and search across folders by name to locate your desired image. Check the box of any images you wish to add to the product, then click Select. The image(s) will then be listed as options in the product images setting.

Link to an Uploaded File

After you upload a file to File Manager, you can access a unique URL on the CDN to link to the file. If you are a theme developer who wants to link to a CDN file in a Hypr template, the recommended method is to use the make_url tag.

1. Go to Main > Content > Files.
2. Navigate to or search for the file you want to link to, and select the file.
3. Click the Get URL operation at the top.
4. A pop-up will display two URLs for the file on the CDN, based on the file name and the ID. Copy whichever path you prefer to use.
5. To link to the file in a Hypr template, use the make_url tag with the cdn mode to have eCommerce generate a URL with a cache key appended (which allows you to refresh the cached version of the file using the Bust Cache feature in General Settings).

Upload a Custom Sitemap

For SEO reasons, you may wish to create your own sitemap and use it in place of the default sitemap. You can upload a custom sitemap using File Manager. After uploading your sitemap, you can point crawlers to it using redirects or by editing your site's robot.txt file.

To upload a custom sitemap:

1. Create your custom sitemap outside of the Kibo Composable Commerce Platform and name it sitemap.xml.
2. Upload your custom sitemap to your site using File Manager.

Point Crawlers to Your Sitemap

After uploading your custom sitemap, you need to either add redirects or edit your robots.txt file to point crawlers to your sitemap.

To point crawlers to your custom sitemap using redirects:

1. Go to Main > Content > Redirects.
2. Select your site using the site selector drop-down.
3. Configure the following two redirects from the default sitemap to your custom sitemap:

   Source	Destination
   sitemap.xml	cms/files/sitemap.xml
   sitemap	cms/files/sitemap.xml

4. Enable Rewrite on the redirects to keep the source URL from changing during the redirect.

To point crawlers to your custom sitemap using the robots.txt file:

1. Go to System > Settings > General Settings.
2. Under Robots, upload a robots.txtfile that includes the following line specifying the absolute path to your sitemap:

   Sitemap: http://www.yourSite.com/cms/files/sitemap.xml

Bust Cache

Bust cache allows you to update the URL for image files in order to force your storefront to display the latest version instead of those that might be saved in cache. Access bust cache in the Admin General Settings at System > Settings > General Settings.

Your theme developer must first enable the Bust Cache feature in your theme files before it has any effect on your CDN files.

Enable Bust Cache

To enable bust cache, your theme developer must complete the following steps:

1. Open a theme file that contains CDN content.
   For example, open templates/modules/product/product-listing.hypr.live for editing.
2. Replace any Hypr tags that reference the file URL and object model with the make_urlHypr tag. For example:

   Replace

   <img src="{{model.mainImage.imageUrl}}?max={% block thumbnail-size %}{{ themeSettings.listProductThumbSize }}{% endblock thumbnail-size %}" />

   With

   <img src="{% make_url "image" model.mainImage %}" />

   Include Additional Fields

   You can include additional image fields (like the max field) by appending the fields to the end of the tag, between with and as_parameter, as follows:

   <img src="{% make_url "image" model.mainImage with max=themeSettings.listProductThumbSize extraExampleField=1 as_parameter %}" />

Result

The URL of the CDN file you apply the make_url tag to may look something like the following URL, where the number after mzCB is randomly generated each time you click Bust Cache in the Admin.

cdn.subdomain.com/img.jpg?max=150&extraField=1&_mzCb=908908080

Enable Bust Cache for Non-CDN Files Uploaded in Your Theme

You also can enable bust cache directly on a link destination for non-CDN files that you upload through your theme, as follows:

<a href="{% make_url "cdn" "/resources/images/example.png" with max=234 as_parameters %}">Link Text</a>

Result

Kibo eCommerce prepends a CDN location to the specified file and applies a CDN cache key so that the file is updated every time you click Bust Cache in the General Settings.

<a href="//cdn..../1023-434/resources/images/cat.png?max=234&_mzCb=234929834923498">Link Text</a>

Access the Cache Key Value Through JavaScript or in a Hypr Template

After you enable bust cache, you can access the cache key value (the randomly generated number appended to the CDN file URL) through JavaScript as shown in the following example:

require(['hyprlivecontext'], function(HyprLiveContext) {
                    HyprLiveContext.locals.siteContext.generalSettings.cdnCacheBustKey;
                    })
            

In addition, you can access the cache key value in a Hypr template using the following code:

siteContext.generalSettings.cdnCacheBustKey // (available in the HyprLive context)

For example:

<a href="//cdn.mozu.com/sampleDoc.pdf?_mzCb={{siteContext.generalSettings.cdnCacheBustKey}}">My Document</a>

CDN Image Manipulation

When you use the make_url tag on an image hosted on the CDN, you can include the following additional fields at the end of the tag, between with and as_parameter, to process the image. You can also apply these fields as URL parameters appended to the image path after a ? character and separated by & characters.

make_url Example

{% make_url "image" model.mainImage with max=500 quality=75 crop="10,10,-10,-10" as_parameters %}

URL Parameter Example

http://cdn.mozu.com/22440-m1/cms/files/filename?max=500&quality=75&crop=10,10,-10,-10

Field	Description
max	Specifies a pixel limitation for the largest side of an image.
maxWidth	Specifies a pixel limitation for the width of the image, preserving the aspect ratio if the image needs resizing.
maxHeight	Specifies a pixel limitation for the height of the image, preserving the aspect ratio if the image needs resizing.
width	Specifies an exact width dimension for the image, in pixels.
size	Same as width. Provides backwards-compatibility for an earlier syntax.
height	Specifies an exact height dimension for the image, in pixels.
crop	Usage: crop=x1,y1,x2,y2 in URLs and crop="x1,y1,x2,y2" in the make_url tag. Crops the image based on the specified coordinates. The reference point for positive coordinates is the top or left side of the image, and the reference point for negative coordinates is the bottom or right side of the image. You can use this field to easily crop an equal amount of pixels from every edge of the image. For example, crop=10,10,-10,-10 removes 10 pixels from all edges of the image (crop=0,0,0,0 leaves the image uncropped). You can also use this field to specify a subset of the image. For example, crop=150,-300,-150,300 crops the following image as shown. Using positive or negative coordinates is up to you. For example, you can crop the same subset of the example image using coordinates that are all positive, all negative, or a different combination from the one shown in the example, such as crop=+,+,-,-. The only thing to remember is that you must always specify x2 to the right of x1 and y2 to the bottom of y1, otherwise no cropping takes effect.
quality	Adjusts the image compression for JPEG files (other image types do not support this field). Accepts values from 0-100, where 100 = highest quality, least compression.