KB Version:

Page Navigation

Related Links

Learning Levels

Most Read

Asset Factory Plug Ins

Digest

asset factory The asset factory plugin framework allows administrators to tie Java plugin classes with certain asset factories. These plugins, configurable through a file named "asset-factory-plugin-config.xml", allow administrators to accomplish certain tasks as users create new assets from asset factories.

Technical

Writing Your Own Asset Factory Plug-In

Pre-requisites

This article assumes you have moderate knowledge of how to program in Java as well as the latest Java Runtime Enviornment (JRE) installed on your machine (required by Eclipse). The JRE must be version 1.5 or later.

Collecting the tools

Before you get started, you should collect the tools you need to develop a Java project. Please download the following two items:

Eclipse IDE (http://www.eclipse.org)

Asset Factory Plugin SDK (asset-factory-plugin-SDK)

Note: To download the SDK for older versions of Cascade Server:

Installing Eclipse and Opening the SDK

Once you download Eclipse you will want to unzip it to a directory of your choosing (suggestions: c:\java\eclipse or c:\Program Files\Eclipse on Windows, /usr/local/eclipse on Linux, or ~/java/eclipse on OS X). Start Eclipse and you will be prompted to choose a workspace location - the default location should suffice. Make note of it as this is where we will unzip the SDK to.

Next, you will unzip the Plugin SDK to your workspace directory. The zip should create it's own directory inside your workspace directory.

Finally we will bring in the Plugin SDK (which is really just an Eclipse project) into Eclipse. To do this, right click in the package explorer view on the left hand side and select "Import...". Then, select "Existing Projects into Workspace" under "General" and click "Next". Select "Browse" next to "Select root directory:" and browse to the directory created when you unzipped the SDK. You should then see "Asset Factory Plugin" under "Projects". Click "Finish".

You should now see the project in your Package Explorer. The project has two packages:

  • The resources package - this is where your "resource bundles" will live. A "resource bundle" is a set of localized strings describing various aspects of your asset factory plugin, such as the name, description, and the names and descriptions of any parameters your asset factory plugin may utilize. Note that the name of this package must be "resources" and must live off the root of the project.
  • The "com.mycompany.cascade.plugin" package - this package can be renamed to whatever you desire - this is where your plugin class will reside.

Writing the Plugin Class

A plug-in is a Java class that implements the AssetFactoryPlugin interface. It is strongly recommended that you extend the BaseAssetFactoryPlugin class because it contains the implementation of helper methods that the framework relies on.

The plug-in writer will need to implement the following methods:

 

This method is called before the user has performed the initial edit. The FolderContainedAsset passed as a parameter will contain the data from the asset factory's default asset, if one is set. At this stage, the asset has not yet been created.

This method is called after the user has performed the initial edit. The FolderContainedAsset passed as a parameter will contain the data the user entered combined with the data from the asset factory's default asset. At this stage, the asset has not yet been created.

 

This method shall return a map where the keys are the names of the parameters (keys into the resource bundle?) and the values are the descriptions of the parameters (keys into the resource bundle?). This method must return a non-null Map object.

 

This method returns a non-null array of strings which are keys into the resource bundle?, each of which is the name of a parameter this plug-in can take.

 

This method returns a key into the resource bundle? which is the description of the plug-in.

 

This method returns a key into the resource bundle? which is the name of the plug-in

What is a "key into the resource bundle"?

The resource bundle is a file that allows internationalization of your plug-in. This file is formatted with key/value pairs, one on each line. The key is generally a dotted string (example: "name.of.my.plugin") and the value is a human-readable string (example: "This is the name of my plug-in"). The key/value pairs are separated by an equals ("=") sign. You can find two sample resource bundles in the Asset Factory Plug-in SDK.

Disallowing asset creation

A powerful aspect of asset factory plug-ins is their ability to determine which assets are allowed to be created and which aren't. By default, assets are always allowed to be created. However, if a plug-in writer deems that due to some conditions an asset is not to be created, that plug-in writer can throw a new FatalPluginException that contains the reason why the asset cannot be created. The plug-in writer can also call the function setAllowCreation() with the first boolean parameter set to false and the second String parameter explaining why the asset was not allowed to be created. The framework will then check this and pass the specified message up to the user.

Note: By default, a plug-in is set to allow assets to be created, so if your plug-in is not intended to restrict creation, you will not need to add any additional code.

Exceptions

Asset Factory Plug-ins may use two types of exceptions: a PluginException or a FatalPluginException. A PluginException is a general exception that will NOT stop other plug-ins from executing, but it will halt the execution of the current plug-in. A FatalPluginException stops other plugins from executing AND tells the plug-in framework to not allow the asset to be finalized and put into the system.

What to do with your plug-in

First, create a JAR file containing your plug-in file and the resource bundle(s) it references. To do this, right click on your project in the Package Explorer (left hand side) in Eclipse and select "Export...". Under the "Java" section, select JAR file and click "Next". Next you will be prompted as to which files to include. Ensure the checkboxes for your plug-in package and resources package are selected. The checkbox next to the "src" folder should be unchecked while "src/java" should be checked. If you click on your project, you will see that the ".classpath" and ".project" files are included, which are unnecessary and should be unchecked so they are not included in the JAR. The rest of the default options should be fine (only things checked are "Export generated class files and resources" and "Compress the contents of the JAR file"). Under "Select the export destination:", select where the JAR file will be temporarily placed before deployment to Cascade Server. Click Finish.

To deploy the plug-in JAR, first you must shut down Cascade Server. Next, locate the JAR file and place this file in <Tomcat_Installation_Location>/webapps/ROOT/WEB-INF/lib under the Tomcat Deployment directory. JAR files placed in this location are automatically loaded along with other libraries needed by Cascade Server. Once you have done this, start Cascade Server and go to the Asset Factory section in the Administration area and select Manage Plugins. In the "Add a Plugin" text field, enter the fully qualified Java class name of your plug-in (for instance, "com.mycompany.cascade.plugin.MyPlugin") and click Submit. The plug-in will then be added and will be accessible in the "Plug-ins" tab when editing an Asset Factory.

What can go wrong

Help! I loaded my plug-in and now I can't edit any of my Asset Factories (blank screen)

The most likely cause for this is Cascade Server is being told to look for a key which does not exist in the resource bundle you have supplied. If you can examine the logs, you will more than likely see a message about "Could not locate key for this.is.the.missing.key". You will need to ensure that all the keys that you return in your getAvailableParameterDescriptions(), getAvailableParameterNames(), getDescription(), and getName() functions point to valid keys in your resource bundle for all locales.

Available Plug-Ins

  1. Create Resized Images Plug-in
    This plug-in allows an administrator to specify that multiple resized images will be created when a user uploads a single image.

     

  2. Display to System Name Plug-in
    This plug-in ensures that newly-created assets are given search engine friendly system names.

     

  3. File Limit Plug-in
    This plug-in allows administrators to place restrictions on the size and type of file created using a specific asset factory.

     

  4. Set Start Date Plug-in
    This plug-in sets the metadata field "start date" to the current time for newly created assets, with an optional configurable offset.

     

  5. Friendly Page Name Plug-in
    This plugin limits the system name of new page assets to configurable regular expression.

     

  6. Title to System Name Plug-in
    This plug-in ensures that newly-created assets are given search engine friendly system names.

     

  7. Image Resizer Plug-in
    This plug-in allows an administrator to specify that an uploaded image be resized to particular dimensions.

     

  8. Data Definition Field to System Name Plug-in
    This plug-in takes the value from a specified structured data field, makes it "safe" by removing non-SEO characters, and turns that into the system name for the new asset.

     

  9. Structured Data Fields to System Name Plug-in
    This plug-in takes the value from ultiple specifies structured data fields, concatentes them together, and turns that into the system name for the new asset.

     

Related Links