Changeset 3170


Ignore:
Timestamp:
Mar 7, 2007, 6:15:18 PM (15 years ago)
Author:
Johan Enell
Message:

jsp section added and some examples removed

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/src/docbook/developerdoc/plugin_developer.xml

    r3169 r3170  
    727727         Request.COMMAND_CONFIGURE_JOB,
    728728         "Select a file to import items from",
    729          "TODO - description",
     729         "Description",
    730730         parameters
    731731      );
     
    749749            </para>
    750750           
    751             <example id="net.sf.basedb.core.plugin.InteractivePlugin.getRequestInformation_2">
    752               <title>
    753                 Reuse a <classname>ParameterType</classname> for many parameters
    754               </title>
    755               <programlisting>
     751            <programlisting>
    756752StringParameterType stringPT = new StringParameterType(255, null, true);
    757753PluginParameter one = new PluginParameter("one", "One", "First string", stringPT);
    758754PluginParameter two = new PluginParameter("two", "Two", "Second string", stringPT);
    759755// ... and so on
    760               </programlisting>
    761             </example>
     756            </programlisting>
    762757            <para>
    763758              The
     
    866861              parameters page.
    867862            </para>
    868             <example id="net.sf.basedb.core.plugin.InteractivePlugin.getRequestInformation_3">
    869               <title>
    870                 Creating sections
    871               </title>
    872               <programlisting>
     863            <programlisting>
    873864PluginParameter firstSection = new PluginParameter(null, "First section", null, null);
    874865PluginParameter secondSection = new PluginParameter(null, "Second section", null, null);
     
    882873parameters.add(firstParameterInSecondSection);
    883874parameters.add(secondParameteInSecondSection);
    884               </programlisting>
    885             </example>
     875            </programlisting>
    886876          </listitem>
    887877        </varlistentry>
     
    10411031  <sect1 id="plugin_developer.organize">
    10421032    <title>How to organize your plugin project</title>
    1043     <para></para>
     1033    <para>
     1034      Here is a simple example of how you might organize your project using ant (
     1035      <ulink url="http://ant.apache.org">http://ant.apache.org</ulink>
     1036      ) as the build tool. This is just a recommendation that we have found to be working
     1037      well. You may choose to do it another way.
     1038    </para>
     1039   
     1040    <sect2 id="plugin_developer.organize.layout">
     1041      <title>Directory layout</title>
     1042      <para>
     1043        <literallayout>
     1044          <filename class="directory"><replaceable>pluginname</replaceable>/</filename>
     1045          <filename class="directory"><replaceable>pluginname</replaceable>/bin/</filename>
     1046          <filename class="directory"><replaceable>pluginname</replaceable>/lib/</filename>
     1047          <filename class="directory"><replaceable>pluginname</replaceable>/src/<replaceable>org/company</replaceable>/</filename>
     1048        </literallayout>
     1049        The
     1050        <filename class="directory">bin/</filename>
     1051        directory is empty to start with. It will contain the compiled code. The
     1052        <filename class="directory">lib/</filename>
     1053        directory contains the JAR files your plugin uses (including the
     1054        <filename>BASE2Core.jar</filename>
     1055        ). The
     1056        <filename class="directory">src/</filename>
     1057        directory contains your source code.
     1058      </para>
     1059    </sect2>
     1060   
     1061    <sect2 id="plugin_developer.organize.build">
     1062      <title>Ant build file</title>
     1063      <para>
     1064        In the root of your directory, create the build file:
     1065        <filename>build.xml</filename>
     1066        . Here is an example that will compile your plugin and put it in a JAR file.
     1067      </para>
     1068      <example id="plugin_developer.organize.build.file">
     1069        <title>A simple build file</title>
     1070        <programlisting>
     1071&lt;?xml version="1.0" encoding="UTF-8"?&gt;
     1072&lt;project
     1073   name="MyPlugin"
     1074   default="build.plugin"
     1075   basedir="."
     1076   &gt;
     1077
     1078   &lt;!-- variables used --&gt;
     1079   &lt;property name="plugin.name" value="MyPlugin" /&gt;
     1080   &lt;property name="src" value="src" /&gt;
     1081   &lt;property name="bin" value="bin" /&gt;
     1082
     1083   &lt;!-- set up classpath for compiling --&gt;
     1084   &lt;path id="classpath"&gt;
     1085      &lt;fileset dir="lib"&gt;
     1086         &lt;include name="**/*.jar"/&gt;
     1087      &lt;/fileset&gt;
     1088   &lt;/path&gt;
     1089
     1090   
     1091   &lt;!-- main target --&gt;
     1092   &lt;target
     1093      name="build.plugin" 
     1094      description="Compiles the plugin and put in jar"
     1095      &gt;
     1096      &lt;javac
     1097         encoding="ISO-8859-1"
     1098         srcdir="${src}"
     1099         destdir="${bin}"
     1100         classpathref="classpath"&gt;
     1101      &lt;/javac&gt;
     1102      &lt;jar
     1103         jarfile="${plugin.name}.jar"
     1104         basedir="bin"
     1105         manifest="MANIFEST.MF"
     1106         &gt;
     1107      &lt;/jar&gt;
     1108
     1109    &lt;/target&gt;
     1110&lt;/project&gt;
     1111        </programlisting>
     1112      </example>
     1113      <para>
     1114        If your plugin depends on other JAR files than the
     1115        <filename>Base2Core.jar</filename>
     1116        you should list them in the
     1117        <filename>MANIFEST.MF</filename>
     1118        file. Otherwise you should remove the manifest attribute of the jar tag in the build
     1119        file.
     1120      </para>
     1121        <programlisting>
     1122Manifest-Version: 1.0
     1123Class-Path: OtherJar.jar ASecondJar.jar
     1124        </programlisting>
     1125    </sect2>
     1126     
     1127    <sect2>
     1128      <title>Building the plugin</title>
     1129      <para>
     1130        Compile the plugin simply by typing
     1131        <command>ant</command>
     1132        in the console window. If all went well the
     1133        <filename>MyPlugin.jar</filename>
     1134        will be created in the same directory.
     1135      </para>
     1136      <para>
     1137        To install the plugin copy the JAR file to the server including the dependent JAR
     1138        files (if any). Place all files together in the same directory. Then follow the
     1139        instructions in chapter
     1140        <link linkend="plugin_installation" endterm="plugin_installation.title"></link>
     1141        .
     1142      </para>
     1143    </sect2>
    10441144  </sect1>
    10451145
    10461146  <sect1 id="plugin_developer.customJSP">
    10471147    <title>Using a custom JSP page for parameter input</title>
    1048     <para></para>
     1148    <para>
     1149      This is an advanced option for plugins that require a different interface for specifying
     1150      plugin parameters than the default list showing each parameter at a time. This feature
     1151      is used by setting the RequestInformation.getJspPage() property when construction the
     1152      request information object. If this property has a non-null value, the web client will
     1153      send the browser to the specified JSP page instead of to the generic parameter input
     1154      page.
     1155    </para>
     1156    <para>
     1157      When setting the JSP page you should not specify any path information. The web client
     1158      has a special location for these JSP pages, generated from the package name of your
     1159      plugin and the returned values. If the plugin is located in the package
     1160      <classname><replaceable>org.company</replaceable></classname>
     1161      the JSP page must be located in
     1162      <filename class="directory">
     1163        <replaceable>www-root</replaceable>
     1164        /plugins/
     1165        <replaceable>org/company</replaceable>
     1166        /
     1167      </filename>
     1168      . Please note that the browser still thinks that it is showing the regular page at the
     1169      usual location:
     1170      <filename class="directory"><replaceable>www-root</replaceable>/common/plugin/index.jsp</filename>
     1171      , so all links in your JSP page should be relative to that directory.
     1172    </para>
     1173    <para>
     1174      Even if you use your own JSP page we recommend that you use the built-in facility for
     1175      passing the parameters back to the plugin. For this to work you must:
     1176    </para>
     1177      <itemizedlist spacing="compact">
     1178        <listitem>
     1179          <simpara>Generate the list of <classname>PluginParameter</classname> objects as usual</simpara>
     1180        </listitem>
     1181        <listitem>
     1182          <simpara>
     1183            Name all your input fields like:
     1184            <parameter>
     1185              parameter:
     1186              <replaceable>name-of-parameter</replaceable>
     1187            </parameter>
     1188          </simpara>
     1189          <programlisting>
     1190// Plugin generate PluginParameter
     1191StringParameterType stringPT = new StringParameterType(255, null, true);
     1192PluginParameter one = new PluginParameter("one", "One", "First string", stringPT);
     1193PluginParameter two = new PluginParameter("two", "Two", "Second string", stringPT);
     1194
     1195// JSP should name fields as:
     1196First string: &lt;input type="text" name="parameter:one"&gt;&lt;br&gt;
     1197Second string: &lt;input type="text" name="parameter:two"&gt;
     1198          </programlisting>
     1199        </listitem>
     1200        <listitem>
     1201        <simpara>
     1202          Send the form to
     1203          <filename>index.jsp</filename>
     1204          with some parameters
     1205        </simpara>
     1206        <programlisting>
     1207&lt;form action="index.jsp" method="post"&gt;
     1208&lt;input type="hidden" name="ID" value="&lt;%=ID%&gt;"&gt;
     1209&lt;input type="hidden" name="cmd" value="SetParameters"&gt;
     1210...
     1211&lt;/form&gt;
     1212          </programlisting>
     1213        <para>
     1214          In your JSP page you will probably need to access some information like the
     1215          <classname>SessionControl</classname>
     1216          and possible even the
     1217          <classname>RequestInformation</classname>
     1218          object created by your plugin.
     1219        </para>
     1220        <programlisting>
     1221// Get session control and it's ID (required to post to index.jsp)
     1222final SessionControl sc = Base.getExistingSessionControl(pageContext, true);
     1223final String ID = sc.getId();
     1224
     1225// Get information about the current request to the plugin
     1226PluginConfigurationRequest pcRequest =
     1227   (PluginConfigurationRequest)sc.getSessionSetting("plugin.configure.request");
     1228PluginDefinition plugin =
     1229   (PluginDefinition)sc.getSessionSetting("plugin.configure.plugin");
     1230PluginConfiguration pluginConfig =
     1231   (PluginConfiguration)sc.getSessionSetting("plugin.configure.config");
     1232PluginDefinition job =
     1233   (PluginDefinition)sc.getSessionSetting("plugin.configure.job");
     1234RequestInformation ri = pcRequest.getRequestInformation();
     1235        </programlisting>
     1236        </listitem>
     1237      </itemizedlist>
    10491238  </sect1>
    10501239
Note: See TracChangeset for help on using the changeset viewer.