home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _49834868dd01aa5f4433acf3d01c1b0e < prev    next >
Text File  |  2000-03-23  |  8KB  |  240 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>CGI::Imagemap.pm - imagemap behavior for CGI programs</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> CGI::Imagemap.pm - imagemap behavior for CGI programs</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <UL>
  26.  
  27.         <LI><A HREF="#static methods">Static Methods</A></LI>
  28.         <LI><A HREF="#class methods">Class Methods</A></LI>
  29.     </UL>
  30.  
  31.     <LI><A HREF="#example">EXAMPLE</A></LI>
  32.     <LI><A HREF="#bugs">BUGS</A></LI>
  33.     <LI><A HREF="#author">AUTHOR</A></LI>
  34.     <LI><A HREF="#credits">CREDITS</A></LI>
  35. </UL>
  36. <!-- INDEX END -->
  37.  
  38. <HR>
  39. <P>
  40. <H1><A NAME="name">NAME</A></H1>
  41. <P>CGI::Imagemap.pm - imagemap behavior for CGI programs</P>
  42. <P>
  43. <HR>
  44. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  45. <UL>
  46. <LI>Linux</LI>
  47. <LI>Solaris</LI>
  48. <LI>Windows</LI>
  49. </UL>
  50. <HR>
  51. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  52. <PRE>
  53.   use CGI::Imagemap;
  54. </PRE>
  55. <PRE>
  56.  
  57.   $map = new CGI::Imagemap;
  58.   $map->setmap(@map);
  59.   $action = $map->action($x,$y);</PRE>
  60. <PRE>
  61.  
  62. -- or --</PRE>
  63. <PRE>
  64.   use CGI::Imagemap 'action_map';
  65. </PRE>
  66. <PRE>
  67.  
  68.   $action = action_map($x,$y,@map);</PRE>
  69. <P>
  70. <HR>
  71. <H1><A NAME="description">DESCRIPTION</A></H1>
  72. <P>CGI::Imagemap allows CGI programmers to place TYPE=IMAGE form fields on
  73. their HTML fill-out forms, with either client-side or server-side maps
  74. emulated.</P>
  75. <P>The imagemap file follows that of the NCSA imagemap program.  Each point
  76. is an x,y tuple.  Each line in the map consists of
  77. one of the following formats.  Comment lines start with ``#''.</P>
  78. <PRE>
  79.   circle action center edgepoint
  80.   rect action upperleft lowerright
  81.   point action point
  82.   poly action point1 point2 ... pointN
  83.   default action</PRE>
  84. <P>Using ``point'' and ``default'' in the same map makes no sense. If ``point''
  85. is used, the action for the closest one is selected.</P>
  86. <P>To use CGI::Imagemap, define an image submit map on your form with
  87. something like:</P>
  88. <PRE>
  89.    <input type=image name=mv_todo
  90.         SRC="image_url"></PRE>
  91. <P>You can pass a ``client-side'' imagemap like this:</P>
  92. <PRE>
  93.    <input type="hidden" name="todo.map"
  94.                 value="rect action1 0,0 25,20">
  95.    <input type="hidden" name="todo.map"
  96.                 value="rect action2 26,0 50,20">
  97.    <input type="hidden" name="todo.map"
  98.                 value="rect action3 51,0 75,20">
  99.    <input type="hidden" name="todo.map"
  100.                 value="default action0"></PRE>
  101. <P>If the @map passed parameter contains a NUL (\0) in the first array
  102. position, the map is assumed to be null-separated and @map is built
  103. by splitting it.  This allows a null-separated todo.map with
  104. multiple values (parsed by a cgi-lib.pl or the like) to be
  105. referenced.</P>
  106. <P>All of the following examples assume the above definitions in your
  107. form.</P>
  108. <P>
  109. <H2><A NAME="static methods">Static Methods</A></H2>
  110. <P>CGI::Imagemap allows the export of two routines, <EM>action_map</EM> and
  111. <EM>map_untaint</EM>.   If you choose to use CGI::Imagemap statically, call the
  112. module with:</P>
  113. <PRE>
  114.   use CGI::Imagemap qw(action_map map_untaint);</PRE>
  115. <DL>
  116. <DT><STRONG><A NAME="item_action_map"><CODE>action_map(x,y,map)</CODE></A></STRONG><BR>
  117. <DD>
  118. We are assuming the map definition above, with the <EM>type=image</EM>
  119. variable named <EM>todo</EM>, and the map in <EM>todo.map</EM>. You can pass the map
  120. in one of two ways.  The first is compatible with the CGI.pm (or CGI::*)
  121. modules, and passes the map as an array:
  122. <PRE>
  123.     $query = new CGI;
  124.     my $x = $query->param('todo.x');
  125.     my $y = $query->param('todo.y');
  126.     my $map = $query->param('todo.map');
  127.     $action = action_map($x, $y, $map);</PRE>
  128. <P>If you are using the old <EM>cgi-lib.pl</EM> library, which places multiple
  129. instances of the same form variable in a scalar, separated by null (\0)
  130. characters, you can do this:</P>
  131. <PRE>
  132.     ReadParse(*FORM);
  133.     my $x = $FORM{'todo.x'};
  134.     my $y = $FORM{'todo.y'};
  135.     my $map = $FORM{'todo.map'};
  136.     $action = action_map($x, $y, $map);</PRE>
  137. <P></P>
  138. <DT><STRONG><A NAME="item_map_untaint"><CODE>map_untaint($untaint)</CODE></A></STRONG><BR>
  139. <DD>
  140. If you are running with taint checking, as is suggested for CGI programs,
  141. you can use <A HREF="#item_map_untaint"><CODE>map_untaint(1)</CODE></A> to set map untainting on a global basis. 
  142. (If using class methods, each has its own instance of untainting).
  143. <P>It ensures all characters in the action fit pattern of [-\w.+@]+,
  144. meaning alphnumerics, underscores, dashes (-), periods, and the @ sign.
  145. It also checks the methods (rect,poly,point,default,circle) and ensures
  146. that points/tuples are only integers.  Once that is done, it untaints
  147. the passed form variables.</P>
  148. <PRE>
  149.   map_untaint(1);    # Turns on untainting
  150.   map_untaint('yes');# Same as above</PRE>
  151. <PRE>
  152.   map_untaint(0);    # Disable untainting
  153.   map_untaint('no'); # Same as above
  154. </PRE>
  155. <PRE>
  156.  
  157.   $status = map_untaint(); # Get status</PRE>
  158. <P>Default is no untainting.</P>
  159. <P></P></DL>
  160. <P>
  161. <H2><A NAME="class methods">Class Methods</A></H2>
  162. <P>The class methods for CGI::Imagemap are much the same as above, with the
  163. exception that multiple imagemaps are then maintained by the module, with
  164. full independence. The following method definitions assume the CGI::Form
  165. module is being used, like this:</P>
  166. <PRE>
  167.     use CGI::Form;
  168.     use CGI::Imagemap;</PRE>
  169. <PRE>
  170.     $query  = new CGI::Form;
  171.     $map    = new CGI::Imagemap;</PRE>
  172. <DL>
  173. <DT><STRONG><A NAME="item_setmap"><CODE>setmap(@map)</CODE></A></STRONG><BR>
  174. <DD>
  175. This sets the map for the instance.
  176. <PRE>
  177.     $map = new CGI::Imagemap;
  178.     $map->setmap($query->param('todo.map'));</PRE>
  179. <P></P>
  180. <DT><STRONG><A NAME="item_addmap"><CODE>addmap(@map)</CODE></A></STRONG><BR>
  181. <DD>
  182. This adds a new map action specification <EM>to the current map</EM>.
  183. <PRE>
  184.   $map->addmap('point action5 3,9'));</PRE>
  185. <P></P>
  186. <DT><STRONG><A NAME="item_action"><CODE>action(x,y)</CODE></A></STRONG><BR>
  187. <DD>
  188. This finds the action, based on the active map and the values of x and y,
  189. <PRE>
  190.   $x = $query->param('todo.x');
  191.   $y = $query->param('todo.y');
  192.   $action = $map->action($x, $y);</PRE>
  193. <P></P>
  194. <DT><STRONG><A NAME="item_untaint"><CODE>untaint()</CODE></A></STRONG><BR>
  195. <DD>
  196. Sets, unsets, or returns the taint status for the instance.
  197. <PRE>
  198.   $map->untaint(1);       # Turns on untainting
  199.   $map->untaint('yes');   # Same as above
  200.   $map->untaint(1);       # Disables untainting
  201.   $map->untaint('yes');   # Same as above
  202.   $status = $map->untaint(); # Get status</PRE>
  203. <P></P>
  204. <DT><STRONG><A NAME="item_version"><CODE>version()</CODE></A></STRONG><BR>
  205. <DD>
  206. Returns the version number of the module.
  207. <P></P></DL>
  208. <P>
  209. <HR>
  210. <H1><A NAME="example">EXAMPLE</A></H1>
  211. <P>A couple of self-contained examples are included in the CGI::Imagemap
  212. package.  They are:</P>
  213. <PRE>
  214.   testmap     -  Uses the CGI::Form module
  215.   testmap.old -  Uses the old cgi-lib.pl</PRE>
  216. <P>
  217. <HR>
  218. <H1><A NAME="bugs">BUGS</A></H1>
  219. <P>The untainting stuff is not totally independent -- threading might
  220. not work very well.  This can be fixed if it is important -- in the
  221. CGI world, I doubt it.</P>
  222. <P>
  223. <HR>
  224. <H1><A NAME="author">AUTHOR</A></H1>
  225. <P>Mike Heins, Internet Robotics, <<A HREF="mailto:mikeh@iac.net">mikeh@iac.net</A>></P>
  226. <P>
  227. <HR>
  228. <H1><A NAME="credits">CREDITS</A></H1>
  229. <P>This work is heavily kited from the Perl imagemap program originally
  230. written by V. Khera <<A HREF="mailto:khera@kciLink.com">khera@kciLink.com</A>>.</P>
  231. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  232. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  233. <STRONG><P CLASS=block> CGI::Imagemap.pm - imagemap behavior for CGI programs</P></STRONG>
  234. </TD></TR>
  235. </TABLE>
  236.  
  237. </BODY>
  238.  
  239. </HTML>
  240.