<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link rel="home" title="HomePage" href="HomePage.html" />
<link rel="help" title="HowToUseWiki" href="HowToUseWiki.html" />
<link rel="copyright" title="GNU General Public License" href="http://www.gnu.org/copyleft/gpl.html#SEC1" />
<link rel="author" title="The PhpWiki Programming Team" href="http://phpwiki.org/ThePhpWikiProgrammingTeam" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta http-equiv="Content-Language" content="en" />
<meta name="robots" content="noindex,nofollow" />
<meta name="language" content="en" />
<meta name="document-type" content="Public" />
<meta name="document-rating" content="General" />
<meta name="generator" content="PhpWiki" />
<meta name="PHPWIKI_VERSION" content="1.3.14" />

<link rel="stylesheet" type="text/css" charset="iso-8859-1" href="phpwiki-printer.css" />
<title>PhpWiki - FormMagick HOWTO</title>
</head>
<body>

<div id="header">
  
<!-- Page title -->
<h1>FormMagick HOWTO</h1>
</div>
<div id="content">



<div class="wikitext"><h3>FormMagick HOWTO</h3>
<p class="tightenable">This HOWTO will outline how to create and maintain panels on the SME Server using the <span><a href="esmith.html" class="wiki relation">esmith</a><span class="relation-symbol">::</span><a href="FormMagick.html" class="wiki">FormMagick</a></span> module, just like all of the official panels are done.</p>
<p class="tightenable">This is currently a work-in-progress.</p>
<h4>Why use FormMagick?</h4>
<p class="tightenable">Primarily, because FormMagick provides a localization API, so that panels can be provided in multiple languages, with the text separated out in XML lexicon files. These files can then be given to anyone wanting to translate the server's panels, and they can provide translations. This makes the SME Server a truly international project. Please, think of others. Not everyone speaks English.</p>
<p class="tightenable">Additionally, <span><a href="esmith.html" class="wiki relation">esmith</a><span class="relation-symbol">::</span><a href="FormMagick.html" class="wiki">FormMagick</a></span> subclasses <span><a href="CGI.html" class="wiki relation">CGI</a><span class="relation-symbol">::</span><a href="FormMagick.html" class="wiki">FormMagick</a></span> and provides certain boilerplate code for the panels to make life easier for panel authors. It also causes certain problems which will be detailed here, with their current solutions.</p>
<h4>Getting Started</h4>
<p class="tightenable">As always, use the source. Look at the existing panels, most of which use FormMagick, and learn from them. The ones that truly use FormMagick have an xml page definition in the cgi script at /etc/e-smith/web/functions. Lets look at a simple one. If you have a 6.0 SME Server, look at /etc/e-smith/web/functions/quota. This is the cgi script that is run when you click on quotas in the server manager's menu.</p>
<pre class="tightenable">
#!/usr/bin/perl -wT

#----------------------------------------------------------------------
# heading     : Collaboration
# description : Quotas
# navigation  : 2000 2300
#----------------------------------------------------------------------</pre>
<p class="tightenable">As you can see, we're running perl with warnings and taint-checking turned-on. Good ideas for a CGI script. The comments here are picked up when the menu is generated, so the Quota panel ends up the Collaboration section, and the weighting controls where not only that section ends up, but where in that section it appears. Lets continue past the Mitel copyright.</p>
<pre class="tightenable">
use strict;
use <span><a href="esmith.html" class="wiki relation">esmith</a><span class="relation-symbol">::</span><a href="FormMagick%3A%3APanel%3A%3Aquota%3B.html" class="wiki">FormMagick::Panel::quota;</a></span>

my $panel = <span><a href="esmith.html" class="wiki relation">esmith</a><span class="relation-symbol">::</span><a href="FormMagick%3A%3APanel%3A%3Aquota-%3Enew%28%29%3B.html" class="wiki">FormMagick::Panel::quota-&gt;new();</a></span>
$panel-&gt;display();</pre>
<p class="tightenable">We use the strict pragma, good idea for any Perl script beyond 10 lines or so, and then use a module called <span><a href="esmith.html" class="wiki relation">esmith</a><span class="relation-symbol">::</span><a href="FormMagick%3A%3APanel%3A%3Aquota..html" class="wiki">FormMagick::Panel::quota.</a></span> We'll find out what that is later. Then, we instantiate an instance of that class, and call its display method. That's basically it for Perl code in the CGI front-end.</p>
<p class="tightenable">Next, in the section of the CGI, is the XML page definition. This is the heart of FormMagick, allowing you to describe the pages in your CGI using XML. Lets look at it.</p>
<pre class="tightenable">
&lt;form title=&quot;FORM_TITLE&quot; header=&quot;/etc/e-smith/web/common/head.tmpl&quot;
                         footer=&quot;/etc/e-smith/web/common/foot.tmpl&quot;&gt;</pre>
<p class="tightenable">We start the DATA section, and then the form itself, specifying the lexicon tag for the form title, and the paths to the page header and footer. I'll explain lexicon later, but pay attention to it. It's a vital part of FormMagick's localisation API (not everyone speaks English...).</p>
<pre class="tightenable">
  &lt;page name=&quot;Initial&quot; pre-event=&quot;print_status_message&quot;&gt;
    &lt;subroutine src=&quot;showInitial()&quot;/&gt;
  &lt;/page&gt;</pre>
<p class="tightenable">This is our first page definition. We name the page &quot;Initial&quot;, define a pre-event to call the <tt>print_status_message</tt> function, and then define the contents of our page. In this case, we don't define a bunch of widgets and their callbacks, we just tell FormMagick to call a subroutine called <tt>showInitial</tt>. That subroutine is exported in the module we included, and we'll cover it later, but basically, it outputs the initial quota page you see when you load the panel.</p>
<p class="tightenable">The next page definition is a little more standard FormMagick.</p>
<pre class="tightenable">
  &lt;page name=&quot;Modify&quot; pre-event=&quot;turn_off_buttons&quot;
  post-event=&quot;performModifyUser&quot;&gt;
    &lt;title&gt;MODIFY_USER_TITLE&lt;/title&gt;
    &lt;subroutine src=&quot;modifyUser()&quot;/&gt;
    &lt;subroutine src=&quot;print_button('SAVE')&quot;/&gt;
  &lt;/page&gt;</pre>
<p class="tightenable bottom">Here, we define a page called &quot;Modify&quot;, and call a pre-event subroutine of <tt>turn_off_buttons</tt>. We do that because by default, FormMagick will create a &quot;Next&quot; button, and we don't want one here. We define a post-event of <tt>performModifyUser</tt>, a function we define to handle the form submission. The page title is defined as the lexicon of <tt>MODIFY_USER_TITLE</tt>, and then we call two subroutines to draw the page itself. Note that for static form contents, like groups of widgets, we would define them right in the XML. We will cover an example of that later. For now, I'd like to cover the relationship between the front-end and the back-end.</p>
</div>

<div id="footer">  <hr class="printer" noshade="noshade" />
<p class="editdate">Owner: <a href="msoulier.html" class="wiki">msoulier</a>  Last edited on March 2, 2004  1:32 am by <a href="msoulier.html" class="wiki">msoulier</a></p>
</div>

</div>
<!-- Add your Disclaimer here -->
</body>
</html>
