root/Chameleon/trunk/Chameleon/KeepSessionAlive/KeepSessionAlive.en-ca.doc.xml

<?xml version="1.0" encoding="UTF-8"?>
<ca:widgetdoc xmlns:ca="http://localhost/chameleon/utils/xml/schemas" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://localhost/chameleon/utils/xml/schemas ..\..\..\utils/xml/schemas/chameleon.xsd">
  <ca:docinfo>
    <ca:language>
      <ca:value>en-ca</ca:value>
    </ca:language>
    <ca:docbuilddate>
      <ca:value>1999-12-31</ca:value>
    </ca:docbuilddate>
    <ca:docversion>
      <ca:value>0.1</ca:value>
    </ca:docversion>
    <ca:authors>
      <ca:person>
        <ca:name>Doc_Builder</ca:name>
        <ca:company>DM Solutions Group Inc.</ca:company>
        <ca:contact>chameleon@lists.maptools.org</ca:contact>
      </ca:person>
    </ca:authors>
    <ca:editors>
      <ca:person>
        <ca:name>Christopher R. Thorne</ca:name>
        <ca:company>DM Solutions Group Inc.</ca:company>
        <ca:contact>chameleon@lists.maptools.org</ca:contact>
      </ca:person>
      <ca:person>
        <ca:name>Paul Spencer</ca:name>
        <ca:company>DM Solutions Group Inc.</ca:company>
        <ca:contact>chameleon@lists.maptools.org</ca:contact>
      </ca:person>
    </ca:editors>
  </ca:docinfo>
  <ca:identification>
    <ca:name>
      <ca:value>KeepSessionAlive</ca:value>
    </ca:name>
    <ca:chameleonpack>
      <ca:value>TBD</ca:value>
    </ca:chameleonpack>
    <ca:parentgroup>
      <ca:value>Utility Widget</ca:value>
    </ca:parentgroup>
    <ca:version>
      <ca:value>2.0</ca:value>
    </ca:version>
    <ca:releasedate>
      <ca:value>2005-01-10</ca:value>
    </ca:releasedate>
    <ca:maturitylevel>
      <ca:value>TECHRELEASE</ca:value>
    </ca:maturitylevel>
    <ca:developers>
      <ca:person>
        <ca:name>Paul Spencer</ca:name>
        <ca:company>DM Solutions Group Inc.</ca:company>
        <ca:contact>chameleon@lists.maptools.org</ca:contact>
      </ca:person>
    </ca:developers>
  </ca:identification>
  <ca:descriptions>
    <ca:description>
      <ca:paras>
        <ca:para>Chameleon applications remember the current state of the application by saving some settings in a server-side session.  By default, server-side sessions are configured to expire after some pre-determined period of inactivity (typically, 30 minutes).  The KeepSessionAlive widget is used to ensure that a user's session never expires while the application is open in a browser window.  This "invisible" widget needs to be placed somewhere inside the body of the application page. It represents itself in the Web page as a transparent 1x1 pixel image that refreshes its contents on a regular (configurable) basis in order to keep the associated PHP session alive.</ca:para>
      </ca:paras>
    </ca:description>
    <ca:dependancies>
      <ca:dependancy type="None" title="">
        <ca:para/>
      </ca:dependancy>
    </ca:dependancies>
    <ca:sharedresources>
      <ca:paras title="None Available.">
        <ca:para/>
      </ca:paras>
    </ca:sharedresources>
    <ca:embeddedhelp>
      <ca:paras>
        <ca:para/>
      </ca:paras>
    </ca:embeddedhelp>
    <ca:guinotes title="Interface Functionality">
      <ca:guinote type="General" title="To Keep it Going...">
        <ca:para>Expiration of sessions is intended to reduce server stress by allowing cleanup of extraneous session files on a regular basis.  Some applications may be intended to be long-lived, particularly those built for an internal or closed audience.  In these cases, it is sometimes desirable to keep the application's session alive even though the user may not be using it constantly.</ca:para>
        <ca:para>It is not recommended that the KeepSessionAlive widget be used on high-load servers with restricted temporary space or in applications that don't specifically require this functionality.</ca:para>
      </ca:guinote>
    </ca:guinotes>
  </ca:descriptions>
  <ca:tagstructures>
    <ca:tagstructure title="Widget Syntax">
      <ca:description/>
      <ca:code>
        <ca:codeblock bold="true">
          <ca:line>&lt;CWC2 TYPE="KeepSessionAlive"</ca:line>
        </ca:codeblock>
        <ca:codeblock bold="false">
          <ca:line>   ENABLED="[TRUE|FALSE]" </ca:line>
          <ca:line>   FORMINDEX="[0 &lt; integer]"</ca:line>
          <ca:line>   VISIBLE="[TRUE|FALSE]"</ca:line>
          <ca:line/>
          <ca:line>   &lt;!-- KeepSessionAlive Attributes --&gt;</ca:line>
          <ca:line/>
          <ca:line>   TIMEOUT="[0 &lt; integer &lt; 1800]"/&gt;</ca:line>
        </ca:codeblock>
      </ca:code>
    </ca:tagstructure>
  </ca:tagstructures>
  <ca:examples>
    <ca:widgetexamples>
      <ca:example title="Example #1: Simple">
        <ca:description>The following example tag keeps the session alive every 300 seconds or 5 minutes.</ca:description>
        <ca:code>
          <ca:codeblock bold="false">
            <ca:line>&lt;cwc2 type="KeepSessionAlive" timeout="300"/&gt;</ca:line>
          </ca:codeblock>
        </ca:code>
      </ca:example>
    </ca:widgetexamples>
    <ca:sampleapps>
      <ca:sampleapp>
        <ca:name>Hawaii Demo</ca:name>
        <ca:appurl>www.mapsherpa.com/hawaii2/</ca:appurl>
        <ca:description>The Hawaii Demo uses the latest 1.99 Chameleon version.</ca:description>
      </ca:sampleapp>
    </ca:sampleapps>
    <ca:scriptexamples/>
  </ca:examples>
  <ca:attributegroups>
    <ca:attributegroup>
      <ca:name>Base</ca:name>
    </ca:attributegroup>
  </ca:attributegroups>
  <ca:widgettag>
    <ca:attribute>
      <ca:name>TIMEOUT</ca:name>
      <ca:type>
        <ca:value>integer</ca:value>
      </ca:type>
      <ca:class>
        <ca:value>Widget Only</ca:value>
      </ca:class>
      <ca:default>
        <ca:value>1800</ca:value>
        <ca:description/>
      </ca:default>
      <ca:possvalues type="range">
        <ca:minimum>0</ca:minimum>
        <ca:maximum>1800</ca:maximum>
      </ca:possvalues>
      <ca:description>Set the period (in seconds) after which the application automatically connects to the server to keep the session alive.</ca:description>
    </ca:attribute>
  </ca:widgettag>
  <ca:formelements>
    <ca:formelement>
      <ca:name>sid</ca:name>
      <ca:type>
        <ca:value>unknown</ca:value>
      </ca:type>
      <ca:description/>
    </ca:formelement>
  </ca:formelements>
  <ca:jsfunctions>
    <ca:jsfunction>
      <ca:name>KeepSessionAlive_</ca:name>
      <ca:scope>
        <ca:value>Private</ca:value>
      </ca:scope>
      <ca:description>The guts of this widget that refresh the hidden image to prevent the session timing out.</ca:description>
    </ca:jsfunction>
  </ca:jsfunctions>
</ca:widgetdoc>