This module contains the implementation of the Cloudinary Content Picker for Jahia 8.1.x.x
With this module, a contributor can easily add a Cloudinary media asset to a Jahia page.
This module contains:
- The definition of a
Cloudinary Asset Content Reference
content (definition.cnd). - A React application :
Cloudinary Content Picker
(CloudinaryPicker.jsx). This application is a custom jContent SelectorType (aka picker) and is used to pick a Cloudinary asset. - A proxy servlet filter used to call the Cloudinary Admin API from the frontend
Cloudinary Proxy Servlet
(CloudinaryProxyServlet.java). - A light implementation of an External Data Provider (EDP) named
Cloudinary Asset Provider
(CloudinaryDataSource.java).
Not covered in this module:
- CKEditor Cloudinary media picker
The module can be installed in 2 ways, from the source or from the store.
- Download the zip archive of the latest release.
- If you already know your Cloudinary configuration (API key, site, and host) you can update the default configuration about Cloudinary. Update properties in the cloudinary_picker_credentials.cfg file.
- Go to the root of the repository.
- Run the
mvn clean install
command. This creates a jar file in the target repository.you must have a java sdk and maven installed
- In jContent, go to
Administration
panel. - In the
Server
section, expandModules and Extensions
and clickModules
. - From the right panel, click
SELECT MODULE
and select the jar file in the target repository. - Finally, click
UPLOAD
.
-
In jContent, navigate to
Administration
. -
In the
Server
section, expand theModules and Extensions
entry and clickModules
. -
From the right panel, click
Available modules
and search for cloudinary. -
Click the install icon
in the right of the package to download and install the module.
-
Wait until the module is loading.
If the module is properly deployed you should find it in the Installed modules
section.
If you have installed the module from the store or if you didn't configure the properties in the cloudinary_picker_credentials.cfg file before to build the module, you must do the post install to have the Cloudinary provider starting.
Don't forget to enable the module for one of your project
Skip this section if you have already configured the cloudinary_picker_credentials.cfg file during the install from the source process. This configuration doesn't require a server restart.
To request the Cloudinary server, you have to configure the module with your Cloudinary API access information.
To set up your Cloudinary API access:
-
Go to jahia tools (https://<jahia host>/tools).
-
From the tools UI, click
OSGI console
under Administration and Guidance. -
In the top menu expand the entry OSGI and click Configuration.
-
Look for
org.jahia.se.modules.cloudinary_picker_credentials
and click on it. -
Finally, update the appropriate properties and save your changes.
-
If all the properties are set correctly, the provider should start, and you should see the
cloudinary
key in the list of External providers. -
Now, you should be able to create a new
Cloudinary Content Reference
content. More details at the end of this doc.
To pick a cloudinary asset (for example a video, image, or PDF) from a Cloudinary Cloud instance, you need to implement:
- A React application named
Cloudinary Content Picker
, and used as aselectorType
in jContent. This picker is a user interface (UI) from which a jContent user can query a Cloudinary server to find and select the media asset they want to use on the website. - A proxy servlet filter used to call the Cloudinary Admin API from the frontend :
Cloudinary Proxy Servlet
. - A light External Data Provider (EDP), named
Cloudinary Asset Provider
, that maps the JSON returned by the cloudinary Admin API and represents the Cloudinary asset into a Jahia node.
The data flow is composed of 8 actions of which 2 are optional and depend on the cache.
-
From a website page, the user creates or updates a
content reference
to a Cloudinary asset content (akaCloudinary Content Reference
). Then, jContent displays a user form with a Cloudinary Content field. The React applicationCloudinary Content Picker
used as aselectorType
is launched and displays a placeholder.A selectorType has 2 main component : one used to present the selected content (or a placeholder if no content is selected), and one used to pick a content. In this module this picker is the cloudinary Media library app
-
When user clicks the Cloudinary Content field, the Media library web application provided by Cloudinary is launched into a modal. This media library interact directly with the cloudinary backend.
To know more about the Media Library.
-
When user insert a new asset, the media library returns a JSON object containing the public_id of the asset. This id can evolve. Thus, the content picker uses it immediately to search the asset with the Cloudinary Admin API through a proxy and get the fixed asset_id
The proxy uses the Cloudinary Search API.
-
When the user saves their choice from the picker, a content path is created. This path is built with a static part
/sites/systemsite/contents/dam-cloudinary
, and theasset_id
of the Cloudinary asset.jContent cannot use this path directly as it expects to receive a Jahia node id. Therefore, the content picker executes a GraphQL call to create the node and get its id back. During this call, the path is resolved and mapped to a Jahia node with the help of the
Cloudinary Asset Provider
. -
If the selected asset is not in the jContent cache, the provider calls the Cloudinary Admin API endpoint to get the relevant properties about the selected asset.
The provider uses the Cloudinary Search API.
-
The JSON response returned by the API is mapped to a Jahia node and cached into an Ehcache instance named
cacheCloudinary
. By default, the cache is configured to keep the content for a maximum of 8 hours and to drop the content if it is idle for more than 1 hour. -
If the path provided in step 4 is correct, the provider return a Jahia reference node, and the user can save their
Cloudinary Content Reference
content. The content can be used by a jContent Page. This module provides jContent views for different type of cloudinary assets (for example images and videos). -
The jContent views use the cloudinary content URL to get and render the content in a webpage. The Cloudinary CDN improves performance when assets load and allows Cloudinary to collect statistics. The Cloudinary asset is rendered into the website.
you can select the view of the content in reference. You can also select the width and the height, if your asset is an image.
The complete flow is the following :