Asset Factory

Digest

asset factory An asset factory provides a way to create a specific type of asset or specially configured page, such as blocks, external links, files, folders, pages, stylesheets, and templates.  New assets created via the asset factory need not be based on any particular asset, and may be placed in any folder.  Access to asset factories and the assets they create are determined by user access rights.

Concept

In addition to Cascade Server’s default asset factories, a system administrator may create customized asset factories by selecting an example page upon which future pages should be based.  New assets created by customized asset factories will have the same template, block, and stylesheet assignments, and a default region that must be populated with user-created content.  The administrator may also require specific asset factory-created pages to be placed in a pre-selected folder.

Each asset factory, whether default or customized, can be configured to display only to selected groups that already exist in the system.  Likewise, asset factories may also be grouped into container folders that allow for group access rights to be assigned to them.  Containers for asset factories appear as new sub-menus underneath the ‘New’ menu.  For example, a “Press Release” asset factory may be created and grouped into a container named Articles and have its access rights assigned to Group A.  Users that belong to Group A would view a new ‘Articles’ sub-menu when they click on the ‘New’ menu.

Technical

Creating an Asset Factory

Asset factories are valuable tools that enable non-technical users to easily create specific types of pages and other assets.  They are managed in the Administration area, but each must be based on an actual asset in the main area.  An ideal base asset will have all of the content that one would like to use as the default content, including configurations, for every asset that the asset factory creates.  We advise that all base assets are placed in a common folder.

To create a new asset factory:

  1. Go to the Administration area and select the ‘Asset Factories’ menu.
  2. Click Add Asset Factory
  3. Select the type of asset you would like to create.
  4. In the General pane, complete the following:
    1. Name- Describes the asset (eg. Press Release, Newsletter, etc.).
    2. Parent Container- Determines where the asset factory should be stored in the Administration area.
    3. Base Asset- Selects the asset on which the asset factory will be based.
    4. Placement Folder- Determines the default folder placement for all assets created using this asset factory.
    5. Subfolder Placement- Checking this allows assets created via this asset factory to be placed in subfolders within the placement folder.
    6. Folder Placement Position- Determines the order in which the new asset will appear in the folder. For example, a new press release may always need to be placed first in the folder in order for dynamic navigation menus to render them as most recent.
    7. Overwrite- Allows newly created assets to overwrite existing assets with the same name.
    8. Groups- Select from Available groups on the left, and move to the right to enable asset factory usage.
  5. In the Workflow pane, there are three possible modes for asset factories:
    1. Folder Controlled- Pulls workflow definitions from the folder in which the asset is being created within the asset factory.
    2. As Selected Below- Selects a workflow to be used for all assets created using this asset factory.
    3. None- Uses no workflow for assets created with this asset factory.
  6. On the Plug-ins pane, add one or more plug-ins by selecting from the drop-down menu and clicking the green + icon. Some plug-ins will prompt you to add various parameters.
  7. Click Submit to save your new asset factory.

newassetfaccreateasstfacnewassetfactype

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 (CascadeAssetFactoryPlugin.zip)

If you do not wish to use Eclipse to write your plug-in, you can develop against the asset factory plugin API which can be found here.

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:

            public void doPluginActionPre(AssetFactory, FolderContainedAsset)   

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.

            public Map<String, String> getAvailableParameterDescriptions()

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

            public String[] getAvailableParameterNames()

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.

            public String getDescription() 

This method returns a key into the resource bundle LINK TO PLUGINS HERE which is the description of the plug-in.

            public String getName()

This method returns a key into the resource bundleLINK TO PLUGINS HERE 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. 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.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.

Asset Factory References

Related Links

Knowledge Base Beta Feedback Form