Vyššie na [Platon] / phpMyEdit / doc / sgml

Updated documentation on extensions, added extensions to distribution
package and bumped version to 5.5rc1 (release candidate 1)

<!-- $Platon: phpMyEdit/doc/sgml/extensions.sgml,v 1.16 2004/03/20 12:15:38 nepto Exp $ -->

<chapter id="extensions">
<title id="extensions.title">Extensions</title>

<para>

There are often situations, when more specific functionality is needed from
&name;. You will surely agree, that it will be really strange to hardcode all
these particular requirements into the core &name; class. For this reason the
extension mechanism is provided.

</para>

<sect1 id="extensions.overview">
<title id="extensions.overview.title">Overview</title>
<para>

Extensions are &name;_&lt;something&gt; classes, where &lt;something&gt; is an
appropriate extension name. They not only extend base &name; class, but they
also add new functionality. But they may not only add new things. It is
possible also to disable such features, simply to get the desirable behaviour.

</para>
<para>

In addition to common &name; configuration options, extension configuration is
usually provided by <varname>$opts['ext']</varname> associative array.
Possible keys are described on particular extension pages in this manual.
Please refer to them to get more information.

</para>
<para>

Extensions are currently not part of &name; distribution. They are only in
<ulink url="http://platon.sk/cvs/cvs.php/&name;/extensions/">CVS
repository</>, because they are still under development and they are changing
a lot. This manual chapter is provided for letting &name; users know, that
something like this exists. The only way how to get extension files is to
fetch them from CVS. All extensions need to be placed under the <filename
class=directory>extensions/</> subdirectory below the &name; core class
location.

</para>
<para>

Several new extensions are planned to create or handle more or less specific
tasks, especially those which are not appropriate for the &name; core class.
You can feel absolutely free to improve existing extensions, suggest new
improvements for them, or create new extensions to fit your own needs. We will
be happy to add them to repository.

</para>
</sect1>

<sect1 id="extensions.slide">
<title id="extensions.slide.title">&name;-slide</title>
<para>

&name;-slide can create slideshow with ability to view and/or edit records.
Everytime is exactly one record shown. Record can be displayed in view or edit
mode. View mode looks like "view" functionality in normal &name;, change mode
looks like "change" functionality in normal &name;.

</para>
<para>

The only difference is that two buttons, <GUIbutton>Prev</> and
<GUIbutton>Next</>, are displayed in addition to common view/edit buttons to
provide ability of going to the next or previous record. This extension
purpously disable "add", "copy", "delete", and "table listing"
functionalities.

</para>
<para>

Here are configuration variables related to extension. All of these
&name;-slide options are optional.

<simplelist type=horiz columns=2>
<member> &nbsp; <varname>$opts['ext']['rec']</></>
<member> -- primary key value of record to display initially</>
<member> &nbsp; <varname>$opts['ext']['next_disable']</></>
<member> -- disable <GUIbutton>Next</> button</>
<member> &nbsp; <varname>$opts['ext']['prev_disable']</></>
<member> -- disable <GUIbutton>Prev</> button</>
</simplelist>

</para>
<para>

Following variables are not options, but they are used internally by
extension. They can be used for getting some information for example in
triggers.

<simplelist type=horiz columns=2>
<member> &nbsp; <varname>$opts['ext']['next']</></>
<member> -- primary key value of next record</>
<member> &nbsp; <varname>$opts['ext']['prev']</></>
<member> -- primary key value of previous record</>
</simplelist>

</para>
<para>

To use this extension you have to include
<filename>extensions/&name;-slide.class.php</filename> file and call
<varname>new &name;_slide($opts)</varname> instead of common &name; class
file.

</para>
</sect1>

<sect1 id="extensions.report">
<title id="extensions.report.title">&name;-report</title>
<para>

&name;-report extension is provided for easy table report creation. There is
often a need for selecting particular fields from table with applying specific
filter options and finally write out chosen subset of data (report) to HTML
page.

</para>
<para>

Navigation is easy to use. Field selection menu would be displayed if
<varname>fields_select</varname> parameter is passed by GET or POST HTTP method
to PHP script and it has non-empty value. This field selection menu contains
list of checkboxes connected with columns, list of filtering input fields and
also button for report creation. Every report page has ability to return back
into field selection. It is possible to specify amount of records on report
page, what is by default set to unlimited.

