You can extend the capabilities of Source by adding new component models or data processing tools. Some of these "plugin" tools extend Source’s user interface. Other plugins, especially those written by third parties, may look and operate differently from the normal user interface. Refer to Assign catchment models when working with catchment model plugins.
Plugins are files which have a .DLL or .EXE extension, and work with specific versions of Source. Plugins that are external to Source, and must be downloaded from the Internet, must be handled differently. Refer to Externally created plugins for more information..
There are several plugins included with Source that have been verified by the Source development team. This documentation is only developed and maintained for these included plugins. Table 1 provides plugin file and location details of plugins that are discussed in more detail.
Table 1. Plugins
|Plugin||Plugin file||Location in Source|
C:\Program Files\eWater\<Source version>\Plugins\RiverSystem.Plugins.PerfectGWLag.dll
|Tools » Plugins<various related folders>|
|River Analysis Package|
C:\Program Files\eWater\<Source version>\Plugins\RiverSystem.Plugins.RAP.dll
|Spatial data pre-processor|
C:\Program Files\eWater\<Source version>\Plugins\RiverSystem.Plugins.SpatialDataPreProcessor.dll
|Tools » PluginsRiverSystem.Plugins.SpatialDataPreProcessor|
C:\Program Files\eWater\<Source version>\Plugins\CommunityPlugins\SourcePlugin.SubSource.dll
Working with the Plugin Manager
The Plugin Manager allows you to install, load and manage all plugins in Source. Available via, this dialog (shown in Figure 1) shows all plugins that have been installed either:
- Manually; or
- Via the online store hosted by eWater.
The Details panel in the Plugin Manager provides the following information for the selected plugin:
- Version - a four-digit number used to uniquely identify which version of Source the plugin was compiled against; and
- Tags - the version of Source that the plugin can be opened in.
Manually installing plugins
Source community plugins are installed as part of Source are located in the following folder:
C:\Program Files\eWater\<Source version>\Plugins
<Source version> refers to the version of Source currently in use.
To install a plugin manually:
- Click Browse... to open an Explorer dialog;
- Select the plugin; and
- Click OK.
Figure 1. Plugin manager
Installing via the online store
- Choose Online to view a complete list of plugins available from the store; and
- Click Install.
Specifying plugins when running RiverSystem.Forms.exe
It is possible to overwrite the standard plugin loading functionality when starting RiverSystem.Forms.exe. In order to do this you call RiverSystem.Forms.exe from the command line (note: this is NOT the command line runner) and use the following switches to specify plugins
|/p||/p project_name||/p C:\SourceProjects\MyProject\myProject.rsproj||does not need to be an absolute path|
|/nopluginfile||/nopluginfile||/nopluginfile||disables loading and saving of plugin configs|
|/plugin||/plugin plugin_path||/plugin C:\SourceProjects\MyProject\FirstPlugin.dll||must use an absolute path, or will only use the name and do a normal lookup|
The easiest ways to do this is to specify a shortcut, or use a batch file. For example a batch file might have
use C:\SourceVersions\5.0.3\RiverSystem.Forms.exe to load only the following plugins
- C:\SourceProjects\MyProject\FirstPlugin.dll - this is a custom plugin
- C:\SourceProjects\MyProject\SourcePlugin.AllocationAndUtilities.dll - as this is an absolute path it will use the specified version of the file at C:\SourceProjects\MyProject\SourcePlugin.AllocationAndUtilities.dll rather than C:\SourceVersions\5.0.3\CommunityPlugins\SourcePlugin.AllocationAndUtilities.dll
- FarmDamPlugin.dll - this will do a normal lookup in CommunityPlugins and use C:\SourceVersions\5.0.3\CommunityPlugins\FarmDamPlugin.dll
then load the project C:\SourceProjects\MyProject\myProject.rsproj
Note that if a plugin cannot be found, or a non absolute path is used, source will preferentially use the name specified as a lookup in CommunityPlugins. This is to maintain backwards compatibility with existing functionality.
Note also that this will not have an effect on the plugins used in RiverSystem,CommandLine.exe
Uninstalling plugins from a source project
To uninstall plugins from a source project when they have been added accidentally, normally just load this project file to a source version which does not install the plugins ( not included in plugin manager ) and then save the project. By doing this, source will try to remove the plugins. But for certain plugins, the following steps are needed to be able to uninstall it from a source project:
- Go to Tools>>Remove Plugin from project file.
- Add the project and then select the plugin from the lower window under "Select plugins to be removed from the project file', see figure 3.
- Click "Save" to save the project.
- If you haven't already removed the plugin from source plugin manager, go to Tools >> Plugin Manager >> uninstall "the plugin", click OK and restart Source when prompted. Now you should be able to load the project file to source without the plugin loaded.
This is not required for all plugins, but only for those where generic settings are stored in the project and remain in the project even if not the usage has been removed e.g. a node plugin needs a tool to remove it because generic settings about the nodes are stored even when they are not used in a project. However, e.g. for rainfall-runoff plugins, it is only necessary to remove the usage of it, there is no generic information stored about the rainfall-runoff models. Once the rainfall-runoff model no longer has a usage the model can be loaded without the plugin loaded.
If no plugins appear in Figure 3, then there are no plugins which store generic settings.
This is currently only required for plugins:
- NetLP Monthly Optimiser
Figure 3. Remove Plugin Tool
There are two possible scenarios that warrant an upgrade:
- The version of Source has been upgraded - in this case, Source will attempt to install the same plugin version that was installed in the previous version of Source; or
- The plugin version is different - if the plugin was originally installed from the online store, clicking Update will remove the old version and install the new one. Note that this happens only once when Source is opened for the first time with the new plugin version.
Writing your own plugins
Externally created plugins
For plugins that have been developed externally to Source (such as DERMTools), you must manually unblock them in Windows after downloading. By default, Windows blocks the execution of programs downloaded from the internet (including the .dlls used as Source plugins) in order to reduce the risk of the computer being infected by a virus or some other form of malicious software.
Once downloaded, open as follows:
- Open Explorer. Right click on the dll file and choose Properties; and
- In the resulting dialog (shown in Figure 4), click Unblock at the bottom of the screen, then OK.
The plugin can then be loaded as normal in Source.