Changeset 6812 for trunk/doc/src/docbook


Ignore:
Timestamp:
Mar 30, 2015, 10:46:31 AM (7 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:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/src/docbook/developer/extensions.xml

    r6685 r6812  
    233233      of an extension. This extension will add a new menu item in the
    234234      menu which displays a popup with the text "Hello world!" when
    235       selected. Copy the XML code below and save it to a file in
    236       the <filename>plugins.dir</filename>
    237       directory. The filename must end with <filename>.xml</filename>.
    238       Install the extension by going through the installation wizard
    239       at <menuchoice>
    240           <guimenu>Administrate</guimenu>
    241           <guimenuitem>Plug-ins &amp; extensions</guimenuitem>
    242           <guimenuitem>Overview</guimenuitem>
    243         </menuchoice>.
    244     </para>
    245    
    246     <para>
    247       When the extension has been installed you should have a new
    248       menu item:
    249       <menuchoice>
    250         <guimenu>Extensions</guimenu>
    251         <guimenuitem>Hello world!</guimenuitem>
    252       </menuchoice>
    253       which pops up a message in a Javascript window.
    254     </para>
    255    
    256     <note>
    257       <para>
    258       You may have to logout and login again to see the new menu item.
    259       </para>
    260     </note>
    261    
    262     <programlisting language="xml">
     235      selected.
     236    </para>
     237   
     238    <orderedlist>
     239      <listitem>
     240      <para>
     241      Start by creating an empty directory in some suitable
     242      location on your hard disk. Inside this directory, create two more
     243      directories <filename>META-INF</filename> and
     244      <filename>resources</filename>.
     245      </para>
     246      </listitem>
     247     
     248      <listitem>
     249      <para>
     250      Copy the XML code below and save it to <filename>META-INF/extensions.xml</filename>
     251      in your newly created directory. It is important that you get the filename
     252      correct.
     253      </para>
     254     
     255      <programlisting language="xml">
    263256<![CDATA[
    264257<?xml version="1.0" encoding="UTF-8" ?>
     
    269262      >
    270263      <index>1</index>
    271       <about>
     264      <about safe-scripts="1">
    272265         <name>Hello world</name>
    273266         <description>
     
    282275         </factory-class>
    283276         <parameters>
     277          <id>hello-world</id>
    284278            <title>Hello world!</title>
    285279            <tooltip>This is to test the extensions system</tooltip>
    286             <onClick>alert('Hello world!')</onClick>
    287280            <icon>/images/info.png</icon>
     281            <script>~/hello.js</script>
    288282         </parameters>
    289283      </action-factory>
     
    292286]]>
    293287</programlisting>
     288      <para>
     289        This file is the most important one when creating extensions
     290        since it is used to tell BASE about the extensions (and
     291        plug-ins) in the package. See below for more information.
     292      </para>
     293      </listitem>
     294     
     295      <listitem>
     296      <para>
     297      Copy the javascript code below and save it to <filename>resources/hello.js</filename>
     298      in your newly created directory. Once again, it is important that the filename
     299      is correct.
     300      </para>
     301      <programlisting language="javascript">
     302<![CDATA[
     303var HelloWorld = function() 
     304
     305   var hello = {}; 
     306   
     307    /**
     308       Executed once when the page is loaded. Typically
     309       used to bind events to fixed control elements.
     310    */ 
     311    hello.initMenuItems = function() 
     312    { 
     313       // Bind event handlers the menu items.   
     314       // First parameter is the ID of the menu item 
     315       // Second parameter is the event to react to (=click) 
     316       // Last parameter is the function to execute 
     317       Events.addEventHandler('hello-world', 'click', hello.helloWorld); 
     318    } 
     319     
     320    // Show 'Hello world' message
     321    hello.helloWorld = function(event) 
     322    { 
     323       alert('Hello world');
     324    } 
     325     
     326    return hello; 
     327}(); 
     328     
     329//Register the page initializer method with the BASE core 
     330Doc.onLoad(HelloWorld.initMenuItems); 
     331]]>
     332</programlisting>
     333      </listitem>
     334   
     335      <listitem>
     336      <para>
     337      Create a JAR package containing the two directories and files
     338      you have created. It is important the the subdirectory structure
     339      inside the JAR file is rooted at the first empty directory you created.
     340      </para>
     341     
     342        <literallayout>
     343<filename class="directory">META-INF/</filename>
     344<filename>META-INF/extensions.xml</filename>
     345<filename class="directory">resources/</filename>
     346<filename>resources/hello.js</filename>
     347        </literallayout>
     348     
     349      <para>
     350        Copy the JAR file to the the <filename>plugins.dir</filename>
     351        directory for your BASE installation.
     352      </para>
     353      </listitem>
     354   
     355      <listitem>
     356      <para>
     357        Log in to BASE and install the extension by going through the
     358        installation wizard at <menuchoice>
     359            <guimenu>Administrate</guimenu>
     360            <guimenuitem>Plug-ins &amp; extensions</guimenuitem>
     361            <guimenuitem>Overview</guimenuitem>
     362          </menuchoice>.
     363        When the extension has been installed you should have a new
     364        menu item:
     365        <menuchoice>
     366          <guimenu>Extensions</guimenu>
     367          <guimenuitem>Hello world!</guimenuitem>
     368        </menuchoice>
     369        which pops up a message in a Javascript window.
     370       
     371      </para>
     372      <note>
     373        <para>
     374        You may have to logout and login again to see the new menu item.
     375        </para>
     376      </note>
     377      </listitem>
     378   
     379    </orderedlist>
     380   
     381    <sect2 id="extensions_developer.extensions.xml">
     382      <title>The extensions.xml file</title>
    294383   
    295384    <para>
     
    388477      <title>Content security policy and inline javascript</title>
    389478      <para>
    390         In the above example <sgmltag class="starttag">onClick</sgmltag> is
    391         a parameter that contains a javascript statement. In general, we recommend
    392         that inline javascript is avoided due to security vulernabilities.
    393         If you install the above extension, your BASE server probably display
    394         a warning message about violating the <emphasis>Content security policy</emphasis>.
    395         If so, you need to change the configuration to be less restricted. See
     479        The Hello World example requires quite a lot of code and it
     480        would have been tempting to skip the <filename>hello.js</filename>
     481        file and simply add
     482       
     483        <code><sgmltag class="starttag">onclick</sgmltag>alert('Hello world')<sgmltag class="endtag">onclick</sgmltag></code>
     484       
     485        to the <sgmltag class="starttag">parameters</sgmltag> section in the
     486        <filename>extensions.xml</filename> file. However, BASE is by default
     487        configured to block all inline JavaScript since it opens up for
     488        cross-site scripting attacks. It is possible to relax this policy
     489        but it is nothing we recommend. See
    396490        <xref linkend="appendix.web.xml.csp-filter" /> for more information.
    397491      </para>
     
    404498      </para>
    405499    </note>
     500   
     501    </sect2>
    406502   
    407503    <sect2 id="extensions_developer.extend_multiple">
     
    486582      InvokationContext<? super MenuItemAction> context)
    487583   {
     584      JspContext jspContext = (JspContext)context.getClientContext();
     585      String home = jspContext.getHome(context.getExtension());
     586      jspContext.addScript(home + "/hello.js");
    488587      return true;
    489588   }
     
    498597      {
    499598         MenuItemBean bean = new MenuItemBean();
     599         bean.setId("hello-factory");
    500600         bean.setTitle("Hello factory world!");
    501601         bean.setIcon(jspContext.getRoot() + "/images/info.gif");
    502          // NOTE! onclick is deprected! A real implementation
    503          // should bind events using to the menu using javascript
    504          bean.setOnClick("alert('Hello factory world!')");
    505602         helloWorld[0] = bean;
    506603      }
     
    512609
    513610    <para>
    514       And here is the XML configuration file that goes with it.
     611      And here are the XML and JavaScript files that goes with it.
    515612    </para>
    516613
     
    540637]]>
    541638</programlisting>
     639    <programlisting language="javascript">
     640<![CDATA[
     641var HelloWorldFactory = function() 
     642
     643   var hello = {}; 
     644   
     645    /**
     646       Executed once when the page is loaded. Typically
     647       used to bind events to fixed control elements.
     648    */ 
     649    hello.initMenuItems = function() 
     650    { 
     651       // Bind event handlers the menu items.   
     652       // First parameter is the ID of the menu item 
     653       // Second parameter is the event to react to (=click) 
     654       // Last parameter is the function to execute 
     655       Events.addEventHandler('hello-factory', 'click', hello.helloFactoryWorld); 
     656    } 
     657     
     658    // Show 'Hello factory world' message
     659    hello.helloFactoryWorld = function(event) 
     660    { 
     661       alert('Hello factory world');
     662    } 
     663     
     664    return hello; 
     665}(); 
     666     
     667//Register the page initializer method with the BASE core 
     668Doc.onLoad(HelloWorldFactory.initMenuItems); 
     669]]>
     670</programlisting>
    542671   
    543672    <para>
    544673      To install this extension you need to put the compiled
    545       <filename>HelloWorldFactory.class</filename> and the XML
    546       file inside a JAR file. The XML file must be located at
    547       <filename>META-INF/extensions.xml</filename> and the class
     674      <filename>HelloWorldFactory.class</filename>, the XML
     675      and JavaScript files inside a JAR file. The XML file must be located at
     676      <filename>META-INF/extensions.xml</filename> the JavScript file
     677      at <filename>resources/hello.js</filename>, and the class
    548678      file at <filename>net/sf/basedb/examples/extensions/HelloWorldFactory.class</filename>.
    549679    </para>
     
    701831   
    702832    <para>
    703       The third new part is that the call to <methodname>MenuItemBean.setOnClick()</methodname>
    704       has been removed. To replace the inline scripting functionality we need
    705       the <methodname>MenuItemBean.setId()</methodname> call, the
    706       <methodname>setParameter()</methodname> calls and the
     833      The third new part is the use of dynamic action attributes. These
     834      are extra attributes that have not been defined by the <classname>Action</classname>
     835      interface. To set a dynamic attribute we call the
     836      <methodname>setParameter()</methodname> method and then
    707837      <methodname>MenuItemBean.setDynamicActionAttributesSource()</methodname>
    708       call. The dynamic attributes are a simple way to output data to
     838      The dynamic attributes are a simple way to output data to
    709839      the HTML that is later needed by scripts. In this case, the generated
    710840      HTML may look something like this:
     
    16381768     
    16391769      <note>
    1640         <title>onclick is deprecated</title>
     1770        <title>onclick has been removed</title>
    16411771        <para>
    1642           The onclick attribute has been deprecated since BASE 3.3. Use a custom script instead to
     1772          The onclick attribute has been deprecated since BASE 3.3 and was removed in BASE 3.5. Use a custom script instead to
    16431773          bind the click event with the menu item or <sgmltag class="starttag">data-url</sgmltag>
    16441774          if the menu simply navigates to another page. <sgmltag class="starttag">data-popup</sgmltag>
     
    16751805     
    16761806      <note>
    1677         <title>onclick is deprecated</title>
     1807        <title>onclick has been removed</title>
    16781808        <para>
    1679           The onclick attribute has been deprecated since BASE 3.3. Use a custom script instead to
     1809          The onclick attribute has been deprecated since BASE 3.3 and was removed in BASE 3.5. Use a custom script instead to
    16801810          bind the click event with the button. Download the example code to see it in action.
    16811811        </para>
Note: See TracChangeset for help on using the changeset viewer.