Extend eXo Cloud Drive to new cloud services with the Connector API: Customization and configuration (Part 3 of 3)

CloudDrive-post3

In case you missed them, you can quickly jump to the previous parts of the series:

In this post we will finish the introduction to Cloud Drive add-on’s Connector API. As you already read in the first post, the Cloud Drive is an add-on that connects cloud files into eXo. It is extensible, thanks to the Connector API, and we have already reviewed its architecture and its Java API.

In this post you will learn how the client side can be customized via connector’s CSS and Javascript API. We will end by seeing how configuration and packaging work.

Styles customization

The eXo Platform and Cloud Drive offer UI customization via CSS. Drives, files (by their mimetype), and menu icons already have dedicated class names. To add your styles you will need to follow the conventions and place a properly named file, with required class names, in the right place. Then, when your connector initializes the cloud provider via UI context, this file will be loaded by the Cloud Drive client script. An example of how such a CSS file can look is in the template project in this file.

Javascript client

Cloud Drive uses client side Javascript for better integration with existing user interface of eXo Platform. File icons and ECMS context menus are customized directly in the browser to reuse the existing applications infrastructure. The client is also responsible for initiation of new drives’ connection and synchronization.

Cloud Drive client it is an AMD module registered in the Platform portal and loaded to ECMS Documents pages when the user opens a cloud drive folder. If the connector needs a custom Javascript, it should be registered as a module with the name cloudDrive/PROVIDER_ID. Then it behaves similarly to CSS loading: if the module is available for a drive provider, it will be loaded by the client and used to serve the drive.

One of important purposes of a connector Javascript is managing automatic synchronization. By default, the Cloud Drive client will do a periodic sync when a user opens the drive folder. But making periodic requests to the server isn’t the best approach, especially when nothing changes remotely. If your cloud service can inform you of changes in real time (e.g. by a “long-polling” request), there is a way to leverage this via Connector API.

Cloud Drive’s Javascript is based on asynchronous processing; it uses jQuery Deferred internally to implement this technique. If the connector script has a method onChange() it will be used to obtain a Promise instance that will be used to initiate the synchronization during the work. In this case, the logic of your connector will manage when a next sync request will be invoked, thereby reducing network traffic and making the experience better for your users.

If the client needs to deal with data specific only to your connector, Connector API offers several possibilities:

  • each connected drive may have a state—an object of any type that also will be returned to a client as a part of the drive response (/clouddrive/drive web-service)
  • you can implement your own RESTful service (somewhere at /clouddrive/drive/PROVIDER_ID) and request it from custom client module.

To customize or initialize the UI elements, the connector client can use jQuery.ready() handlers registered from its module. Below is a simplified example of a client module (it implements onChange() and read custom data from connector’s REST-service):

Configuration

When code needs to be executed, you will need a configuration for your connector. Follow this guide to learn how to configure existing connectors, and use it to practice for new connectors. Instructions for creating a configuration of components and connector extension can be found here.

In general, each connector needs the following configurations:

  • the connector’s extension in PortalContainerConfig. The connector should depend on the Cloud Drive extension and has priority higher than 1000.
  • The connector plugin of CloudDriveService. This defines all required parameters of the connector (ID, name, etc.)
  • proper display-name in the WAR of the connector
  • optionally it may need configuration of dedicated JCR namespaces and node types
  • optionally it may need UI extensions configuration (e.g. when offering a dedicated connect-menu)
  • optionally it may need CSS and Javascript configuration in the portal’s gatein-resources.xml
  • finally, if component configuration relies on variables, you need to define variables in configuration.properties or via JVM settings of the server.

Packaging and Deployment

At some point, you will need to deploy your connector to a Platform server. There are several ways, but we recommend using a proper one: use eXo Add-ons manager, a modern and friendly tool with a rich user experience. The Extension manager script, an older tool that already exists in eXo 4.0, can also do the job. In both cases you will need to package your connector as an add-on and make it available to the deployer.

Our template project already contains a packaging artifact. It is able to package all connector files in an archive compatible with the add-ons managers. If your connector uses third-party libraries, add them in the Maven dependencies and the assembly of the packaging. Build the project and use the resulting zip-archive, from the packaging, as an add-on for the installation.

An important notice about uninstallation: if you create some specific data that might damage the Platform in case of your add-on removal, consider using a correct uninstallation process. Note that dedicated UI actions, if they follow Cloud Drive UI requirements, will be automatically removed by the core add-on.

Done!

So, there you are. Now it’s time for you to create a new Cloud Drive connector and deploy it to the eXo Platform. Connector API opens a way for any developer to do this without changing the Cloud Drive code or configuration. I hope to see new connectors soon in the eXo Community.

Have a good time coding!

Join the eXo tribe by registering for the community and get updates, tutorials, support, and access to the Platform and add-on downloads!

Make the most out of eXo Platform 4

Register to the next webinar and get a complete overview of what you can do with eXo Platform 4. Reserve your seat now!

Be part of the discussion, share your comments

comments

Keep in touch with the author

Tags: , , , , , ,