Changeset 6812 for trunk/doc/src/docbook/developer/extensions.xml

Timestamp:

Mar 30, 2015, 10:46:31 AM (9 years ago)

Author:

Nicklas Nordborg

Message:

References #1813: Remove deprecated event handler methods from extensions

Trying to remove code examples that use inline javascript event handlers.

File:

• trunk/doc/src/docbook/developer/extensions.xml (modified) (13 diffs)

trunk/doc/src/docbook/developer/extensions.xml

@@ -233 +233 @@
       of an extension. This extension will add a new menu item in the
       menu which displays a popup with the text "Hello world!" when 
-      selected. Copy the XML code below and save it to a file in
-      the <filename>plugins.dir</filename>
-      directory. The filename must end with <filename>.xml</filename>. 
-      Install the extension by going through the installation wizard
-      at <menuchoice>
-          <guimenu>Administrate</guimenu>
-          <guimenuitem>Plug-ins &amp; extensions</guimenuitem>
-          <guimenuitem>Overview</guimenuitem>
-        </menuchoice>.
-    </para>
-    
-    <para>
-      When the extension has been installed you should have a new 
-      menu item:
-      <menuchoice>
-        <guimenu>Extensions</guimenu>
-        <guimenuitem>Hello world!</guimenuitem>
-      </menuchoice>
-      which pops up a message in a Javascript window.
-    </para>
-    
-    <note>
-      <para>
-      You may have to logout and login again to see the new menu item.
-      </para>
-    </note>
-    
-    <programlisting language="xml">
+      selected. 
+    </para>
+    
+    <orderedlist>
+      <listitem>
+      <para>
+      Start by creating an empty directory in some suitable
+      location on your hard disk. Inside this directory, create two more
+      directories <filename>META-INF</filename> and 
+      <filename>resources</filename>. 
+      </para>
+      </listitem>
+      
+      <listitem>
+      <para>
+      Copy the XML code below and save it to <filename>META-INF/extensions.xml</filename>
+      in your newly created directory. It is important that you get the filename
+      correct.
+      </para>
+      
+      <programlisting language="xml">
 <![CDATA[
 <?xml version="1.0" encoding="UTF-8" ?>
@@ -269 +262 @@
       >
       <index>1</index>
-      <about>
+      <about safe-scripts="1">
          <name>Hello world</name>
          <description>
@@ -282 +275 @@
          </factory-class>
          <parameters>
+          <id>hello-world</id>
             <title>Hello world!</title>
             <tooltip>This is to test the extensions system</tooltip>
-            <onClick>alert('Hello world!')</onClick>
             <icon>/images/info.png</icon>
+            <script>~/hello.js</script>
          </parameters>
       </action-factory>
@@ -292 +286 @@
 ]]>
 </programlisting>
+      <para>
+        This file is the most important one when creating extensions
+        since it is used to tell BASE about the extensions (and
+        plug-ins) in the package. See below for more information.
+      </para>
+      </listitem>
+      
+      <listitem>
+      <para>
+      Copy the javascript code below and save it to <filename>resources/hello.js</filename>
+      in your newly created directory. Once again, it is important that the filename
+      is correct.
+      </para>
+      <programlisting language="javascript">
+<![CDATA[
+var HelloWorld = function()  
+{  
+   var hello = {};  
+    
+    /** 
+       Executed once when the page is loaded. Typically 
+       used to bind events to fixed control elements. 
+    */  
+    hello.initMenuItems = function()  
+    {  
+       // Bind event handlers the menu items.   
+       // First parameter is the ID of the menu item  
+       // Second parameter is the event to react to (=click)  
+       // Last parameter is the function to execute  
+       Events.addEventHandler('hello-world', 'click', hello.helloWorld);  
+    }  
+      
+    // Show 'Hello world' message
+    hello.helloWorld = function(event)  
+    {  
+       alert('Hello world');
+    }  
+     
+    return hello;  
+}();  
+      
+//Register the page initializer method with the BASE core  
+Doc.onLoad(HelloWorld.initMenuItems);  
+]]>
+</programlisting>
+      </listitem>
+    
+      <listitem>
+      <para>
+      Create a JAR package containing the two directories and files
+      you have created. It is important the the subdirectory structure
+      inside the JAR file is rooted at the first empty directory you created.
+      </para>
+      
+        <literallayout>
+<filename class="directory">META-INF/</filename>
+<filename>META-INF/extensions.xml</filename>
+<filename class="directory">resources/</filename>
+<filename>resources/hello.js</filename>
+        </literallayout>
+      
+      <para>
+        Copy the JAR file to the the <filename>plugins.dir</filename>
+        directory for your BASE installation.
+      </para>
+      </listitem>
+    
+      <listitem>
+      <para>
+        Log in to BASE and install the extension by going through the 
+        installation wizard at <menuchoice>
+            <guimenu>Administrate</guimenu>
+            <guimenuitem>Plug-ins &amp; extensions</guimenuitem>
+            <guimenuitem>Overview</guimenuitem>
+          </menuchoice>.
+        When the extension has been installed you should have a new 
+        menu item:
+        <menuchoice>
+          <guimenu>Extensions</guimenu>
+          <guimenuitem>Hello world!</guimenuitem>
+        </menuchoice>
+        which pops up a message in a Javascript window.
+        
+      </para>
+      <note>
+        <para>
+        You may have to logout and login again to see the new menu item.
+        </para>
+      </note>
+      </listitem>
+    
+    </orderedlist>
+    
+    <sect2 id="extensions_developer.extensions.xml">
+      <title>The extensions.xml file</title>
     
     <para>