</para>
<para>

Extension can completelly work without cookies. However it uses cookies to
have a memory, where last selected report is stored. When user leaves report
PHP script and comes back after some time, a last selected report should be
predefined in checkboxes and input fields on fields selection screen.
Detection for cookie usage is done automatically. If HTTP headers was already
sent, cookies are not used, because they will cause an ugly warning. Otherwise
cookies are used for described kind of memory.

</para>
<para>

To use this extension simply include
<filename>extensions/&name;-report.class.php</filename> file and call
<varname>new &name;_report($opts)</varname> instead of common &name; class
file. Extension specific configuration parameters currently do not exist, thus
all table columns are allowed to be selected in final report. This will surely
change in future, because table could have columns that need to be
unselectable for final report (such as password column or similar).

</para>
</sect1>

<sect1 id="extensions.htmlarea">
<title id="extensions.htmlarea.title">&name;-htmlarea</title>
<para>

<warning><simpara>
This extension is obsolete. Use integrated <xref linkend="extensions.mce-cal"
endterm="extensions.mce-cal.title"> extension instead.
</simpara></warning>

</para>
<para>

&name;-htmlarea extension provides support for htmlArea. htmlArea is a free
WYSIWYG editor replacement for &lt;textarea&gt; fields.  For full source code
and documentation, visit <ulink
url="http://www.interactivetools.com/">http://www.interactivetools.com/</ulink>
website.

</para>
<para>

htmlArea requires Microsoft Internet Explorer 5.5 or better on Windows to run.
This is because it makes use of some advanced features of IE5.5 that aren't
available in other browsers yet. It is backwards compatible with other
browsers, though. They will get a regular textarea field instead of a WYSIWYG
editor.

</para>
<para>

The extension requires a properly installed htmlArea script as it is described
on the metioned website. This extension enables WYSIWYG editing of a textarea
field. In order to use it, you should:

<orderedlist>

<listitem>
<para>

Load htmlArea script in the &lt;head&gt;...&lt;/head&gt; section of
your &name; calling program as described in the htmlArea manual.

</para>
</listitem>

<listitem>
<para>

Call to <filename>&name;-htmlarea.class.php</> instead of
<filename>&name;.class.php</>.

<example><title>htmlArea extension enabling</title>
<programlisting>
require_once 'extensions/&name;-htmlarea.class.php';
new &name;_htmlarea($opts);
</programlisting>
</example>

</para>
</listitem>
    
<listitem>
<para>

Add <varname>'html'=&gt;true</> parameter to the textarea field
definition in your &name; calling program.

<example><title>htmlArea field enabling</title>
<programlisting><![CDATA[
$opts['fdd']['col_name'] = array(
 'name'     => 'Column',
 'select'   => 'T',
 'options'  => 'ACPVD',
 'required' => true,
 'textarea' => array(
   'html' => true,
   'rows' => 11,
   'cols' => 81)
);
]]></programlisting>
</example>

</para>
</listitem>
</orderedlist>

</para>
<para>

This extension is contribution of Ezudin Kurtowich
<email>ekurtovic@ieee.org</email> from Sarajevo.

</para>
</sect1>

<sect1 id="extensions.calpopup">
<title id="extensions.calpopup.title">&name;-calpopup</title>
<para>

<warning><simpara>
This extension is obsolete. Use integrated <xref linkend="extensions.mce-cal"
endterm="extensions.mce-cal.title"> extension instead.
</simpara></warning>

</para>
<para>

&name;-calpopup extension provides support for a calendar popup helper to be
put on any text field.  This extension uses the free jsCalendar code from
<ulink
url="http://dynarch.com/mishoo/calendar.epl">http://dynarch.com/mishoo/calendar.epl</ulink>
website.

</para>
<para>

The requirement is a properly installed jsCalendar script. All browsers
supported by jsCalendar are supported by this extension.

</para>
<para>

This extension enables the display of a popup calendar selection against
selected fields. In order to use it, you should:

<orderedlist>

<listitem>
<para>

Load the jsCalendar scripts in the &lt;head&gt;...&lt;/head&gt; section of
your &name; calling program, substituting the correct paths:

