KB Version:

Page Navigation

Related Links

Learning Levels

Most Read

Asset Factory

Digest

asset factory Asset Factories provide a framework which allows end-users to rubber stamp new assets with the necessary configurations already in place. Asset Factories can be created from scratch or can be used to create new assets based on the configurations of an asset that already exists in Cascade Server. For example, if new content of page type 'blog post' is frequently created, it is recommended that an Asset Factory is used to routinize this creation process. End-user access to an Asset Factory is determined by the applicable groups associated with that Asset Factory. Access to edit an Asset Factory is determined by user access rights.

Concept

More Insight into Asset Factories

In addition to the default Asset Factories included with Cascade Server, additional Asset Factories may be created. These additional Asset Factories can be constructed from scratch, or used to create new assets based on the configuration of assets already existing in the system, called base assets. If an Asset Factory of type page has a base page selected, then new pages created using that Asset Factory will have the same configuration (Content Type, Configuration Set, Metadata Set, Data Definition and Block and Format assignments in page regions) as the base page. New pages created with the Asset Factory will also have the same default content regions as the base page asset. Depending on how they are set up, Asset Factories might require a placement folder for assets created by the Asset Factory.

Each Asset Factory can be configured to display only to selected user groups that already exist in the system. Likewise, Asset Factories may also be put together into Containers that allow for groups to be assigned to them. Containers for Asset Factories appear as sub-menus underneath the New menu. For example, a 'Press Release' Asset Factory may be created and put into a container named Articles and have its access rights assigned to Group A. Users that belong to Group A would see a new Articles sub-menu when they click on the "New" menu.

In versions of Cascade Server 6.2 and newer, when creating a new folder from an Asset Factory that has a Base Folder selected, for example, a 'year' folder for a calendar, the links contained by assets inside of that folder will be resolved relative to that folder.

For example, when creating a new calendar year folder with month pages that link to each other by default:

Year 1 Year 2
Month A Month A1
Month B (which links to Month A) Month B1 (will be resolved to link to Month A1)


If under Year 1 folder, page called Month B links to a page called Month A and that Year 1 folder is a base folder for an Asset Factory, then upon creation of Year 2 using that Asset Factory, page Month B1 will have links resolved to now point to Month A1 instead of linking to original page, Month A.

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.  Asset Factories are managed in the Administration area but can be based on assets that reside in the home 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 created using that Asset Factory.  To avoid confusing Asset Factory base assets with published assets, it is advised that all base assets be placed in a Folder that is separate from Folders containing actual content.

To create a new Asset Factory:

  1. Go to the Administration area and select the Asset Factories’ menu on the left.
  2. Click New 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.). The name will be used as a label in the ‘New menu.
    2. Parent Container- Determines where the Asset Factory should be stored in the Administration area. Asset Factory Containers are used as submenus in the ‘New menu.
    3. Base Asset- Specifies the asset on which assets created using the Asset Factory will be based. If no base asset is selected, new assets will have no pre-populated content or configurations.
    4. Placement Folder- Specifies the Folder into which assets are placed when being created with the Asset Factory. If a Placement Folder is chosen, users will not be able to choose a different Parent Folder when using the Asset Factory unless the "Subfolder Placement" checkbox is checked. If not chosen, users will be able to choose any Parent Folder (as long as they have access to the Folder via permissions) when creating new assets using this Asset Factory.
    5. Subfolder Placement- Enabling this option allows assets created via this Asset Factory to be placed in subfolders of the Placement Folder.
    6. Folder Placement Position- Determines the order in which the new asset will appear in the selected Parent 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. The value "0" is used to place assets in the first folder position; leaving the value blank is used to place assets in the last folder position.
    7. Overwrite- Allows newly created assets to overwrite existing assets with the same name.
    8. Groups- Specifies which groups can access the Asset Factory in the New menu (these groups must also be applied to the Asset Factory's parent container).  To grant a group access to the Asset Factory, select it in the select box on the left and use the right arrow button to move it to the select box on the right.
  5. In the Workflow section, there are three possible modes for Asset Factories:
    1. Folder Controlled- Utilizes 'Create' Workflow Definitions that are available on the Folder into which the new asset is being created.
    2. As Selected Below- Uses a Workflow Definition specified on the Asset Factory itself.  The Workflow Definition is selected using the chooser that is available in the Asset Factory form.
    3. None- Uses no Workflow for assets created with this Asset Factory.
  6. On the Plugins pane, add one or more plug-ins by selecting one 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.
newassetfac
createasstfac

Writing Your Own Asset Factory Plug-In

Pre-requisites

This article assumes you have moderate Java programming knowledge as well as the latest Java Runtime Enviornment (JRE) installed on your machine (required by Eclipse). The JRE must be version 1.6.

Collecting the tools

Before you get started, Cascade 7.6.x users should download the following:

If you wish to use a different IDE to write your plug-in, you can develop against the asset factory plugin API standalone JAR. The source for the built-in plugins is included and requires the general Cascade API JAR.

Previous versions of the Asset Factory Plugin SDK:

Cascade 7.12.x - SDK or (standalone JAR and general API JAR)
Cascade 7.4.x - SDK or (standalone JAR and general API JAR)
Cascade 7.2.x - SDK or (standalone JAR and general API JAR)
Cascade 7.0.x - SDK or (standalone JAR and general API JAR)
Cascade 6.10.x - SDK or (standalone JAR and general API JAR)
Cascade 6.8.x - SDK or (standalone JAR and general API JAR)
Cascade 6.7.x - SDK or (standalone JAR and general API JAR)
Cascade 6.4.x - SDK or (standalone JAR and general API JAR)
Cascade 6.2.x - SDK or (standalone JAR and general API JAR)
Cascade 6.0.x - SDK or (standalone JAR and general API JAR

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) and the values are the descriptions of the parameters (keys into the resource bundle). 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 which is the description of the plug-in.

            public String getName()

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. 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 Global 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

If you loaded your plug-in and now you can't edit any of your Asset Factories (blank screen), the most likely cause 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.

Cross-Site Relationships

For more information on Cross-Site relationships for Asset Factories, check out our Cross-Site relationship rules page.

Asset Factory References

Related Links

Related Videos