@@ -388 +477 @@
       <title>Content security policy and inline javascript</title>
       <para>
-        In the above example <sgmltag class="starttag">onClick</sgmltag> is 
-        a parameter that contains a javascript statement. In general, we recommend
-        that inline javascript is avoided due to security vulernabilities.
-        If you install the above extension, your BASE server probably display
-        a warning message about violating the <emphasis>Content security policy</emphasis>.
-        If so, you need to change the configuration to be less restricted. See
+        The Hello World example requires quite a lot of code and it
+        would have been tempting to skip the <filename>hello.js</filename>
+        file and simply add 
+        
+        <code><sgmltag class="starttag">onclick</sgmltag>alert('Hello world')<sgmltag class="endtag">onclick</sgmltag></code>
+        
+        to the <sgmltag class="starttag">parameters</sgmltag> section in the
+        <filename>extensions.xml</filename> file. However, BASE is by default
+        configured to block all inline JavaScript since it opens up for
+        cross-site scripting attacks. It is possible to relax this policy
+        but it is nothing we recommend. See
         <xref linkend="appendix.web.xml.csp-filter" /> for more information.
       </para>
@@ -404 +498 @@
       </para>
     </note>
+    
+    </sect2>
     
     <sect2 id="extensions_developer.extend_multiple">
@@ -486 +582 @@
       InvokationContext<? super MenuItemAction> context) 
    {
+      JspContext jspContext = (JspContext)context.getClientContext();
+      String home = jspContext.getHome(context.getExtension());
+      jspContext.addScript(home + "/hello.js");
       return true;
    }
@@ -498 +597 @@
       {
          MenuItemBean bean = new MenuItemBean();
+         bean.setId("hello-factory");
          bean.setTitle("Hello factory world!");
          bean.setIcon(jspContext.getRoot() + "/images/info.gif");
-         // NOTE! onclick is deprected! A real implementation 
-         // should bind events using to the menu using javascript
-         bean.setOnClick("alert('Hello factory world!')");
          helloWorld[0] = bean;
       }
@@ -512 +609 @@
 
     <para>
-      And here is the XML configuration file that goes with it.
+      And here are the XML and JavaScript files that goes with it.
     </para>
 
@@ -540 +637 @@
 ]]>
 </programlisting>
+    <programlisting language="javascript">
+<![CDATA[
+var HelloWorldFactory = function()  
+{  
+   var hello = {};  
+    
+    /** 
+       Executed once when the page is loaded. Typically 
+       used to bind events to fixed control elements. 
+    */  
+    hello.initMenuItems = function()  
+    {  
+       // Bind event handlers the menu items.   
+       // First parameter is the ID of the menu item  
+       // Second parameter is the event to react to (=click)  
+       // Last parameter is the function to execute  
+       Events.addEventHandler('hello-factory', 'click', hello.helloFactoryWorld);  
+    }  
+      
+    // Show 'Hello factory world' message
+    hello.helloFactoryWorld = function(event)  
+    {  
+       alert('Hello factory world');
+    }  
+     
+    return hello;  
+}();  
+      
+//Register the page initializer method with the BASE core  
+Doc.onLoad(HelloWorldFactory.initMenuItems);  
+]]>
+</programlisting>
     
     <para>
       To install this extension you need to put the compiled 
-      <filename>HelloWorldFactory.class</filename> and the XML
-      file inside a JAR file. The XML file must be located at
-      <filename>META-INF/extensions.xml</filename> and the class
+      <filename>HelloWorldFactory.class</filename>, the XML 
+      and JavaScript files inside a JAR file. The XML file must be located at
+      <filename>META-INF/extensions.xml</filename> the JavScript file
+      at <filename>resources/hello.js</filename>, and the class
       file at <filename>net/sf/basedb/examples/extensions/HelloWorldFactory.class</filename>.
     </para>
@@ -701 +831 @@
     
     <para>
-      The third new part is that the call to <methodname>MenuItemBean.setOnClick()</methodname>
-      has been removed. To replace the inline scripting functionality we need
-      the <methodname>MenuItemBean.setId()</methodname> call, the
-      <methodname>setParameter()</methodname> calls and the 
+      The third new part is the use of dynamic action attributes. These
+      are extra attributes that have not been defined by the <classname>Action</classname>
+      interface. To set a dynamic attribute we call the
+      <methodname>setParameter()</methodname> method and then 
       <methodname>MenuItemBean.setDynamicActionAttributesSource()</methodname>
-      call. The dynamic attributes are a simple way to output data to
+      The dynamic attributes are a simple way to output data to
       the HTML that is later needed by scripts. In this case, the generated
       HTML may look something like this:
@@ -1638 +1768 @@
       
       <note>
-        <title>onclick is deprecated</title>
+        <title>onclick has been removed</title>
         <para>
-          The onclick attribute has been deprecated since BASE 3.3. Use a custom script instead to
+          The onclick attribute has been deprecated since BASE 3.3 and was removed in BASE 3.5. Use a custom script instead to
           bind the click event with the menu item or <sgmltag class="starttag">data-url</sgmltag>
           if the menu simply navigates to another page. <sgmltag class="starttag">data-popup</sgmltag> 
@@ -1675 +1805 @@
       
       <note>
-        <title>onclick is deprecated</title>
+        <title>onclick has been removed</title>
         <para>
-          The onclick attribute has been deprecated since BASE 3.3. Use a custom script instead to
+          The onclick attribute has been deprecated since BASE 3.3 and was removed in BASE 3.5. Use a custom script instead to
           bind the click event with the button. Download the example code to see it in action.
         </para>