<example><title>CalPopup javascript</title>
<programlisting><![CDATA[
<script type="text/javascript" src="js/calendar.js"></script>
<script type="text/javascript" src="js/lang/calendar-en.js"></script>
<script type="text/javascript" src="js/calendar-setup.js"></script>
]]></programlisting>
</example>

</para>
</listitem>

<listitem>
<para>

Choose your preferred jsCalendar CSS file (see jsCalendar documentation) and
add the following in the &lt;head&gt;...&lt;/head&gt; section of your
&name; calling program, substituting the correct path:
  
<example><title>CalPopup javascript</title>
<programlisting><![CDATA[
<link rel="stylesheet" type="text/css" media="screen"
        href="css/calendar-system.css">
]]></programlisting>
</example>

</para>
<note><para>

To avoid an unwanted side effect in the CSS style produced by
<filename>phpMyEditSetup.php</filename>, add a 'width:auto' property into the
'.calendar table' entry in your selected jsCalendar style sheet.

</para></note>

</listitem>
<listitem>
<para>

Call to <filename>&name;-calpopup.class.php</> instead of
<filename>&name;.class.php</>.

<example><title>CalPopup extension enabling</title>
<programlisting>
require_once 'extensions/&name;-calpopup.class.php';
new &name;_calpopup($opts);
</programlisting>
</example>

</para>
</listitem>
    
<listitem>
<para>

Add <varname>calendar</varname> parameter to the field definitions where you
want a calendar popup in your &name; calling program.

<example><title>CalPopup field enabling</title>
<programlisting><![CDATA[
$opts['fdd']['col_name'] = array(
 'name'     => 'Column',
 'select'   => 'T',
 'options'  => 'ACPVD',
 'required' => true,
 'calendar' => true
);
]]></programlisting>
</example>

This is will display a button next to the field which pops up a calendar when
clicked. If that field has a <varname>strftimemask</varname> parameter set, it
will use this for the date format.

</para>
<para>
        
For more advanced usage, you can set the <varname>calendar</varname> parameter
to an array of valid jsCalendar <function>Calendar.setup</function> options
(see jSCalendar document for details). Note that not all of these options make
sense to use in &name;, and some of them will actively break the function.
        
<example><title>CalPopup advanced field</title>
<programlisting>
$opts['fdd']['col_name'] = array(
 'name'     => 'Column',
 'select'   => 'T',
 'options'  => 'ACPVD',
 'required' => true,
 'calendar' => array(
   'ifFormat'    => '%Y/%m/%d', // defaults to the ['strftimemask']
   'firstDay'    => 1,          // 0 = Sunday, 1 = Monday
   'singleClick' => true,       // single or double click to close
   'weekNumbers' => true,       // Show week numbers
   'showsTime'   => false,      // Show time as well as date
   'timeFormat'  => '24',       // 12 or 24 hour clock
   'label'       => '...',      // button label (used by &name;)
   'date'        => '2003-12-19 10:00' // Initial date/time for popup
                                       // (see notes below)
 )
);
</programlisting>
</example>

</para>
</listitem>
</orderedlist>

</para>
<para>

The popup will normally set the initial value to the current field value or to
current date/time. <varname>date</varname> option will always override this,
even if there is a current date/time value in the field. If you want a default
value only if the field is currently empty, use the &name;
<varname>default</varname> option.

</para>
<para>

Only the options listed above may be set by the user, any other options will
be ignored.

</para>
<para>

This extension is contribution of Adam Hammond
<email>ajh@phpmyedit.org</email> from London.

</para>
</sect1>

<sect1 id="extensions.mce-cal">
<title id="extensions.mce-cal.title">&name;-mce-cal</title>
<para>

&name;-mce-cal is a merge of HTML textarea and calendar popup extensions. This
extension should be used instead of &name;-htmlarea and &name;-calpopup
extensions. See&nbsp;extension source code comments for full documentation.

</para>
<para>

To use this extension you have to include
<filename>extensions/&name;-mce-cal.class.php</filename> file and call
<varname>new &name;_mce_cal($opts)</varname> instead of common &name; class
file.

</para>
<para>

This extension is again contribution of Adam Hammond
<email>ajh@phpmyedit.org</email> from London.

</para>
</sect1>
</chapter>