Click or drag to resize
AlchemyStep By Step From Alchemy4Tridion.Plugin Package

Developing a plugin from the ground up is as simple as installing the necessary NuGet package and ensuring you have some core classes. If this sounds a little intimidating at first and you'd rather see an entire project example to use as a guideline, check out this guide.

Create an Alchemy4Tridion Plugin From Scratch

  1. Create a new Class Library project in Visual Studio.

  2. In the Package Manager console type the following:

    Install-Package Alchemy4Tridion.Plugin - Pre
    Note Note

    Only once Alchemy4Tridion has come out of public beta testing will version 1.0 be available without the "-Pre" flag.

    Alternatively, you can also right click your class library project use the "Manage Nuget Packages" option to search and install the Alchemy4Tridion.Plugin package (make sure the prerelease filter option is selected).

  3. Rename the installed ServiceController to your liking. In the 2nd argument of the AlchemyRoutePrefixAttribute on the controller, feel free to rename "Service" as well. Note that this is the name that you'll use in your JavaScript to call your service. If you do not require a web service for your plugin delete ServiceController.

    Important note Important

    As of the 0.6 release, the ServiceController class is no longer included in the NuGet package.

  4. Feel free to rename the AlchemyPlugin.cs at the root of your project. If you are going to be using encrypted custom configuration settings, you can also set your encryption key here.

    public class MySuperAwesomePlugin : AlchemyPluginBase
    {
        public override void Configure(IPluginServiceLocator services)
        {
            services.SettingsEncryptor.EncryptionKey = "MySecretEncryptionKey";
        }
    }

    This is your plugin class, and is the entry for the framework to discover your plugin. The only requirement for this class is that it extends AlchemyPluginBase.

    Caution note Caution

    As of 0.6, the AlchemyPlugin.cs class is no longer included in the NuGet package. If not using the Alchemy4Tridion Developer Pack, you'll have to create this class manually. If you attempt to build the project without creating this class, the build will fail and you will see an appropriate error message.

    If you are using the Plugin Project templates from the developer pack, this class is automatically included.

  5. Add any static files that your plugin needs (JavaScript, CSS, images, .ascx controls, .aspx views, etc) under a /Static/ or /Assets/ folder in your project. Note that you can organize your static files any way you want within the static folder, but at build time the plugin package will put them in specific folders (e.g. all JavaScript files will end up in /assets/js/ of the plugin package).

  6. Add any Config classes that represent configuration elements of the traditional Editor.config file. (covered by another topic in this documentation).

  7. Build your project in Visual Studio.

  8. If you want to upload your project to the Webstore, complete the dialog that pops up after supplying your Webstore credentials.

  9. If you want to test your plugin directly without uploading to the Webstore, find the .a4t file in the /bin/Debug/ folder of your project (assuming you built under the Debug target). You can drag and drop this to the "Plugins" tab of the Alchemy UI.

    Caution note Caution

    Since this plugin has not been uploaded to the Webstore it is considered a development plugin. Be mindful of any other plugins that may already be installed; if your plugin doesn't have a unique name it will get an error saying it is already installed.

  10. Plugins require a page reload to show up in the Tridion GUI. After installing (or uninstalling) a plugin, a reload icon will appear in the top bar of the Alchemy UI, near where your username is displayed. You can either click this or use your browser's refresh button.

  11. Your plugin is now installed and any changes to the GUI should now be visible in the CME.

    Note Note

    Tridion GUI cache can be a tricky at timess. The Alchemy4Tridion framework will automatically recycle application pools as well as increment the System.config's modification attribute, however it has been noted that sometimes the cache just won't clear for particular files, and you may have to clear your browser's cache manually.

    If you don't see the desired results, you may have just experienced this issue.

Next Steps

Now that you know how to build a plugin, continue reading this documentation to further master new areas of plugin development.