In part II of Advanced Plugin Development for the Mura CMS we looked at a basic FW/1 plugin framework that used SubSystems as display objects. In Part III we are going to discuss integrating a datasource and ColdSpring into your plugin. This datasource could be one that is completely separate from your Mura DSN, or it could involve custom tables within the Mura DSN itself. I should note that this tutorial isn't going to include creating your datasource upon plugin installation, as that will be part of a future tutorial (and contains Mura code that I'll have to get permission for sharing). Also, the example code in the ColdSpring beans is currently setup for use in a MySQL database ... if you are working with a different type of database you will have to massage the queries in the ColdSpring CFC's a little bit.
To follow along, you should download and install the APD III plugin (bottom of post) into an updated version of Mura CMS. Next add this table to a datasource that ColdFusion will have access to:
Mura Plugins and a Datasource
Incorporating a datasource into your plugin involves a couple of steps. We're going to be using five arguments for our DSN: type (i.e. MySQL or MS SQL), name, username, password and prefix (the last being important if you are putting your custom tables in an existing DSN, such as your Mura install).
First, if you have added custom tables to the existing Mura install, you will be able to use the DSN settings that were created when Mura was installed. In this case, we can access the DSN settings using the Mura scope:
If you are adding tables to your Mura DSN, I highly recommend you prefix them with something unique, i.e. "pluginX_". This way you won't have to worry about future updates to Mura or other plugins creating table conflicts.
If the datasource is external to your Mura DSN, you will need to let users identify the datasource and its particular attributes. This is easily done in the setup process by including a few settings attributes in the /plugin/config.xml document:
This will add the settings for DSN type (MySQL/MSSQL), name, username, password and prefix. These settings fields will appear whenever a user is installing or updating your plugin. Note that this is only necessary when your datasource is external to your Mura DSN. I would personally recommend having your datasource external, if only to keep your plugin more portable and isolated, but this isn't always possible.
The next step in integrating our database is to make sure our ColdSpring beans have the information needed to access it. To do this in our example plugin, I use the FW/1 setupApplication() function in the Application.cfc (/myuplugin/Application.cfc):
If you are using the Mura DSN, the setup is slightly different:
Note that for the "dsnprefix" you could still use the /plugin/config.xml" settings to identify this value.
Next, our actual ColdSpring file:
There are a couple of Mura-specific items in here. The use of [plugin] (and |plugin|) are needed to integrate the base Mura path into your CFC calls. If you look at the code in the Application.cfc, above, you will see that [plugin] is replaced with the relative CFC-mapped path, and that |plugin| is replaced with a physical path (useful for AOP).
That should be about it! If everything is set up correctly, you should be able to go to the APD Example III plugin in your Mura install and see the following (for reference this page is generated by the FW/1 SubSystem 'admin' using '/admin/controllers/main.cfc' & '/admin/views/main/default.cfm'):
Adding your own datasource and the powerful ColdSpring bean factory ... or any bean factory, for that matter ... will definitely increase the magnitude of what you can accomplish with Mura plugins, as well as making them more flexible and extensible. You might also want to read my PluginConfig and PluginApplication post for using the PluginApplication as your plugin's bean factory.
Hopefully I haven't missed anything in the "Datasource & ColdSpring" overview of Advanced Plugin Development for the Mura CMS, but if I have an exploration of the example plugin should answer your questions.
Download: APD III Example Plugin