Brass SSE Developer Guide - Distributing Your
Plugin
You've coded your plugin, you've compiled and tested
it and now you're ready to share it with the world!
Question is, how do you do that?
So what do I do?
SSEdit and Brass make distributing plugins extremely
easy with the Pack Creator system. As well as the SSE plugin itself,
most plugins will need some extra resources - data files, images
etc. The Pack Creator makes it nice and easy to distribute your
plugin plus all its resources in a single, easy to manage file.
This page will take you through how to pack up
your plugin, step by step. We're going to use the Gallery plugin
(the source for the plugin is included with the SSEdit samples).
The first step is to fill out your plugin's information
by clicking the info icon ( 
) on the toolbar (or choosing "Set Plugin Info" from the
Build menu). If you used the New Plugin Wizard this information
will probably be filled out for you.
The information you enter here is compiled into your
plugin and displayed by Brass when you view your plugin properties.
Remember to keep the version number up to date!
Now that the plugin information is set we can compile
it to an executable SSE by clicking the Compile icon ( 
).
The compiler must report zero errors - you can't distribute a plugin
that doesn't compile, of course!
Now that we have a compiled plugin we can pack it and its resources
into an SSP - a ShinySource Pack. To open the Pack Creator, select
"Pack for Distribution" from the File menu or click the
Pack icon on the toolbar ( 
).
The Pack Creator window is split in half. In the top half the SSE
name and destination folder are shown. This is the standard Brass
SSE folder that all SSEs must be installed to. You'll notice that
the resources folder is set to the same name as your SSE. This is
deliberate - it's to ensure one SSE doesn't overwrite another SSE
with its data.
If you created a layout with the Panel Designer, this will also
be shown. You can't change the filename of the default layout as
it's actually stored internally in SSEdit and Brass. Lots of information
on the Panel Designer (including how to change or remove a layout)
is available on the Panel Designer
page.
Finally an optional info file is also displayed. Info files are
a quick way to pop up some formatted text when anyone installs your
plugin. They are discussed in detail below.
Resources and GETSELFNAME
Now is a good time to talk about GETSELFNAME.
GETSELFNAME is a Shiny statement that returns the current filename
of the SSE. Why is this useful?
It's pretty likely that at some point someone will want to run
the same plugin twice. This isn't as crazy as it sounds! Think about
an RSS reader plugin that pulls the news from one RSS URL. If you
wanted to see the news from a couple of different RSS feeds, but
you wanted them in separate display panels you could just make a
copy of the plugin and change the URL used for the RSS feed. But
here's a potential problem - if the RSS reader needs to use some
resources (for example, write a temporary file) and 2 copies of
the plugin are running at the same time, a collision could occur
if both copies of the plugin try to write to the same file at the
same time.
GETSELFNAME solves this problem. If you know the name of the plugin
at the time it's running you also know the name of the resource
folder for the plugin. And because GETSELFNAME returns the filename
of the plugin (which must be unique, of course) you can be absolutely
sure that no other plugin is going to use anything in the resource
folder. Brass makes sure this resource folder always exists before
a plugin is loaded.
So when writing code like this:
// Open a temp file for saving data
fopen(MyFile, "SSE\\MyPlugin\\temp.txt");
you should write code like this instead:
// Open a temp file for saving data
string ResFolder = "SSE\\" + strleft(getselfname(),
strlen(getselfname()) - 3);
fopen(MyFile, ResFolder + "\\temp.txt");
This is a handy code snippet to extract a path and folder name
from the plugin name using getselfname and stripping the .SSE extension.
You can copy it from this web page, or insert it using the Code
Wizard:
string SSEFolder = "SSE\\" + strleft(getselfname(),
strrfind(getselfname(), "."));
Back to the Pack
To create the finished pack, all we need to do is add the resources
the plugin needs. Click the "Add" button and select the
files you want to distribute with your plugin (you can select multiple
files at a time). All the files you select will be installed to
the plugin's resource folder, as shown in the top half of the window.
If you try to add 2 files with the same filename you'll get this
message:
All the resources for a plugin will be installed to the same folder,
so if you try to add 2 resources with the same filename the Pack
Creator will warn you about the clash. Brass uses one resource folder
per SSE to keep things neat and tidy.
An Example
Just in case it isn't clear, assume your plugin is called MyPlugin.sse
and loads a JPG called "mypic.jpg". Currently mypic.jpg
is stored in C:\mydata, and your plugin code looks like this:
image myimg;
createimage(MyImage,
"C:\\MyData\\mypic.jpg");
First you should open the Pack Creator and add mypic.jpg to the
resource list. Next you should modify your code to look like this:
string SSEFolder = "SSE\\" + strleft(getselfname(),
strrfind(getselfname(), "."));
image myimg;
createimage(MyImage,
SSEFolder + "\\mypic.jpg");
Because you added mypic.jpg to the resource list it will automatically
be packed to the SSP and then installed along with your plugin,
to the Brass\SSE\MyPlugin. The code snippet above gets the resource
folder and loads the jpg. Doing it this way guarantees your plugin
will always work, no matter what file or foldername is used.
Using the "Deploy to Brass" option in the SSEdit File
menu simulates this install and makes sure all your resources are
copied to the right resource folder. You can read more about it
here.
Resources for skinned controls
If you've used the Panel Designer to create a default layout for
your plugin, SSEdit will automatically add any images you use for
skinning to your resource list. The process is completely automatic
- once you've created your layout with the Panel Designer, SSEdit
does everything else for you to ensure your plugin pack will contain
all the resources and correct configuration. The following links
explain all about how to use the Panel
Designer, how to skin controls
and how the Panel Designer and Pack
Creator work together.
Adding extra information
In the top half of the Pack Creator window (in the "Locations"
frame) you can see an edit field requesting an optional file to
display. If you provide a file here the Pack Creator will include
it in a special format. When the pack is installed into Brass the
information in this file will be displayed. You don't have to specify
this file, but it's a handy way to display some last-minute information
when your plugin is installed.
This SSP information file must be a plain text file. Brass understands
a couple of HTML-like tags to enhance the display and formatting,
but you cannot use a full HTML file here. Only the following tags
are allowed:
<a href="http://www.somesite.com">Link here</a>
<b>Bold text</b>
<i>Italic text</i>
<hr>
<font color="#000000" size="10" name="Arial">This
is Arial 10pt black</font>
Unlike proper HTML, you must use blank spaces and CR/LF to format
your text instead of " " and "<br>".
Creating the Pack
We've set our plugin information fields, compiled the SSE and selected
our resources. All we need to do now is to create the pack itself
by clicking "Create Pack". You'll be prompted for a filename
for the pack, then once your pack has been created you'll see this
message:
That's it! The SSP contains your plugin and all the resources you
specified.
Installing SSP's in Brass
Of course, SSP's are only useful if you can get the plugin installed
and working in Brass so let's see how to do that. Open the main
Brass window and select "Install New SSP":
Brass will prompt you for the SSP to install, and that's it! The
plugin will be automatically unpacked to the <Brass Install Folder>\SSE
folder, the plugins list will be refreshed and you can begin using
the plugin immediately. If you included an information file in the
SSP, it will be displayed as the pack is installed.
|
