?? sparkplug_dev_guide.html.svn-base
字號:
<html>
<head>
<title>Sparkplug Development Guide</title>
<link href="style.css" rel="stylesheet" type="text/css">
</head>
<body>
<div id="bannerbox">
<table cellpadding="0" cellspacing="0" border="0" width="100%">
<tbody>
<tr>
<td width="99%" class="spring" title="Spark"></td>
<td width="1%"><a href="spark" title="Developing Sparkplugs"><img src="images/banner-spark.gif" border="0" alt="Spark" /></a></td>
</tr>
</table>
</div>
<br/>
<h3>What Are Sparkplugs?</h3>
<p>Sparkplugs dynamically extend the features of the <a href="http://www.jivesoftware.org/spark">Spark</a> instant messaging client.
Use Sparkplugs to customize Spark for your business or organization or to add an innovative twist to instant messaging. The
extensive plugin API allows for complete client flexibility but is still simple and (we hope!) fun to use.</p>
<p>This guide provides a high level overview of the Sparkplug API and examples of several common client customizations. Or, jump
directly into the <a href="api/index.html">Javadocs</a>.
</p>
<h3>Once I Build It, Then What?</h3>
<p>After you've built your amazingly cool Sparkplug, it's easy to rollout to your users. Just have them drop it in the plugins directory of
their Spark installation. If your Sparkplug is generally useful, we hope you'll share it with the whole Spark community! To make your Sparkplug
available via the <a href="http://www.jivesoftware.org/spark/sparkplugs">public repository</a> at jivesoftware.org, submit it to
<a href="mailto:plugins@jivesoftware.org">plugins@jivesoftware.org</a>.</p>
<h3>Contents</h3>
This document contains the following information:
<ul>
<li><a href="#clientOverview">Overview of the Spark Client</a>
<li><a href="#overview">Overview of the Sparkplug API</a>
<li><a href="api/index.html">Sparkplug Javadocs</a>
<li><a href="#plugins">Structure Of A Plugin</a></li>
<li><a href="#gettingStarted">Getting started writing your first plugin</a></li>
<li><a href="#examples">Spark Examples and How-To's. Many examples of the most commonly asked questions when developing with Spark.</a>
</ul>
<h3><a id="clientOverview">Overview of the Spark Client</a></h3>
<p>
The Spark client is designed with the idea that most users find the different aspects of a chat client familiar and easy to use.
All components you see below are either accessible from the Workspace or ChatRoom object and can be manipulated based on your
needs.
</p>
<img src="images/contact-list.png" >
<br/>
<img src="images/chat-room.png">
<h3><a id="overview">Overview of the Spark API</a></h3>
The Spark API provides a framework for adding extensions on top of the protocol and/or UI of the Spark client. For example, you could write your own message filter or add a button to a chat room and send files using the File Transfer API. The Spark API has the following characteristics:
<ul>
<li>Several event listeners to either intercept, be informed of, or execute custom code in response to a particular IM event.
<li>Thorough tie-ins to the UI to allow for customization from simple icon changes, to adding buttons, to adding your own menu items.
<li>Ability to add your own XMPP functions using the SMACK API.
<li>Managers - Managers allow for better (lazy) loading of particular areas within the Spark client as well as providing access points to the system. Some of the more relevant managers are:
<ul>
<li> <a href="api/com/jivesoftware/spark/SparkManager.html">SparkManager</a> -- Acts as the central manager for all of Spark. You use this manager to get instances of ChatManager, SessionManager, SoundManager, and UserManager.
<li> <a href="api/com/jivesoftware/spark/ChatManager.html">ChatManager</a> -- Handles registration of most chat listeners and filters, as well as creation and retrieval of chat rooms. It is also used to retrieve the UI of the ChatFrame.
<li> <a href="api/com/jivesoftware/spark/SessionManager.html">SessionManager</a> -- Contains the information about the current session, such as the server connected to, the handling of connection errors and notification of personal presence changes.
<li> <a href="api/com/jivesoftware/spark/SoundManager.html">SoundManager</a> -- Used to play sounds.
</ul>
<li> Event Handlers -- Spark contains numerous listeners and handlers to allow more pluggability into the Spark client. Some of the more common listeners and handlers are:
<ul>
<li> <a href="api/com/jivesoftware/spark/ui/ChatRoomListener.html">ChatRoomListener</a> (and ChatRoomListenerAdapter) -- Allows the plugin to listen for chat rooms being opened, closed and activated. You would generally use this to customize individual chat rooms.
<li> <a href="api/com/jivesoftware/spark/ui/MessageListener.html">MessageListener</a> -- Allows for notification when a message has been received or sent.
<li> <a href="api/com/jivesoftware/spark/ui/ContactGroupListener.html">ContactGroupListener</a> -- Allows for notification of changes to a Contact Group.
<li> <a href="api/com/jivesoftware/spark/ui/ContactListListener.html">ContactListListener</a> -- Allows for notification of changes to the Contact List.
<li> <a href="api/com/jivesoftware/spark/plugin/impl/filetransfer/transfer/TransferListener.html">TransferListener</a> -- Allows you to intercept File transfers.
<li> <a href="api/com/jivesoftware/spark/plugin/ContextMenuListener.html">ContextMenuListener</a> -- Allows for the addition or removal of actions or menu items to right-click (context menu) popups.
<li> <a href="api/com/jivesoftware/spark/ui/PresenceListener.html">PresenceListener</a> -- Allows for notification when Spark presence changes.
<li> <a href="api/com/jivesoftware/spark/ui/ContactItemHandler.html">ContactItemHandler</a> -- Allows the plugin to control the effects of presence changes within a ContactItem and the associated invoke call.
</ul>
<li> Components -- Spark contains many Swing components that will regularly be used during the creation of your plugin. Some of the more commonly used components are :
<ul>
<li> <a href="api/com/jivesoftware/MainWindow.html">MainWindow</a> -- The frame containing the Contact List. You use MainWindow to add new tabs, menu items, or force focus.
<li> <a href="api/com/jivesoftware/spark/ui/ChatRoom.html">ChatRoom</a> -- The base abstract class of all chat rooms within Spark. Known implementations are ChatRoomImpl and GroupChatRoom.
<li> <a href="api/com/jivesoftware/spark/ui/ChatArea.html">ChatArea</a> -- The base chat viewer for both the TranscriptWindow and ChatInputEditor.
<li> <a href="api/com/jivesoftware/spark/ui/ContactList.html">ContactList</a> -- The ContactList UI in Spark.
<li> <a href="api/com/jivesoftware/spark/ui/ChatRoomButton.html">ChatRoomButton</a> -- The button that should be used to conform to the look and feel of other buttons within a ChatRoom.
</ul>
</ul>
<h3><a id="plugins">Structure of a Plugin</a></h3>
<p>Plugins are shipped as compressed JAR (Java Archive) files. The files in a plugin archive are as follows:</p>
<fieldset>
<legend>Plugin Structure</legend>
<pre>myplugin.jar!/
|- plugin.xml <- Plugin definition file
|- libs/ <- Contains all the class archives needed to run this plugin.
</pre>
</fieldset>
<p>
The <tt>plugin.xml</tt> file specifies the main Plugin class. A sample
file might look like the following:
</p>
<fieldset>
<legend>Sample plugin.xml</legend>
<pre class="xml">
<?xml version="1.0" encoding="UTF-8"?>
<span class="comment"><!-- Google Plugin Structure --></span>
<plugin>
<name>Google Desktop Plugin</name>
<class>com.examples.plugins.GooglePlugin</class>
<author>Derek DeMoro</author>
<version>1.0</version>
<description>Enables users to find files and emails relating to users using Google Desktop technology.</description>
<email>ddman@jivesoftware.com</email>
</plugin>
</pre>
</fieldset>
<h3>Installing your Plugin</h3>
<p>
You only need to drop your newly created <tt>jar file</tt> into the plugins directory of your Spark client install.
</p>
<fieldset>
<legend>Directory Structure</legend>
<pre>Spark/
|- plugins/ <- Put your Sparkplug jar file here
|- lib/ <- The main classes and libraries needed to run Live Assistant
|- resources/ <- Contains other supportive documents and libraries
|- docs/ <- Help Manuals and the JavaDoc to help you develop your own plugins.
</pre>
</fieldset>
<p>Your plugin class must implement the
<tt><a href="api/com/jivesoftware/spark/plugin/plugin.html">Plugin</a></tt>
interface from the <a href="api/index.html">Spark Client API</a>. The Plugin interface has
methods for initializing and shutting down the plugin.
</p>
<h2><a id="gettingStarted">Getting Started Writing Sparkplugs</a></h2>
<p>
In order to build your own Sparkplugs, you will need to setup your project properly to have all items in your classpath.
With the Sparkplug.zip or Sparplug.tar.gz you have just extracted, you should see the following contents:
<fieldset>
<legend>Directory Structure</legend>
<pre>Sparkplugs/
|- build/ <- Simple structure to allow you to easily build your plugins using ANT.
|- images/ <- Images used in this guide.
|- plugin_development_guide.html/ <- The complete development guide (this document).
|- api/ <- Contains the Sparkplug Javadocs.
|- spark/ <- The spark build structure you will need for classpath purposes
|-bin <- Contacts the startup.bat which starts up Spark for testing.
|-lib <- Contains all the archives needed to run Spark.
|-logs <- Where all logs are stored.
|-plugins <- Location where all plugins should be deployed to.
|-resources <- Contains native libraries for running OS specific operations.
</pre>
</fieldset>
<p>
To setup a project to run Spark within your IDE, you will need to the following:
</p>
<ul>
<li>It is required that you use the <b>1.4 JRE</b> to build Spark.
<li>Add all *.jar files in the Sparkplugs/spark/lib and Sparkplugs/spark/lib/windows directories to your classpath.
<li>Add the resource directory (Sparkplugins/spark/resource) to your classpath for the native libraries.</li>
<li>Main Class - com.jivesoftware.Spark
<li>VM Parameters - -Dplugin=path_to_your_plugin.xml file. This allows you to run your plugins within your IDE without deploying.
<li>That's it.
</ul>
<p>We have also provided a build structure to easily build and deploy your own plugins directly into your Spark test bed. To use, read the <a href="builder/how-to-build.txt">how-to-build.txt</a> file in the builder/ directory.</p>
<h3><a id="examples">Spark How-To's</a></h3>
<p>
All code samples can be found in the <a href="examples.jar">examples.jar</a> file located here.
</p>
<ul>
<li><a href="#simplePlugin">How do I create a simple plugin?</a>
<li><a href="#addTab">How do I add my own Tab to the Spark Workspace?</a>
<li><a href="#addContactListContextListener">How do I add a context menu listener to the contact list?</a>
<li><a href="#addChatRoomContextListener">How do I add my own ContextMenu Listener to a ChatRoom?</a>
<li><a href="#addMenu">How do I add my own Menu to Spark?</a>
<li><a href="#addButton">How do I add a button to a Chat Room?</a>
<li><a href="#addSearch">How do I add my own searching feature in Spark like the User Search or Google Search in Firefox?</a>
<li><a href="#interceptFile">How can I intercept a File Transfer request?</a>
<li><a href="#sendFile">How can I send a file to another user?</a>
<li><a href="#contactUI">How can I control the UI and event handling of a ContactItem?</a>
<li><a href="#changePresence">How can I be notified when the Spark user changes their presence?</a>
<li><a href="#messageFilter">How can I add a message filter?</a>
<li><a href="#createChatRoom">How can I create a person-to-person Chat Room?</a>
<li><a href="#createConferenceRoom">How can I create a public Conference room?</a>
<li><a href="#addPreferences">How can I add my own Preferences?</a>
<li><a href="#showAlert">How can I flash the chat frame, like when a new message comes in?</a>
</ul>
<h3 id="simplePlugin">How do I create a simple plugin?</h3>
<ol>
<li>Implement Plugin.
</ol>
<fieldset>
<legend>Simple Plugin</legend>
<pre class="java">
package com.jivesoftware.spark.examples;
import com.jivesoftware.spark.plugin.Plugin;
/**
* Implements the Spark Plugin framework to display the different possibilities using
* Spark.
*/
public class ExamplePlugin implements Plugin {
/**
* Called after Spark is loaded to initialize the new plugin.
*/
public void initialize() {
System.out.println("Welcome To Spark");
}
/**
* Called when Spark is shutting down to allow for persistence of information
* or releasing of resources.
*/
public void shutdown() {
}
/**
* Return true if the Spark can shutdown on users request.
* @return true if Spark can shutdown on users request.
*/
public boolean canShutDown() {
return true;
}
/**
* Is called when a user explicitly asked to uninstall this plugin.
* The plugin owner is responsible to clean up any resources and
* remove any components install in Spark.
*/
public void uninstall(){
// Remove all resources belonging to this plugin.
}
}
</pre>
</fieldset>
<h3 id="addTab">How to add your own Tab to the Spark Workspace?</h3>
<ol>
<li>Implement Plugin.
<li>Retrieve the Workspace which is the UI for Spark.
<li>Retrieve the WorkspacePane which is the Tabbed Pane used by Spark.
<li>Add your own tab.
</ol>
<fieldset>
<legend>Add a Tab to Spark</legend>
<pre class="java">
public class ExamplePlugin implements Plugin {
.
.
.
/**
* Adds a tab to Spark
*/
private void addTabToSpark(){
// Get Workspace UI from SparkManager
Workspace workspace = SparkManager.getWorkspace();
// Retrieve the Tabbed Pane from the WorkspaceUI.
JTabbedPane tabbedPane = workspace.getWorkspacePane();
// Add own Tab.
tabbedPane.addTab("My Plugin", new JButton("Hello"));
}
.
.
.
}
</pre>
</fieldset>
<h3 id="addContactListContextListener">How do I add a context menu listener to the contact list?</h3>
<ol>
<li>Implement Plugin.
<li>Retrieve the ContactList which is part of Spark's Workspace.
<li>Add ContactListListener.
</ol>
<fieldset>
<legend>Add a ContextMenu Listener to ContactList</legend>
<pre class="java">
private void addContactListListener(){
// Get Workspace UI from SparkManager
Workspace workspace = SparkManager.getWorkspace();
// Retrieve the ContactList from the Workspace
ContactList contactList = workspace.getContactList();
// Create an action to add to the Context Menu
final Action sayHelloAction = new AbstractAction() {
public void actionPerformed(ActionEvent actionEvent) {
JOptionPane.showMessageDialog(SparkManager.getMainWindow(), "Welcome to Spark");
}
};
sayHelloAction.putValue(Action.NAME, "Say Hello To Me");
// Add own Tab.
contactList.addContextMenuListener(new ContextMenuListener() {
public void poppingUp(Object object, JPopupMenu popup) {
?? 快捷鍵說明
復(fù)制代碼
Ctrl + C
搜索代碼
Ctrl + F
全屏模式
F11
切換主題
Ctrl + Shift + D
顯示快捷鍵
?
增大字號
Ctrl + =
減小字號
Ctrl + -