Asset Factory
Digest
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.
Please note- if creating a new folder from an Asset Factory, links inside of content of pages and other assets of that folder are updated relative to the new folder. However, those pages' configurations will not simultaneously be updated. For example, when creating a folder, links in that folder's page content will get updated, but chosen blocks and formats in page configuration regions will not be updated/changed.
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:
- Go to the Administration area and select the ‘Asset Factories’ menu.
- Click Add Asset Factory
- Select the type of asset you would like to create.
- In the General pane, complete the following:
- Name- Describes the asset (eg. Press Release, Newsletter, etc.).
- Parent Container- Determines where the asset factory should be stored in the Administration area.
- Base Asset- Selects the asset on which the asset factory will be based.
- Placement Folder- Determines the default folder placement for all assets created using this asset factory.
- Subfolder Placement- Checking this allows assets created via this asset factory to be placed in subfolders within the placement folder.
- 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. The value "0" is used to place assets in the first folder position, while leaving the value blank is used to place assets in the last folder position.
- Overwrite- Allows newly created assets to overwrite existing assets with the same name.
- Groups- Select from Available groups on the left, and move to the right to enable asset factory usage.
- In the Workflow pane, there are three possible modes for asset factories:
- Folder Controlled- Pulls workflow definitions from the folder in which the asset is being created within the asset factory.
- As Selected Below- Selects a workflow to be used for all assets created using this asset factory.
- None- Uses no workflow for assets created with this asset factory.
- 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.
- Click Submit to save your new asset factory.
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 wish to use an IDE other than Eclipse 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.
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 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.
Cross-Site Relationships
For more information on Cross-Site relationships for Asset Factories, check out our Cross-Site relationship rules page.