(The first out of the factory: Implementing IPluginAdminMenu. 52 more to go!)
Code up an Example Plugin
0. Create a new Visual Studio 2005 "class library" project called <INTERFACE NAME>_Example. A containing folder of the same name will automatically be created.
1. Rename the class file <INTERFACE_NAME>_Example.cs, and copy in the contents of skeleton_class.cs that we'll use for all examples. It will have comments that apply to all plugins and a clean format.
2. To the top of AssemblyInfo.cs, add:
using FogCreek.Plugins;
to the bottom add:
[assembly: AssemblyFogCreekPluginId("<INTERFACE NAME>_Example@fogcreek.com")]
3. Add assembly references to:
FogBugz (C:\code\fogbugz-devel\Website\bin\FogBugz.dll)
FogCreek.Plugins (C:\code\fogbugz-devel\Website\bin\FogCreek.Plugins.dll)
System.Web (In the .NET list)Once you do this once, VS will list these in the "Recent" tab of the "Add Reference" window.
4. Right-click on the interface name in the class definition, and click "Implement Interface"
5. Build the project to make sure we're OK so far.
To secret tip: for faster debugging, use these bat files as a post-build event. It will zip the dll and put it in your plugins/upload directory. Now you just hit fogbugz and the plugin installs magically! (only tested when my plugin solution folders live in fogbugz\Plugins\examples and you have to manually add the static folder to the zip archive if you have one)
- Put these two bat files in the directory your plugin solutions are in: _postbuildSln.bat.unsafe _zipPlugin.bat.unsafe
- Right click your solution name in VS and select properties, then click the "Build Events" tab and paste this into the Post-build box: "$(SolutionDir)..\_postbuildSln.bat $(TargetName)"
6. Code up an example that uses as few other interfaces as possible, includes as few libraries as possible, and is as simple as possible while still demonstrating or implying the intended actual use of the interface in some way. (Maybe try to integrate kiwis and the "Hello, Kiwi!" tag line to keep it light?) Do not exceed 90 characters in width. Note: code should use the "code" style and make use of shift-enter for newlines to prevent double-spacing (pasting from VS should default to these newlines)
Make sure that HTML is always formatted with @"", uses String.Format as necessary, and is indented as much as possible, like so:
return String.Format(
@"<form action=""default.asp?pg=pgPlugin&ixPlugin=18""
method=""POST"">
<input type=""hidden"" name=""{0}sAction"" value=""addTodo"" />
<input type=""text"" name=""{0}sAction"" value=""addTodo"" />
<input type=""text"" name=""{0}sDescription"" />
<input type=""submit"" value=""Add""/>
</form>",
api.PluginPrefix()
);
7. As you code, add comments for things that are surprising, noteworthy, or use other important elements of FogBugz plugins APIs/Interfaces.
8. If you found any important stuff in part 7, create a bug in FogBugz, paste in the code from the .cs file, and assign the bug to Dan Wilson. He will later make sure that the information in the comments is integrated into the plugin specification documentation.
9. Install the plugin on your local build, and use the fogbugz screenshot tool to take one or more png screenshots.Make sure that:
- Your local build looks like production fogbugz, with the normal non-debug kiwi on the upper left
- No site errors are reported at the top of the screen (you may have to hit heartbeat.asp to get the "maintenance" message to go away)
- You have some sample data on your screen that's suitable for public display
- To make things easy on yourself, always view your fogbugz in an 800x600 window. make a bookmarklet in firefox to resize, just use this text for the location: "window.resizeTo(800,600)"
- Use ctl-minus and ctl-plus to resize text if things are too wide, but don't scale down the screenshot
10. Use an image editor to trim the screenshot(s). Make sure it's no more than 800px wide, and does not show any of the browser, only HTML. Put your screenshots in the solution folder just in case
11. Put a copy of the whole solution folder into \\winston\interface_examples\
Write a wiki article
12. Start a wiki article linked to from the temporary developers wiki start page:
13. Paste in the skeleton article:
14. Fill in the "Introduction, functionality, and C# code" portions of the article with content. For your screenshots, make sure to set the image style to "outset"
15. Create a link to the C# file by:
- highlighting the text "<INTERFACE NAME>_Example.cs"
- attaching the <INTERFACE NAME>_Example.cs.cs file to it
- deleting the paper clip icon on the right.
16. Save and View! Does it follow this format? https://developers.fogbugz.com/default.asp?W4
17. Take a shot!