Click or drag to resize
AlchemyPlugin Anatomy

This topic contains the following sections:

An Alchemy4Tridion plugin (aka plugin package) is a specially formatted file that contains everything that your plugin needs including DLL's, static files (css, js, etc), and configuration. A plugin has an extension of .a4t when it is built using the Alchemy4Tridion.Plugin NuGet package, and it is this file that can be uploaded to the Alchemy Webstore or installed directly to Tridion via the Alchemy4Tridion extension.

Configuration (a4t.xml)

At minimum, the a4t.xml file is the only real item in the plugin package that your plugin requires. It would be a dull plugin that didn't do anything, but you'd be able to install and list it. This file contains all the necessary info to let the framework know details about it. Depending on the type of plugin you are creating and the features you need, it can also contain extra settings.

Creation

Depending on the type of NuGet package you installed, the a4t.xml file may have been added out of the box to your class library project. If not, then it'll automatically be created when you build your project.

A4T.xml Elements

id

The Webstore's unique identifier for your plugin.

Caution note Caution

This is automatically filled out when you upload your plugin to the WebStore, and should not be modified by you directly.

description

This is the description of your plugin.

Note Note

When uploading to the Webstore, if this is a new plugin or if your plugin on the Webstore does not yet have a description, it will use the value that is specified.

Note Note

This field should use CDATA as descriptions can contains Github flavored markdown.

name *

The (required) unique name of the element. In Alchemy4Tridion, this is your plugin's identifier. This is the only field that is absolutely required for you to fill out when creating a new plugin.

version

The version number of this plugin (ie 1.1.0.0)

Caution note Caution

This is automatically filled out when you upload your plugin to the WebStore, and should not be modified by you directly.

versionId

The Webstore's unique identifier for this version of the plugin.

Caution note Caution

This is automatically filled out when you upload your plugin to the WebStore, and should not be modified by you directly.

settings

The custom configuration settings if your plugin requires them.

Custom Configuration Settings

Alchemy4Tridion allows you to have custom configuration similar to a Tridion GUI Extension's customconfiguration.

Please see this guide for more information.

Static Files

Static files are the StyleSheets, JavaScript, images, user controls (ascx), html pages, and aspx pages that your plugins can utilize.

Adding Static Files

Static files MUST go in your project's "Static" or "Assets" folder (or combination of the two). You can structure your static files any way you want within these files, but you'll have to keep in mind that when you build the project, all the files get organized automatically in specific folders of the plugin package. For example, all JavaScript files will end up in the /assets/js/ folder of the project, all StyleSheets will end up in /assets/css/, and so on, regardless of the folder structure you put them in.

Note Note

This was a design decision to allow creation ease of adding files to your resource groups that allows you to still organize the files the way you want in your project, but allowing filename only references from your extension classes.

You will need to take care that you don't have any static files with the same filename.

The exception to this rule is with JavaScript Libraries.

JavaScript Libraries

Some libraries contain multiple files and a folder structure that must be relative to the main JavaScript file being loaded. Alchemy4Tridion supports this by utilizing the "Libs" folder within your "Static" or "Assets" folder.

Any folder within the "Libs" folder will be considered a Library Folder, and the files within it will keep their structure intact. For example, if you have /Static/Libs/AwesomeLib/(multiple files/folders/structure here), then when built your plugin package will have /assets/libs/AwesomeLib/(multiple files/folders/structure here).

Caution note Caution

Library files should not be added to Resource Groups as Resource Groups will minify and bundle all items into a single resource that Tridion utilizes, and the context of your library and location will be gone. Library files can be referenced in your views with script tags.

<script type="text/javascript" src="${LibsUrl}/AwesomeLib/awesome-lib.min.js"></script>
Tip Tip

This feature can also be used if you also require a specific static file structure for your plugin's own files.

Tokens Within Static Files

Due to the nature of plugins, some details of your plugin may only be known once its installed via the framework. For this reason, Alchemy4Tridion contains special tokens that you can put into your static files that will get parsed during plugin installation.

See the parsed token list for examples and details of which tokens are available to you.

Web Services

Traditional Tridion Extensions made use of WCF web services and a Model to proxy them into your domain so that they could be called via JavaScript. Alchemy4Tridion makes uses of WebAPI Controllers that you can add to your class library so that you can provide back end services that your client code can communicate with, as well as its own proxy so that you can call those services from your JavaScript without having to include any additional library.

See the documentation on the Alchemy WebAPI Controllers for more details.

Plugin Specifics

Depending on the type of plugin you are creating, the rest of your plugin architecture can really vary. Please see the extensions page for more details on development of the type of plugin you are interested in.