Added JPGraph v3.5.0b1

This commit is contained in:
Deon George 2011-05-28 19:51:52 +10:00
parent 8b685a84dd
commit 21b013e3ba
2452 changed files with 173844 additions and 0 deletions

66
includes/jpgraph/README Normal file
View File

@ -0,0 +1,66 @@
README FOR JPGRAPH 3.5.x
=========================
This package contains the JpGraph PHP library Pro version 3.5.x
The library is Copyright (C) 2000-2010 Asial Corporatoin and
released under dual license QPL 1.0 for open source and educational
use and JpGraph Professional License for commercial use.
Please see full license details at
http://jpgraph.net/pro/
http://jpgraph.net/download/
* --------------------------------------------------------------------
* PHP4 IS NOT SUPPORTED IN 2.x or 3.x SERIES
* --------------------------------------------------------------------
Requirements:
-------------
Miminum:
* PHP 5.1.0 or higher
* GD 2.0.28 or higher
Note: Earlier versions might work but is unsupported.
Recommended:
* >= PHP 5.2.0
* PHP Builtin GD library
Installation
------------
1. Make sure that the PHP version is compatible with the stated
requirements and that the PHP installation has support for
the GD library. Please run phpinfo() to check if GD library
is supported in the installation.
If the GD library doesn't seem to be installed
please consult the PHP manual under section "Image" for
instructions on where to find this library. Please refer to
the manual section "Verifying your PHP installation"
2. Unzip and copy the files to a directory of your choice where Your
httpd sever can access them.
For a global site installation you should copy the files to
somewhere in the PHP search path.
3. Check that the default directory paths in jpg-config.inc.php
for cache directory and TTF directory suits your installation.
Note1: The default directories are different depending on if
the library is running on Windows or UNIX.
Note2: Apache/PHP must have write permission to your cache
directory if you enable the cache feature. By default the cache
is disabled.
Documentation
-------------
The installation includes HTML documentation and reference guide for the
library. The portal page for all documentation is
<YOUR-INSTALLATION-DIRECTORY>/docs/index.html
Bug reports and suggestions
---------------------------
Should be reported using the contact form at
http://jpgraph.net/contact/

1
includes/jpgraph/VERSION Normal file
View File

@ -0,0 +1 @@
Version: v3.5.0b1

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.9 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 7.6 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.1 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.9 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.7 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.4 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.9 KiB

View File

@ -0,0 +1,117 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Appendix A. How this manual was produced</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt09.html" title="Part IX. Appendices"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix A. How this manual was produced</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part IX. Appendices</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="appendix" title="Appendix A. How this manual was produced"><div class="titlepage"><div><div><h2 class="title"><a name="app.how-was-this-manual-produced"></a>Appendix A. How this manual was produced</h2></div></div></div>
<p>Unfortunately we couldn't locate any off-the-shelf system for producing this fairly
large manual with some special requirements like automatic inclusion of PHP source that
should be highlighted and in addition rendered by running the scripts and automatically
include the resulting images in the resulting manual. To solve this we have based our
solution around a DocBook5 setup with some custom steps that are described below.</p>
<p><span class="bold"><strong>DocBook5</strong></span></p>
<p>The source for the manual is written as a number of split <code class="uri"><a class="uri" href="http://www.docbook.org/" target="_top">DocBook5</a></code> XML compliant documents using
<code class="uri"><a class="uri" href="http://www.w3.org/TR/xinclude/" target="_top">XInclude</a></code> to bring them
together into one master document. </p>
<p>The transformation of the XML source files was done by the means of a DocBook XSL
stylesheet using the <span class="command"><strong>xsltproc</strong></span> XSL processor. (see <code class="uri"><a class="uri" href="http://xmlsoft.org/XSLT/xsltproc2.html" target="_top">libxslt</a></code>) The DocBook5
style sheets can directly produce either single file HTML or chunked (many files) HTML
(or XHTML). </p>
<p>In addition there is a style sheet to produce FO (Formatted Objects) output which can
be further refined to PDF with the help of the <span class="command"><strong>fop</strong></span> processor (see
<code class="uri"><a class="uri" href="http://xmlgraphics.apache.org/fop/" target="_top">Apache FOP</a></code>).
Unfortunately some formatting instructions in the source are lost in the transformation
to PDF output. This means that some aspects of the manual doesn't come out perfect in
the PDF output. For this reason the PDF version of the documentation should only be seen
as a complementary documentation. The master output format is the chunked HTML.</p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>In formatting the chunked output we have prioritized to keep down the number
of files to avoid many pages with only a small amount of text on them. Our view
is that documentation which breaks the pages down to very low levels are
extremely tiresome to read.</p>
</div><p>
</p>
<p><span class="bold"><strong>Phing based build system</strong></span></p>
<p>The overall build process is drive by a <span class="command"><strong>Phing</strong></span> XML build script.
<span class="command"><strong>Phing</strong></span> (See <code class="uri"><a class="uri" href="http://phing.info/trac/" target="_top">http://phing.info/trac/</a></code> ) is most easily described as a PHP version of the
Java build system <span class="command"><strong>Ant</strong></span>. It has several advantages compared with a more
traditional <span class="command"><strong>make</strong></span> setup, the build files are all written in clear XML
which makes them easy to read and maintain. In addition there are a number of built-in
commands that makes deploying and handling of files extremely easy compared with a
traditional make system which must rely on external tools to do everything. </p>
<p><span class="bold"><strong>Syntax highlighting of example code</strong></span></p>
<p>The syntax highlighting and handling of the numerous example images initially posed a
small problem since there are no off-the-shelf good support for handling this. As a
basic requirement we needed all PHP scripts to be runnable and kept in the normal
example directories and then automatically included when the DocBook source was
processed. </p>
<p>What was needed was some easy way by which we could just mark in the DocBook source
(and still maintain valid DocBook XML) that we wanted a particular named example
included and either show just the image, just the source or both. In addition we
required the source to be syntax highlighted. </p>
<p>To handle this we had to write some custom tasks to extend Phing. In principal our
build system works as follows.</p>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>When a new example have been added or an old one removed a special target in
our build file are run which extracts all scripts from the example sections in
the *.XML files. The name of each found example script in the XML source
corresponds to an existing PHP script in the Example directory in the JpGraph
distribution. A batch file is then automatically created which is subsequently
run and all generated images stored on disk.</p>
</li><li class="listitem">
<p>When the normal DocBook XSL processing is done all the special example markups
in the XML source is replaced with XML tags to include the image and make sure
that the referred script is a proper PHP file name.</p>
</li><li class="listitem">
<p>After the XSL process has been run all programlisting tags will have a special
token, for example "<code class="code">\#\#example0.php\#\#</code>" this then instructs a
custom <span class="command"><strong>Phing</strong></span> task to replace the name in the double "#" tags
with the corresponding source (in the resulting HTML code). At the same time
this source is included it is also passed through the custom syntax highlight
filter so that it comes out as proper marked up source which is inserted
directly in the resulting HTML file.</p>
</li></ol></div>
<p>The overall build system is illustrated in <a class="xref" href="apa.html#fig.documentation-build-system" title="Figure A.1. The documentation build process">Figure A.1. The documentation build process</a></p>
<div class="figure"><a name="fig.documentation-build-system"></a><p class="title"><b>Figure A.1. The documentation build process</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/documentation_buildprocess.png" alt="The documentation build process"></div>
</div></div><br class="figure-break">
<p>The way the special markup works is that whenever we want a full example (source and
image) we create a &lt;programlisting&gt; tag with the file name and title within (single)
"#" characters. For example to include the very first example in this manual we have the
following tags in the docbook XML source</p>
<p>
</p><pre class="screen">&lt;programlisting&gt;#example0|The very first example#&lt;/programlisting&gt;</pre><p>
</p>
<p>The first part (before the "|") is the file name without extension that we want to
include and the second part (after the "|") is the title we want to use. This markup
will include both the source as well as the generated graph/image directly in the
resulting HTML.</p>
<p>When new examples have been added the examples target in our build file is run and
that extracts all the example script used in the book (in the above example
"<code class="code">example0.php</code>") and creates a batch file which is then run to create
all the images used in the examples. </p>
<p>The syntax highlighting is handled by a custom written filter extensions to
<span class="command"><strong>Phing</strong></span> which internally uses the PEAR package
<code class="filename">Pear::Text_Highlight</code>.</p>
<p><span class="bold"><strong>Notes:</strong></span></p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>In the current setup a regular expression in the Phing build script is
responsible for replacing the markup in the programlisting with a
&lt;figure&gt; tag and a new &lt;programlisting&gt;. This should be done with a
custom XSL layer instead and we will update this for the next major
revision.</p>
</li><li class="listitem">
<p>Since the syntax highlighting makes use of HTML markup code for the colors
the PDF output does not support syntax highlighting</p>
</li><li class="listitem">
<p>For the reference manual we still use our old DB based documentation
system which stores all the methods and classes in a DB augmented with
source documentation. (We actually prefer this in front of adding a lot of
end user documentation with PHPDoc comment sin the source which have a
tendency of cluttering up the code as well as making it prone to error since
the source files have to be modified in order to update a simple typo in the
documentations. Our next step is therefor to update that old system to be
able to produce DocBook5 compliant XML for further formatting and
processing.</p>
</li></ol></div><p>
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt09.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,73 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Appendix B. JpGraph Professional License</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt09.html" title="Part IX. Appendices"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix B. JpGraph Professional License</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part IX. Appendices</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="appendix" title="Appendix B. JpGraph Professional License"><div class="titlepage"><div><div><h2 class="title"><a name="app.jpg-license"></a>Appendix B. JpGraph Professional License</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="apb.html#id2622757">B.1. Single License</a></span></dt><dt><span class="section"><a href="apbs02.html">B.2. Bulk (Re-seller license)</a></span></dt></dl></div>
<div class="section" title="Single License"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2622757"></a>Single License</h2></div></div></div>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>The JpGraph Professional License will be referred to as "The license" in the
remainder of this text.</p>
</li><li class="listitem">
<p>This irrevocable, perpetual license covers versions 1.x &amp; 2.x of
JpGraph</p>
</li><li class="listitem">
<p>This license gives the holder right to install JpGraph libraries on One Server
which can run one or several virtual HTTP servers.</p>
</li><li class="listitem">
<p>The license holder is allowed to make modifications to the JpGraph sources but
in no event will the original copyright holders of this library be held
responsible for action or actions resulting from any modifications of the
source.</p>
</li><li class="listitem">
<p>The license holder is not required to publicize or otherwise make available
any software used in conjunction with JpGraph.</p>
</li><li class="listitem">
<p>The license holder may not re-distribute the library on it's own or versions
thereof to third party without prior written permission of the copyright
holder.</p>
</li><li class="listitem">
<p>JpGraph License does not allow the library to be redistributed as part of
another product.</p>
</li><li class="listitem">
<p>In no event shall the copyright notice in any of the source files supplied in
JpGraph be removed or modified.</p>
</li><li class="listitem">
<p>The names "JpGraph" or "Aditus" must not be used to endorse or promote
products derived from this software without prior written permission.</p>
</li><li class="listitem">
<p>The license may be transferred to another server by removing all installed
files from the old server.</p>
</li><li class="listitem">
<p>The wording of this license may change without notice for future versions of
JpGraph.</p>
</li><li class="listitem">
<p>By acquiring a license the licensee agrees to all terms and conditions in this
license text.</p>
</li><li class="listitem">
<p><span class="bold"><strong>Limitations of Liability</strong></span></p>
<p>In no event, except for intellectual property claim, shall the initial
developers or copyright holders be liable for any damages whatsoever, including
- but not restricted to - lost revenue or profits or other direct, indirect,
special, incidental or consequential damages, even if they have been advised of
the possibility of such damages, except to the extent invariable law, if any,
provides otherwise.</p>
<p>In addition, in no event does this license authorize you to use JpGraph in
applications or systems where JpGraphs failure to perform can reasonably be
expected to result in a physical injury, loss of life or any economical damage.
Any such use by the licensee is entirely at the licensees own risk, and the
licensee agrees to hold the original copyright holders of JpGraph harmless from
any claims or losses relating to any such unauthorized use.</p>
</li><li class="listitem">
<p><span class="bold"><strong>Limited Warranty</strong></span></p>
<p>JpGraph warrants that licensor is owner of the software with authority to
license the software to licensee and that the software does not infringe third
party intellectual property rights. Licensor agrees to indemnify, defend and
hold harmless licensee from any claims either that licensor does not own the
software or that the software infringes a third party's intellectual
property.</p>
<p>THE SOFTWARE AND THIS LICENSE DOCUMENT ARE PROVIDED AS IS. THE FOREGOING
WARRANTY IS IN LIEU OF ALL OTHER WARRANTIES, EXPRESS OR IMPLIED, OF ANY KIND,
INCLUDING WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.</p>
</li></ol></div>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt09.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,64 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Bulk (Re-seller license)</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="apb.html" title="Appendix B. JpGraph Professional License"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Bulk (Re-seller license)</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Appendix B. JpGraph Professional License</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="section" title="Bulk (Re-seller license)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2622882"></a>Bulk (Re-seller license)</h2></div></div></div>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>The JpGraph Professional License will be referred to as "The license" in the
remainder of this text.</p>
</li><li class="listitem">
<p>This irrevocable, perpetual license covers versions 1.x &amp; 2.x of
JpGraph</p>
</li><li class="listitem">
<p>This license gives the licensee the right to distribute the JpGraph libraries,
as part of its product portfolio and to use the Jpgraph libraries with its
hosted service offerings. Specifically this license gives the licensee the right
to deploy an unlimited number of JpGraph installations as part of their product
portfolio and offer an unlimited number of hosted services that use the JpGraph
libraries to an unlimited number of users.</p>
</li><li class="listitem">
<p>The license holder is allowed to make modifications to the JpGraph sources but
in no event will the original copyright holders of this library be held
responsible for action or actions resulting from any modifications of the
source.</p>
</li><li class="listitem">
<p>JpGraph libraries is only licensed to be redistributed as a part of the
licensees products. Specifically it may not be sold or re-distributed on it's
own.</p>
</li><li class="listitem">
<p>In no event shall the copyright notice in any of the source files supplied in
JpGraph be removed or modified.</p>
</li><li class="listitem">
<p>The names "JpGraph" or "Aditus" must not be used to endorse or promote
products derived from this software without prior written permission.</p>
</li><li class="listitem">
<p>The wording of this license may change without notice for future versions of
JpGraph.</p>
</li><li class="listitem">
<p>By acquiring a license the licensee agrees to all terms and conditions in this
license text.</p>
</li><li class="listitem">
<p><span class="bold"><strong>Limitations of Liability</strong></span></p>
<p>In no event, except for intellectual property claim, shall the initial
developers or copyright holders be liable for any damages whatsoever, including
- but not restricted to - lost revenue or profits or other direct, indirect,
special, incidental or consequential damages, even if they have been advised of
the possibility of such damages, except to the extent invariable law, if any,
provides otherwise.</p>
<p>In addition, in no event does this license authorize you to use JpGraph in
applications or systems where JpGraphs failure to perform can reasonably be
expected to result in a physical injury, loss of life or any economical damage.
Any such use by the licensee is entirely at the licensees own risk, and the
licensee agrees to hold the original copyright holders of JpGraph harmless from
any claims or losses relating to any such unauthorized use.</p>
</li><li class="listitem">
<p><span class="bold"><strong>Limited Warranty</strong></span></p>
<p>JpGraph warrants that licensor is owner of the software with authority to
license the software to licensee and that the software does not infringe third
party intellectual property rights. Licensor agrees to indemnify, defend and
hold harmless licensee from any claims either that licensor does not own the
software or that the software infringes a third party's intellectual
property.</p>
<p>THE SOFTWARE AND THIS LICENSE DOCUMENT ARE PROVIDED AS IS. THE FOREGOING
WARRANTY IS IN LIEU OF ALL OTHER WARRANTIES, EXPRESS OR IMPLIED, OF ANY KIND,
INCLUDING WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.</p>
</li></ol></div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="apb.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

File diff suppressed because it is too large Load Diff

File diff suppressed because one or more lines are too long

View File

@ -0,0 +1,78 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Appendix E. Available plot marks</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt09.html" title="Part IX. Appendices"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix E. Available plot marks</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part IX. Appendices</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="appendix" title="Appendix E. Available plot marks"><div class="titlepage"><div><div><h2 class="title"><a name="app.plotmark-list"></a>Appendix E. Available plot marks</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ape.html#id2637042">E.1. Built in basic plot marks</a></span></dt><dt><span class="sect1"><a href="apes02.html">E.2. Built in image plot marks</a></span></dt><dd><dl><dt><span class="sect2"><a href="apes02.html#id2637416">E.2.1. Image plot mark: Balls</a></span></dt><dt><span class="sect2"><a href="apes02.html#id2637440">E.2.2. Image plot mark: Squares</a></span></dt><dt><span class="sect2"><a href="apes02.html#id2637462">E.2.3. Image plot mark: Diamonds</a></span></dt><dt><span class="sect2"><a href="apes02.html#id2637510">E.2.4. Image plot mark: Stars</a></span></dt><dt><span class="sect2"><a href="apes02.html#id2637511">E.2.5. Image plot mark: Bevels</a></span></dt><dt><span class="sect2"><a href="apes02.html#id2637592">E.2.6. Image plot mark: Pushpins</a></span></dt></dl></dd></dl></div>
<p> Plot marks can be added to almost all linear (cartesian) graph types. They are used to
emphasise the actual data points in the graph. The plot mark property is available as the
instance variable "<code class="code">$mark</code>" for the plot types that support plot marks. </p>
<div class="sect1" title="Built in basic plot marks"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2637042"></a>Built in basic plot marks</h2></div></div></div>
<p>To embellishment a line plot with one of the built-in basic plot marks, say a a red
diamond mark, at each data point the following line has to be added to the graph
script</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-var">$lineplot</span><span class="hl-code">-&gt;</span><span class="hl-identifier">mark</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetType</span><span class="hl-brackets">(</span><span class="hl-identifier">MARK_DIAMOND</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$lineplot</span><span class="hl-code">-&gt;</span><span class="hl-identifier">mark</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetFillColor</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">red</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div><p>
</p>
<p>The rest of the basic plot marks are handled analogues.</p>
<p>
</p><div class="table"><a name="tab.built-in-plotmarks"></a><p class="title"><b>Table E.1. Built in line based plot marks</b></p><div class="table-contents">
<table summary="Built in line based plot marks" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"></colgroup><thead><tr><th align="center">Displayed plot mark</th><th align="center">Symbolic name</th></tr></thead><tbody><tr><td align="center">
<p><span class="inlinemediaobject"><img src="images/img_marker_square.png"></span></p>
</td><td align="center">
<p><code class="code">MARK_SQUARE</code></p>
</td></tr><tr><td align="center">
<p><span class="inlinemediaobject"><img src="images/img_marker_utriangle.png"></span></p>
</td><td align="center">
<p><code class="code">MARK_UTRIANGLE</code></p>
</td></tr><tr><td align="center">
<p><span class="inlinemediaobject"><img src="images/img_marker_dtriangle.png"></span></p>
</td><td align="center">
<p><code class="code">MARK_DTRIANGLE</code></p>
</td></tr><tr><td align="center">
<p><span class="inlinemediaobject"><img src="images/img_marker_diamond.png"></span></p>
</td><td align="center">
<p><code class="code">MARK_DIAMOND</code></p>
</td></tr><tr><td align="center">
<p><span class="inlinemediaobject"><img src="images/img_marker_circle.png"></span></p>
</td><td align="center">
<p><code class="code">MARK_CIRCLE</code></p>
</td></tr><tr><td align="center">
<p><span class="inlinemediaobject"><img src="images/img_marker_filledcircle.png"></span></p>
</td><td align="center">
<p><code class="code">MARK_FILLEDCIRCLE</code></p>
</td></tr><tr><td align="center">
<p><span class="inlinemediaobject"><img src="images/img_marker_cross.png"></span></p>
</td><td align="center">
<p><code class="code">MARK_CROSS</code></p>
</td></tr><tr><td align="center">
<p><span class="inlinemediaobject"><img src="images/img_marker_star.png"></span></p>
</td><td align="center">
<p><code class="code">MARK_STAR</code></p>
</td></tr><tr><td align="center">
<p><span class="inlinemediaobject"><img src="images/img_marker_x.png"></span></p>
</td><td align="center">
<p><code class="code">MARK_X</code></p>
</td></tr><tr><td align="center">
<p><span class="inlinemediaobject"><img src="images/img_marker_lefttriangle.png"></span></p>
</td><td align="center">
<p><code class="code">MARK_LEFTTRIANGLE</code></p>
</td></tr><tr><td align="center">
<p><span class="inlinemediaobject"><img src="images/img_marker_righttriangle.png"></span></p>
</td><td align="center">
<p><code class="code">MARK_RIGHTTRIANGLE</code></p>
</td></tr><tr><td align="center">
<p><span class="inlinemediaobject"><img src="images/img_marker_flash.png"></span></p>
</td><td align="center">
<p><code class="code">MARK_FLASH</code></p>
</td></tr></tbody></table>
</div></div><p><br class="table-break">
</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt09.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,88 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Built in image plot marks</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ape.html" title="Appendix E. Available plot marks"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Built in image plot marks</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Appendix E. Available plot marks</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Built in image plot marks"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2637370"></a>Built in image plot marks</h2></div></div></div>
<p>Since the image based plot marks only supports some colors (since there has to be a
unique image for each color) the following sections shows for each major image plot mark
what colors are available. The image shows the natural size of the plot mark, i.e. the
scale factor is =1. Only the round balls ar available natively in three different sizes.
Even though it is possible to scale up all the images arbitrarily it will cause the
images to become pixelated.</p>
<p>To use one of the built in image plot mark two parameters has to be given to the
<code class="code">SetType()</code> method. The basic class of plot mark and the wanted color.
For example to use a green square as plot marks the following line would have to be
added</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-var">$lineplot</span><span class="hl-code">-&gt;</span><span class="hl-identifier">mark</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetType</span><span class="hl-brackets">(</span><span class="hl-identifier">MARK_IMG_SQUARE</span><span class="hl-code">,</span><span class="hl-quotes">'</span><span class="hl-string">green</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div><p>
</p>
<p>If a non-supported color is specified an error will be thrown.</p>
<div class="sect2" title="Image plot mark: Balls"><div class="titlepage"><div><div><h3 class="title"><a name="id2637416"></a>Image plot mark: Balls</h3></div></div></div>
<p>
</p><div class="figure"><a name="id2637423"></a><p class="title"><b>Figure E.1. Small size</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/plotmark_colors_img_sball.png" alt="Small size"></div>
</div></div><p><br class="figure-break">
</p>
<p>
</p><div class="figure"><a name="id2637447"></a><p class="title"><b>Figure E.2. Medium size</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/plotmark_colors_img_mball.png" alt="Medium size"></div>
</div></div><p><br class="figure-break">
</p>
<p>
</p><div class="figure"><a name="id2637469"></a><p class="title"><b>Figure E.3. Large size</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/plotmark_colors_img_lball.png" alt="Large size"></div>
</div></div><p><br class="figure-break">
</p>
</div>
<div class="sect2" title="Image plot mark: Squares"><div class="titlepage"><div><div><h3 class="title"><a name="id2637440"></a>Image plot mark: Squares</h3></div></div></div>
<p>
</p><div class="figure"><a name="id2637499"></a><p class="title"><b>Figure E.4. Standard size</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/plotmark_colors_img_square.png" alt="Standard size"></div>
</div></div><p><br class="figure-break">
</p>
</div>
<div class="sect2" title="Image plot mark: Diamonds"><div class="titlepage"><div><div><h3 class="title"><a name="id2637462"></a>Image plot mark: Diamonds</h3></div></div></div>
<p>
</p><div class="figure"><a name="id2637525"></a><p class="title"><b>Figure E.5. Standard size</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/plotmark_colors_img_diamond.png" alt="Standard size"></div>
</div></div><p><br class="figure-break">
</p>
</div>
<div class="sect2" title="Image plot mark: Stars"><div class="titlepage"><div><div><h3 class="title"><a name="id2637510"></a>Image plot mark: Stars</h3></div></div></div>
<p>
</p><div class="figure"><a name="id2637554"></a><p class="title"><b>Figure E.6. Standard size</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/plotmark_colors_img_star.png" alt="Standard size"></div>
</div></div><p><br class="figure-break">
</p>
</div>
<div class="sect2" title="Image plot mark: Bevels"><div class="titlepage"><div><div><h3 class="title"><a name="id2637511"></a>Image plot mark: Bevels</h3></div></div></div>
<p>
</p><div class="figure"><a name="id2637582"></a><p class="title"><b>Figure E.7. Standard size</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/plotmark_colors_img_bevel.png" alt="Standard size"></div>
</div></div><p><br class="figure-break">
</p>
</div>
<div class="sect2" title="Image plot mark: Pushpins"><div class="titlepage"><div><div><h3 class="title"><a name="id2637592"></a>Image plot mark: Pushpins</h3></div></div></div>
<p>
</p><div class="figure"><a name="id2637570"></a><p class="title"><b>Figure E.8. Standard size</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/plotmark_colors_img_pushpin.png" alt="Standard size"></div>
</div></div><p><br class="figure-break">
</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ape.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

File diff suppressed because one or more lines are too long

View File

@ -0,0 +1,201 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Appendix G. List of files included in the library</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt09.html" title="Part IX. Appendices"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix G. List of files included in the library</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part IX. Appendices</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="appendix" title="Appendix G. List of files included in the library"><div class="titlepage"><div><div><h2 class="title"><a name="id2645472"></a>Appendix G. List of files included in the library</h2></div></div></div>
<p>In the distribution these files are stored directly under the src directory in the
distribution. </p>
<p>In the pro-version of the library there are also two alternative directories which
contains variations of the core <code class="filename">src</code> directory. These additional
directories are:</p>
<p>
</p><div class="variablelist"><dl><dt><span class="term">stripped-src</span></dt><dd>
<p>These file are suitable to be deployed on a production server. No examples
or demo applications are included here and in addition all files have white
spaces and comments stripped which makes them significantly smaller and
hence reduce the load time of the files on a productions server.</p>
</dd><dt><span class="term">phpExpress-src</span></dt><dd>
<p>These files are intended to be used with the PHP Accelerator from
NuSpehere. This accelerometer can be downloaded free of charge from <code class="uri"><a class="uri" href="http://www.nusphere.com" target="_top">NuSphere corporation</a></code>. For a
production server this is the recommended installation since it
significantly reduces the load on the production server. See <a class="xref" href="ch11.html" title="Chapter 11. NuSphere PHP accelerator">Chapter 11. <i>NuSphere PHP accelerator</i></a> for information on how to install
the freely available PHP Accelerator.</p>
</dd></dl></div><p>
</p>
<div class="table"><a name="id2645503"></a><p class="title"><b>Table G.1. List of files included in the library</b></p><div class="table-contents">
<table summary="List of files included in the library" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><thead><tr><th>File name</th><th>Only Pro Version </th><th>Description</th></tr></thead><tbody><tr><td>
<code class="filename">flags.dat</code>
</td><td>
</td><td>Raw data for country flag in maximum size</td></tr><tr><td>
<code class="filename">flags_thumb100x100.dat</code>
</td><td>
</td><td>Raw data for country flag in size 100x100</td></tr><tr><td>
<code class="filename">flags_thumb35x35.dat</code>
</td><td>
</td><td>Raw data for country flag in size 35x35</td></tr><tr><td>
<code class="filename">flags_thumb60x60.dat</code>
</td><td>
</td><td>Raw data for country flag in size 60x60</td></tr><tr><td>
<code class="filename">gd_image.inc.php</code>
</td><td>
</td><td>Interface classes to the low level GD library</td></tr><tr><td>
<code class="filename">imgdata_balls.inc.php</code>
</td><td>
</td><td>Stored image data for marker images</td></tr><tr><td>
<code class="filename">imgdata_bevels.inc.php</code>
</td><td>
</td><td>Stored image data for marker images</td></tr><tr><td>
<code class="filename">imgdata_diamonds.inc.php</code>
</td><td>
</td><td>Stored image data for marker images</td></tr><tr><td>
<code class="filename">imgdata_pushpins.inc.php</code>
</td><td>
</td><td>Stored image data for marker images</td></tr><tr><td>
<code class="filename">imgdata_squares.inc.php</code>
</td><td>
</td><td>Stored image data for marker images</td></tr><tr><td>
<code class="filename">imgdata_stars.inc.php</code>
</td><td>
</td><td>Stored image data for marker images</td></tr><tr><td>
<code class="filename">jpg-config.inc.php</code>
</td><td>
</td><td>Configuration file for the library</td></tr><tr><td>
<code class="filename">jpgraph_antispam-digits.php</code>
</td><td>
</td><td>Image data for CAPTCHA digits</td></tr><tr><td>
<code class="filename">jpgraph_antispam.php</code>
</td><td>
</td><td>Extension module: CAPTCHA figures</td></tr><tr><td>
<code class="filename">jpgraph_bar.php</code>
</td><td>
</td><td>Extension module: Bargraphs</td></tr><tr><td>
<code class="filename">jpgraph_canvas.php</code>
</td><td>
</td><td>Extension module: Canvas graphs</td></tr><tr><td>
<code class="filename">jpgraph_canvtools.php</code>
</td><td>
</td><td>Extension module: Tools for canvas graphs</td></tr><tr><td>
<code class="filename">jpgraph_date.php</code>
</td><td>
</td><td>Extension module: Date scale handling</td></tr><tr><td>
<code class="filename">jpgraph_errhandler.inc.php</code>
</td><td>
</td><td>Core module: Error handler</td></tr><tr><td>
<code class="filename">jpgraph_error.php</code>
</td><td>
</td><td>Extension module: Error plots</td></tr><tr><td>
<code class="filename">jpgraph_flags.php</code>
</td><td>
</td><td>Extension module: Country flags</td></tr><tr><td>
<code class="filename">jpgraph_gantt.php</code>
</td><td>
</td><td>Extension module: Gantt chart</td></tr><tr><td>
<code class="filename">jpgraph_gb2312.php</code>
</td><td>
</td><td>Extension module: GB2312 (Chinese) encoding</td></tr><tr><td>
<code class="filename">jpgraph_gradient.php</code>
</td><td>
</td><td>Extension module: Gradient fill</td></tr><tr><td>
<code class="filename">jpgraph_iconplot.php</code>
</td><td>
</td><td>Extension module: Icon images in plots</td></tr><tr><td>
<code class="filename">jpgraph_imgtrans.php</code>
</td><td>
</td><td>Extension module: Image transformation</td></tr><tr><td>
<code class="filename">jpgraph_led.php</code>
</td><td>
</td><td>Extension module: LED digits/numbers</td></tr><tr><td>
<code class="filename">jpgraph_legend.inc.php</code>
</td><td>
</td><td>Core module: Legend handling</td></tr><tr><td>
<code class="filename">jpgraph_line.php</code>
</td><td>
</td><td>Extension module: Line plot</td></tr><tr><td>
<code class="filename">jpgraph_log.php</code>
</td><td>
</td><td>Extension module: Log scale</td></tr><tr><td>
<code class="filename">jpgraph_mgraph.php</code>
</td><td>
</td><td>Extension module: Multigraph canvas</td></tr><tr><td>
<code class="filename">jpgraph.php</code>
</td><td>
</td><td>Core module: JpGraph core module</td></tr><tr><td>
<code class="filename">jpgraph_pie3d.php</code>
</td><td>
</td><td>Extension module: 3D Pie plot</td></tr><tr><td>
<code class="filename">jpgraph_pie.php</code>
</td><td>
</td><td>Extension module: 2D Pie plot</td></tr><tr><td>
<code class="filename">jpgraph_plotband.php</code>
</td><td>
</td><td>Extension module: Plot bands (filled areas in graphs)</td></tr><tr><td>
<code class="filename">jpgraph_plotmark.inc.php</code>
</td><td>
</td><td>Extension module: Plotmark for line plots</td></tr><tr><td>
<code class="filename">jpgraph_polar.php</code>
</td><td>
</td><td>Extension module: Polar plots</td></tr><tr><td>
<code class="filename">jpgraph_radar.php</code>
</td><td>
</td><td>Extension module:: Radar plot</td></tr><tr><td>
<code class="filename">jpgraph_regstat.php</code>
</td><td>
</td><td>Extension module: Spline and Bezier curves</td></tr><tr><td>
<code class="filename">jpgraph_rgb.inc.php</code>
</td><td>
</td><td>Core module: Color handling</td></tr><tr><td>
<code class="filename">jpgraph_scatter.php</code>
</td><td>
</td><td>Extension module:: Scatter plot</td></tr><tr><td>
<code class="filename">jpgraph_stock.php</code>
</td><td>
</td><td>Extension module:: Stock charts</td></tr><tr><td>
<code class="filename">jpgraph_text.inc.php</code>
</td><td>
</td><td>Core module: Text handling</td></tr><tr><td>
<code class="filename">jpgraph_ttf.inc.php</code>
</td><td>
</td><td>Core module: TTF font handling</td></tr><tr><td>
<code class="filename">jpgraph_utils.inc.php</code>
</td><td>
</td><td>Extension module:: Various utility classes</td></tr><tr><td>
<code class="filename">jpgraph_layout_vh.inc.php</code>
</td><td>
</td><td>Extension utility: classes for automatic layout classes</td></tr><tr><td>
<code class="filename">jpgraph_odo.php</code>
</td><td align="center">*</td><td>Extension module: Odometer plot</td></tr><tr><td>
<code class="filename">jpgraph_windrose.php</code>
</td><td align="center">*</td><td>Extension module:: Windrose plots</td></tr><tr><td>
<code class="filename">jpgraph_table.php</code>
</td><td align="center">*</td><td>Extension module:: Graphic tables</td></tr><tr><td>
<code class="filename">jpgraph_barcode.php</code>
</td><td align="center">*</td><td>Extension module: 1D Barcodes</td></tr><tr><td>
<code class="filename">jpgraph_matrix.php</code>
</td><td align="center">*</td><td>Extension module: Matrix plots</td></tr></tbody></table>
</div></div><br class="table-break">
<p>In addition to the files above the distribution contains the following directories</p>
<div class="table"><a name="id2645576"></a><p class="title"><b>Table G.2. List of subdirectories in main <code class="filename">src</code> directory</b></p><div class="table-contents">
<table summary="List of subdirectories in main src directory" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><thead><tr><th>Directory</th><th>Only Pro Version</th><th>Description</th></tr></thead><tbody><tr><td>
<code class="filename">Examples</code>
</td><td>
</td><td>JpGraph Example directory</td></tr><tr><td>
<code class="filename">lang</code>
</td><td>
</td><td>Localized error messages</td></tr><tr><td>
<code class="filename">barcode</code>
</td><td align="center">*</td><td>1D Barcodes</td></tr><tr><td>
<code class="filename">datamatrix</code>
</td><td align="center">*</td><td>2D Barcode Datamatrix directory</td></tr><tr><td>
<code class="filename">pdf417</code>
</td><td align="center">*</td><td>2D Barcode PDF417 directory</td></tr><tr><td>
<code class="filename">QR</code>
</td><td align="center">*</td><td>2D Barcode QR (Quick response) directory</td></tr><tr><td>
<code class="filename">table_examples</code>
</td><td align="center">*</td><td>Table examples</td></tr><tr><td>
<code class="filename">windrose_examples</code>
</td><td align="center">*</td><td>Windrose examples</td></tr><tr><td>
<code class="filename">odometer_examples</code>
</td><td align="center">*</td><td>Odometer examples</td></tr><tr><td>
<code class="filename">matrix_examples</code>
</td><td align="center">*</td><td>Matrix plot examples</td></tr></tbody></table>
</div></div><br class="table-break">
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt09.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

File diff suppressed because one or more lines are too long

View File

@ -0,0 +1,203 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>QR 2D Barcode error messages</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="aph.html" title="Appendix H. Error messages"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">QR 2D Barcode error messages</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Appendix H. Error messages</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="QR 2D Barcode error messages"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2652286"></a>QR 2D Barcode error messages</h2></div></div></div>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>These error messages are not yet localized</p>
</div><p>
</p>
<p>
</p><div class="table"><a name="id2646957"></a><p class="title"><b>Table H.2. English error messages</b></p><div class="table-contents">
<table summary="English error messages" border="0"><colgroup><col><col></colgroup><thead><tr><th> Error code </th><th> Error message </th></tr></thead><tbody><tr><td>
<code class="code">1000</code>
</td><td class="errmsg">Tilde processing is not yet supported for QR
Barcodes.</td></tr><tr><td>
<code class="code">1001</code>
</td><td class="errmsg">Inverting the bit pattern is not supported
for QR Barcodes.</td></tr><tr><td>
<code class="code">1002</code>
</td><td class="errmsg">Cannot read data from file %s</td></tr><tr><td>
<code class="code">1003</code>
</td><td class="errmsg">Cannot open file %s</td></tr><tr><td>
<code class="code">1004</code>
</td><td class="errmsg">Cannot write QR barcode to file %s</td></tr><tr><td>
<code class="code">1005</code>
</td><td class="errmsg">Unsupported image format selected. Check
your GD installation</td></tr><tr><td>
<code class="code">1006</code>
</td><td class="errmsg">Cannot set the selected barcode colors.
Check your GD installation and spelling of color
name</td></tr><tr><td>
<code class="code">1007</code>
</td><td class="errmsg">
<p>
<span class="bold"><strong>JpGraph Error: HTTP headers have
already been sent.</strong></span>
</p>
<p>Caused by output from file %s at line %d. </p>
<p>Explanation: HTTP headers have already been sent back
to the browser indicating the data as text before the
library got a chance to send it's image HTTP header to
this browser. </p>
<p>This makes it impossible for the library to send back
image data to the browser (since that would be
interpreted as text by the browser and show up as junk
text). Most likely you have some text in your script
before the call to Graph::Stroke(). If this texts gets
sent back to the browser the browser will assume that
all data is plain text. Look for any text, even spaces
and newlines, that might have been sent back to the
browser. For example it is a common mistake to leave a
blank line before the opening </p>
</td></tr><tr><td>
<code class="code">1008</code>
</td><td class="errmsg">Could not create the barcode image with
image format=%s. Check your GD/PHP installation.</td></tr><tr><td>
<code class="code">1009</code>
</td><td class="errmsg">Cannot open log file %s for writing.</td></tr><tr><td>
<code class="code">1010</code>
</td><td class="errmsg">Cannot write log info to log file
%s.</td></tr><tr><td>
<code class="code">1100</code>
</td><td class="errmsg">Internal error: Illegal mask pattern
selected</td></tr><tr><td>
<code class="code">1101</code>
</td><td class="errmsg">Internal error: Trying to apply masking to
functional pattern.</td></tr><tr><td>
<code class="code">1102</code>
</td><td class="errmsg">Internal error: applyMaskAndEval(): Found
uninitialized module in matrix when applying mask
pattern.</td></tr><tr><td>
<code class="code">1200</code>
</td><td class="errmsg">Internal error: Was expecting %d bits in
version %d to be placed in matrix but got %d bits</td></tr><tr><td>
<code class="code">1201</code>
</td><td class="errmsg">Internal error: Trying to position bit
outside the matrix x=%d, y=%d, size=%d, bIdx=%d</td></tr><tr><td>
<code class="code">1202</code>
</td><td class="errmsg">Internal error: Trying to put data in
initialized bit.</td></tr><tr><td>
<code class="code">1203</code>
</td><td class="errmsg">Internal error: Mask number for format bits
is invalid. (maskidx=%d)</td></tr><tr><td>
<code class="code">1204</code>
</td><td class="errmsg">Internal error: Found an uninitialized bit
[val=%d] at (%d,%d) when flattening matrix</td></tr><tr><td>
<code class="code">1300</code>
</td><td class="errmsg">Internal error: QRCapacity::getFormatBits()
Was expecting a format in range [0,31] got %d</td></tr><tr><td>
<code class="code">1301</code>
</td><td class="errmsg">Internal error: QRCapacity::getVersionBits()
Was expecting a version in range [7,40] got %d</td></tr><tr><td>
<code class="code">1302</code>
</td><td class="errmsg">Internal error: QRCapacity::_chkVerErr() Was
expecting version in range [1,40] and error level in range
[0,3] got (%d,%d)</td></tr><tr><td>
<code class="code">1303</code>
</td><td class="errmsg">Internal error:
QRCapacity::getAlignmentPositions() Expected %d patterns but
found %d patterns (len=%d).</td></tr><tr><td>
<code class="code">1304</code>
</td><td class="errmsg">Internal error: QRCapacity::%s Was expecting
a version in range [1,40] got %d</td></tr><tr><td>
<code class="code">1400</code>
</td><td class="errmsg">QR Version must be specified as a value in
the range [1,40] got %d</td></tr><tr><td>
<code class="code">1401</code>
</td><td class="errmsg">Input data to barcode can not be
empty.</td></tr><tr><td>
<code class="code">1402</code>
</td><td class="errmsg">Automatic encodation mode was specified but
input data looks like specification for manual
encodation.</td></tr><tr><td>
<code class="code">1403</code>
</td><td class="errmsg">Was expecting an array of arrays as input
data for manual encoding.</td></tr><tr><td>
<code class="code">1404</code>
</td><td class="errmsg">Each input data array element must consist
of two entries. Element $i has of $nn entries</td></tr><tr><td>
<code class="code">1405</code>
</td><td class="errmsg">Each input data array element must consist
of two entries with first entry being the encodation
constant and the second element the data string. Element %d
is incorrect in this respect.</td></tr><tr><td>
<code class="code">1406</code>
</td><td class="errmsg">Was expecting either a string or an array as
input data</td></tr><tr><td>
<code class="code">1407</code>
</td><td class="errmsg">Manual encodation mode was specified but
input data looks like specification for automatic
encodation.</td></tr><tr><td>
<code class="code">1408</code>
</td><td class="errmsg">Input data too large to fit into one QR
Symbol</td></tr><tr><td>
<code class="code">1409</code>
</td><td class="errmsg">The selected symbol version %d is too small
to fit the specified data and selected error correction
level.</td></tr><tr><td>
<code class="code">1410</code>
</td><td class="errmsg">Trying to read past the last available
codeword in block split.</td></tr><tr><td>
<code class="code">1411</code>
</td><td class="errmsg">Internal error: Expected 1 or 2 as the
number of block structures.</td></tr><tr><td>
<code class="code">1412</code>
</td><td class="errmsg">Internal error: Too many codewords for
chosen symbol version. (negative number of pad
codewords).</td></tr><tr><td>
<code class="code">1413</code>
</td><td class="errmsg">Internal error: splitInBytes: Expected an
even number of 8-bit blocks.</td></tr><tr><td>
<code class="code">1414</code>
</td><td class="errmsg">Internal error: getCountBits() illegal
version number (=%d).</td></tr><tr><td>
<code class="code">1415</code>
</td><td class="errmsg">Manually specified encodation schema
MODE_NUMERIC has no data that can be encoded using this
schema.</td></tr><tr><td>
<code class="code">1416</code>
</td><td class="errmsg">Manually specified encodation schema
MODE_ALPHANUM has no data that can be encoded using this
schema.</td></tr><tr><td>
<code class="code">1417</code>
</td><td class="errmsg">Manually specified encodation schema
MODE_BYTE has no data that can be encoded using this
schema.</td></tr><tr><td>
<code class="code">1418</code>
</td><td class="errmsg">Unsupported encodation schema specified
(%d)</td></tr><tr><td>
<code class="code">1419</code>
</td><td class="errmsg">Found character in data stream that cannot
be encoded with the selected manual encodation mode.</td></tr><tr><td>
<code class="code">1420</code>
</td><td class="errmsg">Encodation using KANJI mode not yet
supported.</td></tr><tr><td>
<code class="code">1421</code>
</td><td class="errmsg">Internal error: Unsupported encodation mode
doAuto().</td></tr><tr><td>
<code class="code">1422</code>
</td><td class="errmsg">Found unknown characters in the data stream
that can't be encoded with any available encodation
mode.</td></tr><tr><td>
<code class="code">1423</code>
</td><td class="errmsg">Kanji character set not yet
supported.</td></tr><tr><td>
<code class="code">1424</code>
</td><td class="errmsg">Internal error: DataStorage:: Unsupported
character mode (%d) DataStorage::Remaining()</td></tr><tr><td>
<code class="code">1425</code>
</td><td class="errmsg">Internal error: DataStorage:: Trying to
extract slice of len=%d (with type=%d) when there are only
%d elements left</td></tr><tr><td>
<code class="code">1426</code>
</td><td class="errmsg">Internal error: DataStorage:: Trying to read
past input data length.</td></tr><tr><td>
<code class="code">1427</code>
</td><td class="errmsg">Expected either DIGIT, ALNUM or BYTE but
found ASCII code=%d</td></tr><tr><td>
<code class="code">1428</code>
</td><td class="errmsg">Internal error: DataStorage::Peek() Trying
to peek past input data length.</td></tr></tbody></table>
</div></div><p><br class="table-break">
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="aph.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,121 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Datamatrix 2D barcode error messages</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="aph.html" title="Appendix H. Error messages"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Datamatrix 2D barcode error messages</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Appendix H. Error messages</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Datamatrix 2D barcode error messages"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2653261"></a>Datamatrix 2D barcode error messages</h2></div></div></div>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>These error messages are not yet localized</p>
</div><p>
</p>
<p>
</p><div class="table"><a name="id2653316"></a><p class="title"><b>Table H.3. English error messages</b></p><div class="table-contents">
<table summary="English error messages" border="0"><colgroup><col><col></colgroup><thead><tr><th> Error code </th><th> Error message </th></tr></thead><tbody><tr><td>
<code class="code">1</code>
</td><td class="errmsg">Data is too long to fit specified symbol
size</td></tr><tr><td>
<code class="code">2</code>
</td><td class="errmsg">The BASE256 data is too long to fit
available symbol size</td></tr><tr><td>
<code class="code">3</code>
</td><td class="errmsg">Data must have at least three characters for
C40 encodation</td></tr><tr><td>
<code class="code">4</code>
</td><td class="errmsg">Data must have at least three characters for
TEXT encodation</td></tr><tr><td>
<code class="code">5</code>
</td><td class="errmsg">Internal error: (-5) Trying to read source
data past the end</td></tr><tr><td>
<code class="code">6</code>
</td><td class="errmsg">Internal error: (-6) Trying to look ahead in
data past the end</td></tr><tr><td>
<code class="code">7</code>
</td><td class="errmsg">Internal error: (-7) Logic error in TEXT/C40
encodation (impossible branch)</td></tr><tr><td>
<code class="code">8</code>
</td><td class="errmsg">The given data can not be encoded using X12
encodation.</td></tr><tr><td>
<code class="code">9</code>
</td><td class="errmsg">The "tilde" encoded data is not
valid.</td></tr><tr><td>
<code class="code">10</code>
</td><td class="errmsg">Data must have at least three characters for
X12 encodation</td></tr><tr><td>
<code class="code">11</code>
</td><td class="errmsg">Specified data can not be encoded with
datamatrix 000 140</td></tr><tr><td>
<code class="code">12</code>
</td><td class="errmsg">Can not create image</td></tr><tr><td>
<code class="code">13</code>
</td><td class="errmsg">Invalid color specification</td></tr><tr><td>
<code class="code">14</code>
</td><td class="errmsg">Internal error: (-14) Index for 140 bit
placement matrix out of bounds</td></tr><tr><td>
<code class="code">15</code>
</td><td class="errmsg">This PHP installation does not support the
chosen image encoding format</td></tr><tr><td>
<code class="code">16</code>
</td><td class="errmsg">Internal error: (-16) Cannot instantiate
ReedSolomon</td></tr><tr><td>
<code class="code">20</code>
</td><td class="errmsg">The specification for shape of matrix is out
of bounds (0,29)</td></tr><tr><td>
<code class="code">21</code>
</td><td class="errmsg">Cannot open the data file specifying bit
placement for Datamatrix 200</td></tr><tr><td>
<code class="code">22</code>
</td><td class="errmsg">Datafile for bit placement is corrupt, crc
checks fails.</td></tr><tr><td>
<code class="code">23</code>
</td><td class="errmsg">Internal error: (-23) Output matrice is not
big enough for mapping matrice</td></tr><tr><td>
<code class="code">24</code>
</td><td class="errmsg">Internal error: (-24) Bit sequence to be
placed is too short for the chosen output matrice</td></tr><tr><td>
<code class="code">25</code>
</td><td class="errmsg">Internal error: (-25) Shape index out of
bounds for bit placement</td></tr><tr><td>
<code class="code">26</code>
</td><td class="errmsg">Cannot open the data file specifying bit
placement for Datamatrix 140</td></tr><tr><td>
<code class="code">30</code>
</td><td class="errmsg">The symbol size specified for ECC140 type
Datamatrix is not valid</td></tr><tr><td>
<code class="code">31</code>
</td><td class="errmsg">Data is to long to fit into any available
matrice size for datamatrix 140</td></tr><tr><td>
<code class="code">32</code>
</td><td class="errmsg">Internal error: (-32) Cannot instantiate
MasterRandom</td></tr><tr><td>
<code class="code">33</code>
</td><td class="errmsg">Internal error: (-33) Failed to randomize
140 bit stream</td></tr><tr><td>
<code class="code">34</code>
</td><td class="errmsg">Cannot open file %s for writing</td></tr><tr><td>
<code class="code">35</code>
</td><td class="errmsg">Cannot write to file %s </td></tr><tr><td>
<code class="code">99</code>
</td><td class="errmsg">EDIFACT encodation not implemented</td></tr><tr><td>
<code class="code">100</code>
</td><td class="errmsg">
<p>
<span class="bold"><strong>JpGraph Error: HTTP headers have
already been sent.</strong></span>
</p>
<p>Caused by output from file %s at line %d. </p>
<p>Explanation: HTTP headers have already been sent back
to the browser indicating the data as text before the
library got a chance to send it's image HTTP header to
this browser. </p>
<p>This makes it impossible for the library to send back
image data to the browser (since that would be
interpreted as text by the browser and show up as junk
text). Most likely you have some text in your script
before the call to Graph::Stroke(). If this texts gets
sent back to the browser the browser will assume that
all data is plain text. Look for any text, even spaces
and newlines, that might have been sent back to the
browser. For example it is a common mistake to leave a
blank line before the opening </p>
</td></tr></tbody></table>
</div></div><p><br class="table-break">
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="aph.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,126 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Appendix I. Compiling PHP</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt09.html" title="Part IX. Appendices"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix I. Compiling PHP</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part IX. Appendices</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="appendix" title="Appendix I. Compiling PHP"><div class="titlepage"><div><div><h2 class="title"><a name="app.compile-php"></a>Appendix I. Compiling PHP</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="api.html#id2654072">I.1. Compiling PHP4</a></span></dt><dd><dl><dt><span class="sect2"><a href="api.html#id2654077">I.1.1. Client version</a></span></dt><dt><span class="sect2"><a href="api.html#id2654090">I.1.2. Apache module</a></span></dt><dt><span class="sect2"><a href="api.html#id2654100">I.1.3. CGI extension</a></span></dt></dl></dd><dt><span class="sect1"><a href="apis02.html">I.2. Compiling PHP5</a></span></dt><dd><dl><dt><span class="sect2"><a href="apis02.html#id2654119">I.2.1. Client version</a></span></dt><dt><span class="sect2"><a href="apis02.html#id2654131">I.2.2. Apache module</a></span></dt><dt><span class="sect2"><a href="apis02.html#id2654142">I.2.3. CGI extension</a></span></dt></dl></dd></dl></div>
<p>Usually the included PHP version is adequate but if problems persists it is a good idea to
be able to compile PHP yourself. This way you will also be able to more quickly upgrade to
newer version of PHP which might have fix for a particular nasty bug that may have crept
in.</p>
<p> In the following sections we give examples of Unix shell scripts that will show typical
compile configuration for a downloaded PHP distribution. These compile configuration scripts
will make both the GD and FreeType libraries included in the executable. </p>
<p>In order to compile your downloaded PHP distribution first copy and save these scripts to
a local file and make that file runnable. Then run one of the selected configurations below
and do a normal "make". </p>
<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
<p>When running <code class="code">make</code> you can speed up the compilation by telling make to use
a number of parallel compile processes. Since most modern system have at least two cores
a typical invocation of make would be to make use of three parallel compile time
processes. This is done by using the <code class="code">-j</code> argument. For example as
</p><pre class="screen">make -j3</pre>
</div>
<p>It is possible to compile PHP into (at least) three variants </p>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>as a command line tool</p>
</li><li class="listitem">
<p>as a Apache extension module (this is probably the most common variant)</p>
</li><li class="listitem">
<p>as a CGI module to be used by a HTTP server (this is slower than running PHP
as a module since it needs to be read from disk and the process created every
time a PHP script needs to be executed.)</p>
</li></ol></div><p>There is one crucial difference of importance when using PHP to generate
images. Both the CGI module and the client variant are both standalone executables so what
is the difference? The crucial difference is that the CGI module will by default output a
MIME header before it outputs data while the client version will not. </p>
<p>The following sections have one compile script for each of the three major
versions.</p>
<div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3>
<p>You should make sure that the proposed directory paths in the scripts match your
particular server setup as this can vary from system to system. </p>
</div>
<div class="sect1" title="Compiling PHP4"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2654072"></a>Compiling PHP4</h2></div></div></div>
<div class="sect2" title="Client version"><div class="titlepage"><div><div><h3 class="title"><a name="id2654077"></a>Client version</h3></div></div></div>
<pre class="screen">#! /bin/sh
./configure --prefix=/usr/share --datadir=/usr/share/php \
--libdir=/usr/share/php --includedir=/usr/include \
--bindir=/usr/bin \
--with-config-file-path=/etc/php4/cli \
--with-config-file-scan-dir=/etc/php4/cli \
--enable-mbstring --enable-mbregex \
--with-mysql \
--with-gd --enable-gd-imgstrttf --enable-gd-native-ttf \
--with-zlib-dir=/usr/lib \
--with-png-dir=/usr/lib --with-jpeg-dir=/usr/lib --with-xpm-dir=/usr/X11R6 \
--with-tiff-dir=/usr/lib --with-ttf-dir=/usr/lib \
--with-freetype-dir=/usr/lib \
--enable-ftp \
--enable-memory-limit \
--enable-bcmath -enable-calendar \
--enable-ctype --with-ftp \
--enable-magic-quotes \
--enable-inline-optimization \
--with-bz2 \
--with-iconv
</pre>
</div>
<div class="sect2" title="Apache module"><div class="titlepage"><div><div><h3 class="title"><a name="id2654090"></a>Apache module</h3></div></div></div>
<pre class="screen">#! /bin/sh
./configure --prefix=/usr/share --datadir=/usr/share/php --with-apxs2=/usr/sbin/apxs2 \
--libdir=/usr/share --includedir=/usr/include \
--bindir=/usr/bin \
--with-config-file-path=/etc/php4/apache2 \
--enable-mbstring --enable-mbregex \
--with-mysql \
--with-gd --enable-gd-imgstrttf --enable-gd-native-ttf \
--with-zlib-dir=/usr/lib \
--with-png-dir=/usr/lib --with-jpeg-dir=/usr/lib --with-xpm-dir=/usr/X11R6 \
--with-tiff-dir=/usr/lib --with-ttf-dir=/usr/lib \
--with-freetype-dir=/usr/lib \
--enable-ftp \
--enable-memory-limit \
--bindir=/usr/bin \
--enable-bcmath \
--enable-calendar \
--enable-ctype \
--with-ftp \
--enable-magic-quotes \
--enable-inline-optimization \
--with-bz2 \
--with-iconv
</pre>
</div>
<div class="sect2" title="CGI extension"><div class="titlepage"><div><div><h3 class="title"><a name="id2654100"></a>CGI extension</h3></div></div></div>
<pre class="screen">#! /bin/sh
./configure --prefix=/usr/share --datadir=/usr/share/php \
--libdir=/usr/share --includedir=/usr/include \
--bindir=/usr/bin \
--with-config-file-path=/etc/php4/apache2 \
--with-config-file-scan=/etc/php4/apache2 \
--enable-mbstring --enable-mbregex \
--with-mysql \
--with-gd --enable-gd-imgstrttf --enable-gd-native-ttf \
--with-zlib-dir=/usr/lib \
--with-png-dir=/usr/lib --with-jpeg-dir=/usr/lib --with-xpm-dir=/usr/X11R6 \
--with-tiff-dir=/usr/lib --with-ttf-dir=/usr/lib \
--with-freetype-dir=/usr/lib \
--enable-ftp \
--enable-memory-limit \
--bindir=/usr/bin \
--enable-bcmath \
--enable-calendar \
--enable-ctype \
--with-ftp \
--enable-magic-quotes \
--enable-inline-optimization \
--with-bz2 \
--with-iconv
</pre>
</div>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt09.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,98 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Compiling PHP5</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="api.html" title="Appendix I. Compiling PHP"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Compiling PHP5</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Appendix I. Compiling PHP</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Compiling PHP5"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2654114"></a>Compiling PHP5</h2></div></div></div>
<div class="sect2" title="Client version"><div class="titlepage"><div><div><h3 class="title"><a name="id2654119"></a>Client version</h3></div></div></div>
<pre class="screen">#! /bin/sh
# mkphp5-cli
# Build a command line version of PHP5
./configure \
--prefix=/usr/share/php5 \
--datadir=/usr/share/php5 \
--libdir=/usr/share/php5 \
--includedir=/usr/include/php5 \
--enable-force-cgi-redirect \
--bindir=/usr/bin \
--with-config-file-path=/etc/php5/cli \
--with-config-file-scan-dir=/etc/php5/cli \
--enable-mbstring --enable-mbregex \
--with-mysql \
--with-gd --enable-gd-imgstrttf --enable-gd-native-ttf \
--with-zlib-dir=/usr/lib \
--with-png-dir=/usr/lib --with-jpeg-dir=/usr/lib --with-xpm-dir=/usr/X11R6 \
--with-tiff-dir=/usr/lib --with-ttf-dir=/usr/lib \
--with-freetype-dir=/usr/lib \
--enable-ftp \
--enable-memory-limit \
--enable-safe-mode \
--enable-bcmath -enable-calendar \
--enable-ctype \
--with-ftp \
--enable-magic-quotes \
--enable-inline-optimization \
--enable-tokenizer \
--with-bz2 \
--with-iconv \
--with-pear=/usr/share/php5
</pre>
</div>
<div class="sect2" title="Apache module"><div class="titlepage"><div><div><h3 class="title"><a name="id2654131"></a>Apache module</h3></div></div></div>
<pre class="screen">#! /bin/sh
# mkphp5-sapi
# Build a SAPI (Apache module) version of PHP5
./configure --prefix=/usr/share \
--datadir=/usr/share/php --with-apxs2=/usr/sbin/apxs2 \
--libdir=/usr/share --includedir=/usr/include \
--bindir=/usr/bin \
--with-config-file-path=/etc/php5/apache2 \
--enable-mbstring --enable-mbregex \
--with-mysql \
--with-gd --enable-gd-imgstrttf --enable-gd-native-ttf \
--with-zlib-dir=/usr/lib \
--with-png-dir=/usr/lib --with-jpeg-dir=/usr/lib --with-xpm-dir=/usr/X11R6 \
--with-tiff-dir=/usr/lib --with-ttf-dir=/usr/lib \
--with-freetype-dir=/usr/lib \
--enable-ftp \
--enable-memory-limit --enable-safe-mode \
--bindir=/usr/bin \
--enable-bcmath -enable-calendar \
--enable-ctype --with-ftp \
--enable-magic-quotes \
--enable-inline-optimization \
--with-bz2 \
--with-iconv
!#</pre>
</div>
<div class="sect2" title="CGI extension"><div class="titlepage"><div><div><h3 class="title"><a name="id2654142"></a>CGI extension</h3></div></div></div>
<pre class="screen">#! /bin/sh
# mkphp5-cgi
# Build a CGI version of PHP5
./configure --prefix=/usr/share \
--datadir=/usr/share/php \
--libdir=/usr/share --includedir=/usr/include \
--enable-force-cgi-redirect \
--bindir=/usr/bin \
--with-config-file-path=/etc/php5/apache2 \
--enable-mbstring --enable-mbregex \
--with-mysql \
--with-gd --enable-gd-native-ttf \
--with-zlib-dir=/usr/lib \
--with-png-dir=/usr/lib --with-jpeg-dir=/usr/lib --with-xpm-dir=/usr/X11R6 \
--with-freetype-dir=/usr/lib \
--enable-ftp \
--enable-safe-mode \
--bindir=/usr/bin \
--enable-bcmath -enable-calendar \
--enable-ctype \
--enable-magic-quotes \
--enable-inline-optimization \
--enable-tokenizer \
--with-bz2 \
--with-iconv
</pre>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="api.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,86 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Appendix J. Setting up PHP5 in parallel with PHP4 in SuSE 10.1</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt09.html" title="Part IX. Appendices"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix J. Setting up PHP5 in parallel with PHP4 in SuSE 10.1</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part IX. Appendices</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="appendix" title="Appendix J. Setting up PHP5 in parallel with PHP4 in SuSE 10.1"><div class="titlepage"><div><div><h2 class="title"><a name="app.setting-up-parallel-servers"></a>Appendix J. Setting up PHP5 in parallel with PHP4 in SuSE 10.1</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="apj.html#id2654187">J.1. Configuration files and directories for Apache2 in SuSE 10.1</a></span></dt><dt><span class="section"><a href="apjs02.html">J.2. Making sure you have the correct Apache2 setup</a></span></dt><dt><span class="section"><a href="apjs03.html">J.3. Approaches to running multiple PHP versions</a></span></dt><dt><span class="section"><a href="apjs04.html">J.4. Outline of the remainder of the chapter</a></span></dt><dt><span class="section"><a href="apjs05.html">J.5. Part I - Installing PHP4</a></span></dt><dd><dl><dt><span class="section"><a href="apjs05.html#id2654605">J.5.1. Step one; Compiling PHP4 as a module for Apache2</a></span></dt><dt><span class="section"><a href="apjs05.html#id2654607">J.5.2. Step two; Enable the PHP4 module in the Apache2 configuration</a></span></dt></dl></dd><dt><span class="section"><a href="apjs06.html">J.6. Part II - Creating a virtual host</a></span></dt><dd><dl><dt><span class="section"><a href="apjs06.html#id2654980">J.6.1. Step 1; Adding an alias IP-address to Your server</a></span></dt><dt><span class="section"><a href="apjs06.html#id2654984">J.6.2. Step 2; Creating different document and cgi roots</a></span></dt><dt><span class="section"><a href="apjs06.html#id2655010">J.6.3. Step 3; Configure Apache with a virtual host</a></span></dt></dl></dd><dt><span class="section"><a href="apjs07.html">J.7. Part III - Installing PHP5</a></span></dt><dt><span class="section"><a href="apjs08.html">J.8. Part IV - Verifying the setup</a></span></dt><dd><dl><dt><span class="section"><a href="apjs08.html#id2655206">J.8.1. Troubleshooting</a></span></dt></dl></dd></dl></div>
<p>Even though PHP4 is officially deprecated and is no longer actively maintained a large
number of existing installations are stiil (and will be) using PHP4. For this reason it can
be important to be able to test scripts running both PHP4 and PHP5. This section shows how
to do this on Linux SuSE 10.1 installation. Other Linux dialects can use similar but not
identical setups.</p>
<p>SuSE 10.1 ships with Apache2 and PHP5 as standard. In order to install PHP4 in parallel
some extra work is therefore required. This chapter explains how to setup both PHP4 and PHP5
on the same server by configuring Apache2 using virtual hosts. </p>
<p>We will show how to maintain a simultaneous installation of both PHP4 and PHP5 at the same
time without the need to run a switching script to select which PHP version to activate. In
this setup we have opted to configure Apache with two virtual hosts based on IP-address, one
host running PHP4 as a SAPI module and the other virtual host running PHP5 as a CGI
module.</p>
<div class="section" title="Configuration files and directories for Apache2 in SuSE 10.1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2654187"></a>Configuration files and directories for Apache2 in SuSE 10.1</h2></div></div></div>
<p>Before we start we give a short overview of where important configuration files and
directories for Apache2 are located in SuSE </p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>The configuration files setup by SuSE is slightly different from the standard
one-single "/etc/httpd.conf" used by other systems. The way SuSE does it is to
create a hierarchy of setup files under "/etc/apache2/". While this might look
complicated at first sight it has several advantages specially when You consider
that some script have to modify and add configurations to Apache2. Doing
automatic (and safe) edits in a large config file that can also be manually
edited is almost impossible to guarantee. </p>
</div><p>
</p>
<p>
</p><div class="variablelist"><dl><dt><span class="term">Dir: /etc/apache2/</span></dt><dd>
<p>General configuration directory for Apache2, this is where the
"<code class="filename">httpd.conf</code>" lives. </p>
</dd><dt><span class="term">Dir: /etc/apache2/conf.d/</span></dt><dd>
<p>Module configuration files for loaded modules, for example php4.conf.
All the configuration files in this directory will be automatically read
by the main <code class="filename">httpd.conf</code> by means of an
"<code class="code">include conf.d/*.conf</code>" command so the exact name
doesn't really matter as long as the file ends in "<code class="code">*.conf</code>".
</p>
</dd><dt><span class="term">Dir: /etc/apache2/vhosts.d/</span></dt><dd>
<p>Virtual host configuration files. All files in this directory will be
automatically read by the main <code class="filename">httpd.conf</code> the exact
name doesn't really matter as long as the file ends in
"<code class="filename">*.conf</code>". Note: When yast2 is used to edit
virtual hosts it will add its "<code class="filename">yast2_*.conf</code>" in
this directory. Unfortunately the virtual host configuration in yast2 in
not without problem (bugs) for IP based virtual hosts so we prefer to
create the configuration files manually. This will be shown later on in
this article. </p>
</dd><dt><span class="term">File: /etc/sysconfig/apache2</span></dt><dd>
<p>This is the main Apache2 configuration file. This file is the one that
is really used to configure apache when it is started. This is also the
file that the "Yast2" HTTPD-module edits. </p>
<p>From our point of view the most important thing is that this is the
place where we tell Apache2 what external modules to load. </p>
<p>In the SuSE configuration this is done by listing all the modules in
the string variable <code class="code">APACHE_MODULES</code>. In the SuSE
configuration there are no static "AddModule" directives in any of the
configuration files for Apache. Instead this is dynamically generated
each time apache is started (for example by /etc/init.d/apache2 start) </p>
<p>The generation of the actual module file names is quite clever in that
the script looks at the core module name in the
<code class="code">APACHE_MODULE</code> variable and automatically determines the
name of the file name of the load modules. This means that for PHP we
only have to give the name "php4" or "php5" as the name of the module. </p>
<p>The script will then discover that the name of the file load module is
in fact "<code class="filename">libphp4.so</code>" or
"<code class="filename">libphp5.so</code>" automatically. The dynamically
created list of load modules will be written to
"<code class="filename">/etc/apache2/sysconfig/loadmodule.conf</code>" just
before the startup script activates apache2 daemon which will then read
the modules from this file which is included from the main
"<code class="filename">httpd.conf</code>" file. </p>
</dd></dl></div><p>
</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt09.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,21 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Making sure you have the correct Apache2 setup</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="apj.html" title="Appendix J. Setting up PHP5 in parallel with PHP4 in SuSE 10.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Making sure you have the correct Apache2 setup</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Appendix J. Setting up PHP5 in parallel with PHP4 in SuSE 10.1</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="section" title="Making sure you have the correct Apache2 setup"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2654366"></a>Making sure you have the correct Apache2 setup</h2></div></div></div>
<p>PHP is only guaranteed to work with the Apache2 "Prefork MPM"
(Multi-Processing-Module) and you need to have apache2-prefork installed. This also
means that the APACHE_MPM in /etc/sysconfig/apache2 must NOT be set to "worker". You can
read more about the reasons for this issues in the <code class="uri"><a class="uri" href="http://httpd.apache.org/docs-2.0/developer/thread_safety.html" target="_top">Apache
Documentation : Thread Safety</a></code> For general information about MPMs please see
<code class="uri"><a class="uri" href="http://httpd.apache.org/docs-2.0/mpm.html" target="_top">Apache Documentation :
MPM</a></code>
</p>
<p>If you use Yast2 to install Apache2 and the prefork module then all this will be
automatically setup. Before continuing please make sure that You have successfully
installed Apache2 on your server. For example by directing your favorite browser to
"<code class="filename">http://localhost/</code>" </p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>There is no need to install the default SuSE PHP5 module since we must replace
that anyway with our own CGI version of PHP5. </p>
</div><p>
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="apj.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,40 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Approaches to running multiple PHP versions</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="apj.html" title="Appendix J. Setting up PHP5 in parallel with PHP4 in SuSE 10.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Approaches to running multiple PHP versions</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Appendix J. Setting up PHP5 in parallel with PHP4 in SuSE 10.1</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="section" title="Approaches to running multiple PHP versions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2654423"></a>Approaches to running multiple PHP versions</h2></div></div></div>
<p>There are two fundamental ways of running multiple versions of PHP on the same server. </p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Running multiple instances of the HTTPD demon where each instance listens
on separate addresses and/or ports. </p>
<p><span class="bold"><strong>Advantage:</strong></span> This is the only way to run
multiple versions of PHP as (SAPI) modules in Apache2. In addition this has
some better security since potential crashes will be isolated and not effect
the other HTTPD demons. </p>
<p><span class="bold"><strong>Drawback:</strong></span> Running multiple HTTPD
instances will need more system resources in terms of memory and file
handlers. </p>
</li><li class="listitem">
<p>Running one instance of the HTTPD demon which is configured to serve
multiple virtual hosts. This is the approach we have chosen. </p>
<p><span class="bold"><strong>Advantage:</strong></span> Minimum system overhead and
relatively easy to setup. </p>
<p><span class="bold"><strong>Drawback:</strong></span> Only one PHP version can be run
as a (SAPI) Apache module the other PHP versions must be
configured/installed as CGI modules. This has a slight performance impact
and might not be suitable for heavily loaded production sites. (Note: that
could be overcome with the use of fast-cgi which works by pre-loading an
instance of PHP in memory which will then be used by the Apache process. See
Apache2 documentation regarding fast-cgi for more details). </p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>There are actually two versions of virtual hosts with apache. By
name pr by IP-address. In this example we have chosen to match the
virtual hosts by IP address since for a development server we want
to be able to use plain IP addresses and not have the added
complexity of setting up a full DNS server. For more details about
other differences please see the excellent Apache2 documentation.
</p>
</div><p>
</p>
</li></ol></div><p>
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="apj.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,28 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Outline of the remainder of the chapter</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="apj.html" title="Appendix J. Setting up PHP5 in parallel with PHP4 in SuSE 10.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Outline of the remainder of the chapter</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Appendix J. Setting up PHP5 in parallel with PHP4 in SuSE 10.1</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="section" title="Outline of the remainder of the chapter"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2654435"></a>Outline of the remainder of the chapter</h2></div></div></div>
<p>The approach we will use is to setup PHP4 as a (SAPI) Apache module on the default
server address and setup PHP5 as a CGI module on a virtual host. </p>
<p>
</p><div class="variablelist"><dl><dt><span class="term">Part I - Installing PHP4 as a SAPI module in Apache.</span></dt><dd>
<p>Part 1 Installing PHP4 as a SAPI module in Apache. This sections
details how to configure and compile PHP4 as a SAPI module and then do
the necessary Apache configuration modifications to enable this new
module. By the end of this section we will have the ability to run PHP4
scripts on our server. </p>
</dd><dt><span class="term">Part II - Creating a virtual host</span></dt><dd>
<p>By assigning an alias IP-address on the server we can configure Apache
with a virtual server based on this address. This new virtual server
will have its own "cgi-bin/" as well as "htdocs/" directories. This part
shows how to enable this by adding suitable configurations in Apache. By
the end of this section our server will accept HTTP calls on a secondary
IP-Address and use the specified document root for this new IP-address.
</p>
</dd><dt><span class="term">Part III - Installing PHP5 as a CGI module on the virtual host.</span></dt><dd>
<p>This final part shows how to configure and compile PHP5 as a CGI
module that we then make available for the newly created virtual host in
part 2. By the end of this module we will have PHP4 running on the
default server address and PHP5 running on the secondary virtual host.
</p>
</dd></dl></div><p>
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="apj.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,219 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Part I - Installing PHP4</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="apj.html" title="Appendix J. Setting up PHP5 in parallel with PHP4 in SuSE 10.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Part I - Installing PHP4</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Appendix J. Setting up PHP5 in parallel with PHP4 in SuSE 10.1</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="section" title="Part I - Installing PHP4"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2654589"></a>Part I - Installing PHP4</h2></div></div></div>
<div class="section" title="Step one; Compiling PHP4 as a module for Apache2"><div class="titlepage"><div><div><h3 class="title"><a name="id2654605"></a>Step one; Compiling PHP4 as a module for Apache2</h3></div></div></div>
<p>First download the latest PHP4 tar-ball from php.net or the closest mirror and
unpack it in a temporary directory. </p>
<p>Since we will compile PHP4 ourself we need first to make sure a number of
libraries and the corresponding header files are installed in the system in order to
be able to compile PHP4. This is done by installing a number of "*-devel.rpm" on
your server. Depending your wanted configuration different development libraries
must be made available. </p>
<p>At the very minimum you will need the "apache2-devel.rpm" which provides the
"/sbin/apxs2" (Apache eXtenSion 2) command used to build modules with Apache2. Other
modules you might need are </p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p>jpeg-devel.rpm </p>
</li><li class="listitem">
<p>png-devel.rpm </p>
</li><li class="listitem">
<p>mm-devel.rpm </p>
</li><li class="listitem">
<p>xml2-devel.rpm </p>
</li><li class="listitem">
<p>mysql-devel.rpm </p>
</li><li class="listitem">
<p>...</p>
</li></ul></div><p>
</p>
<p>Before you compile PHP4 you need to configure it by running the "./configure"
command with the options you want to be included in PHP4. </p>
<p>We use a small shell script called "mkphp4-sapi" to avoid having to re-type all
the options each time we compile a new version of PHP. The options we use for a
typical development server are (you might want to use other options) </p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">#! /bin/sh
./configure --prefix=/usr/share \
--datadir=/usr/share/php4 \
--with-apxs2=/usr/sbin/apxs2 \
--libdir=/usr/share \
--includedir=/usr/include \
--bindir=/usr/bin \
--with-config-file-path=/etc/php4/apache2 \
--enable-mbstring --enable-mbregex \
--with-mysql \
--with-gd --enable-gd-imgstrttf --enable-gd-native-ttf \
--with-zlib-dir=/usr/lib \
--with-png-dir=/usr/lib \
--with-jpeg-dir=/usr/lib --with-xpm-dir=/usr/X11R6 \
--with-tiff-dir=/usr/lib --with-ttf-dir=/usr/lib \
--with-freetype-dir=/usr/lib \
--enable-ftp \
--enable-memory-limit --enable-safe-mode \
--bindir=/usr/bin \
--enable-bcmath -enable-calendar \
--enable-ctype --with-ftp \
--enable-magic-quotes \
--enable-inline-optimization \
--with-bz2 \
--with-iconv</span></pre></td></tr></table></div><p>
</p>
<p>However there are one thing You should take notice of. We have specified the
config file path (where the php.ini resides) to "/etc/php4/apache2/" as You can
probably guess from this naming convention it will make it possible to have
different ini files for both PHP4 and PHP5. In fact we have four different ini files
according to </p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>"<code class="filename">/etc/php4/apache2/php.ini</code>" Used by the apache
SAPI module version of PHP4 </p>
</li><li class="listitem">
<p>"<code class="filename">/etc/php4/cli/php.ini</code>" Used by the standalone
client version of PHP4 (/usr/bin/php4) </p>
</li><li class="listitem">
<p>"<code class="filename">/etc/php5/apache2/php.ini</code>" Used by the apache
CGI version of PHP5 </p>
</li><li class="listitem">
<p>"<code class="filename">/etc/php5/cli/php.ini</code>" Used by the standalone
client version of PHP5 (/usr/bin/php5) </p>
</li></ol></div><p>
</p>
<p>When you run this you might get some errors saying that the configuration file
cannot find some library. This is a sign that you might have the library installed
but not yet have the "*-devel" RPM version added to your system which is needed
since this is where all the usual header files needed for compilation would be. </p>
<p>So for example if you get an error like "Cannot find PNG libraries. Please check
your that the corresponding "png-devel" library is installed and if not go back to
Yast2 and install the needed "*-devel.rpm" versions of the libraries. </p>
<p>When You have been able to successfully run the ./configuration command it is time
to compile. Type "make" as usual but do not type "make install", now wait until the
compilation finishes. </p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>If you are on a Pentium4 HT or on a real dual CPU machine you can speed up
the compilation by instead giving the "make -j3" command which will start up
3 concurrent compilation processes.</p>
</div><p>
</p>
<p>Again; Do not run "<code class="code">make install</code>" since this will try to modify the
configuration files in a way that isn't SuSE friendly. </p>
<p>The resulting PHP4 that you have built can be found in
"<code class="filename">.libs/libphp4.so</code>". Now we only want to copy this file to
the location of the other Apache2 modules. </p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>Again, PHP is only guaranteed to work with the non-threaded version of
Apache2, which means that you should have installed the "apache2-prefork"
MPM and NOT the "apache2-worker" MPM. </p>
</div><p>
</p>
<p>If you have correctly installed the prefork MPM several existing modules should
now be installed in "<code class="filename">/usr/lib/apache2-prefork/</code>". </p>
<p>So the only thing that now remains is to copy
"<code class="filename">.libs/libphp4.so</code>" to
"<code class="filename">/usr/apache2-prefork/</code>" in order for Apache to find PHP4 as
a module. </p>
</div>
<div class="section" title="Step two; Enable the PHP4 module in the Apache2 configuration"><div class="titlepage"><div><div><h3 class="title"><a name="id2654607"></a>Step two; Enable the PHP4 module in the Apache2 configuration</h3></div></div></div>
<p>There are three steps to needed to enable PHP4 in Apache. </p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Add php4 to the APACHE_MODULE string in "/etc/sysconfig/apache2" in
order so that the startup script in SuSE will add the appropriate
LoadModule statement so that Apache will load PHP4 as a module. In our
case our module string will look like </p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">APACHE_MODULES=&quot;access actions alias auth auth_dbm autoindex cgi \
dir env expires include log_config mime negotiation setenvif ssl \
suexec userdir dav dav_svn php4 &quot;</span></pre></td></tr></table></div><p>
</p>
</li><li class="listitem">
<p>Telling Apache to run files ending in *.php through the PHP4 module.
This is done by specifying the MIME type which the PHP4 module
registered itself with. In addition we also tell Apache to search for
the appropriate PHP index files in case a directory name is given as the
URL. We do this by creating a file "<code class="filename">php4.conf</code>" with
the following content </p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">&lt;IfModule sapi_apache2.c&gt;
AddType application/x-httpd-php .php3
AddType application/x-httpd-php .php4
AddType application/x-httpd-php .php
AddType application/x-httpd-php-source .php3s
AddType application/x-httpd-php-source .php4s
AddType application/x-httpd-php-source .phps
DirectoryIndex index.php3
DirectoryIndex index.php4
DirectoryIndex index.php
&lt;/IfModule&gt;</span></pre></td></tr></table></div><p>
</p>
<p>and place it in the "<code class="filename">/etc/apache2/conf.d/</code>"
directory. This will guarantee that it will be read upon startup. The
"<code class="code">IfModule</code>" statement in the beginning is just to avoid
the statements to be executed in case the PHP4 module is not loaded (we
test this by checking if the "<code class="code">sapi_apache2.c</code>" has been
activated in Apache). </p>
</li><li class="listitem">
<p>The final step now is to restart Apache by doing (as root) </p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$&gt; /etc/init.d/apache2 restart</span></pre></td></tr></table></div><p>
</p>
</li></ol></div><p>
</p>
<p>In order to verify that PHP has been enabled run a standard PHP script; for
example by copying the following script to "<code class="filename">/srv/www/htdocs/</code>" </p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-identifier">phpinfo</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div><p>
</p>
<p>and name it as "<code class="filename">phpinfo.php</code>" . If you now go to your favorite
browser and run this script as "http://localhost/phpinfo.php" you should get the
standard PHP4 information presented as a quite big table. </p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="apj.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,107 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Part II - Creating a virtual host</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="apj.html" title="Appendix J. Setting up PHP5 in parallel with PHP4 in SuSE 10.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Part II - Creating a virtual host</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Appendix J. Setting up PHP5 in parallel with PHP4 in SuSE 10.1</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="section" title="Part II - Creating a virtual host"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2654968"></a>Part II - Creating a virtual host</h2></div></div></div>
<div class="section" title="Step 1; Adding an alias IP-address to Your server"><div class="titlepage"><div><div><h3 class="title"><a name="id2654980"></a>Step 1; Adding an alias IP-address to Your server</h3></div></div></div>
<p>In this example we will assume that the server is called "gamma" and have the
primary address "192.168.0.50". The virtual host will be called "gamma2" and will be
located at address "192.168.0.51". The easiest way to add another address alias is
to use yast2 and the network configuration module and simple add a new alias.
</p>
</div>
<div class="section" title="Step 2; Creating different document and cgi roots"><div class="titlepage"><div><div><h3 class="title"><a name="id2654984"></a>Step 2; Creating different document and cgi roots</h3></div></div></div>
<p>In preparation of the new virtual host we want it to have a separate document and
cgi (where we will store the PHP5 binary) roots compared with the standard server.
For this purpose we add two new directories "/srv/www/gamm2-htdocs/" and
"/srv/www/gamma2-cgi-bin/" on the server. </p>
</div>
<div class="section" title="Step 3; Configure Apache with a virtual host"><div class="titlepage"><div><div><h3 class="title"><a name="id2655010"></a>Step 3; Configure Apache with a virtual host</h3></div></div></div>
<p>For his we add a new small config file named "gamma2_vhost.conf" (the exact name
is not important as long as it ends in *.conf) in the "/etc/apache2/vhosts.d/"
directory. The script we add is </p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code"># Setup gamma2 on secondary IP-address
&lt;VirtualHost 192.168.0.51&gt;
DocumentRoot /srv/www/gamma2-htdocs/
ServerName gamma2
ServerAdmin root@localhost
# We use a separate CGI directory
ScriptAlias /cgi-bin/ /srv/www/gamma2-cgi-bin/
# For good measure we also add recognition of PHP5 index
DirectoryIndex index.php5
# This is the two critical statement for this virtual
# host we activate PHP5 as a CGI module
Action php5-cgi /cgi-bin/php
AddHandler php5-cgi .php5 .php
&lt;Directory /srv/www/gamma2-cgi-bin/&gt;
AllowOverride None
Options +ExecCGI -Includes
Order allow,deny
Allow from all
&lt;/Directory&gt;
&lt;Directory &quot;/srv/www/gamma2-htdocs/&quot;&gt;
Options None
AllowOverride None
Order allow,deny
Allow from all
DirectoryIndex index.html index.php
&lt;/Directory&gt;
UserDir public_html
&lt;/VirtualHost&gt;</span></pre></td></tr></table></div><p>
</p>
<p>We do not go into any more detail of this configuration since it should be fairly
easy to understand. For details we refer to the Apache documentation. </p>
<p>What we have accomplished with this file is that when we call the server on the
second address any php file will be recognized by apache as a file to be handled by
the "php5-cgi" action. This in turn means that whenever Apache encounters a *.php5
(or *.php) file it will run the program "/cgi-bin/php". This path in turn will be
expanded to " /srv/www/gamma2-cgi-bin/php". </p>
<p>In the next section we will show how to compile PHP5 and put the executable CGI
version in this directory.</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="apj.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,65 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Part III - Installing PHP5</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="apj.html" title="Appendix J. Setting up PHP5 in parallel with PHP4 in SuSE 10.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Part III - Installing PHP5</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Appendix J. Setting up PHP5 in parallel with PHP4 in SuSE 10.1</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="section" title="Part III - Installing PHP5"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2655055"></a>Part III - Installing PHP5</h2></div></div></div>
<p>We are now ready for the last step which means compiling PHP5 as a CGI module for
Apache. This follows the same principle as the compilation for PHP4 as described above.
Again, we use a small configuration script "<code class="filename">mkphp5-cgi</code>" which is
shown below.</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">#! /bin/sh
./configure --prefix=/usr/share \
--datadir=/usr/share/php \
--libdir=/usr/share --includedir=/usr/include \
--enable-force-cgi-redirect \
--bindir=/usr/bin \
--with-config-file-path=/etc/php5/apache2 \
--enable-mbstring --enable-mbregex \
--with-mysql \
--with-gd --enable-gd-imgstrttf --enable-gd-native-ttf \
--with-zlib-dir=/usr/lib \
--with-png-dir=/usr/lib --with-jpeg-dir=/usr/lib \
--with-xpm-dir=/usr/X11R6 \
--with-tiff-dir=/usr/lib --with-ttf-dir=/usr/lib \
--with-freetype-dir=/usr/lib \
--enable-ftp \
--enable-memory-limit --enable-safe-mode \
--bindir=/usr/bin \
--enable-bcmath -enable-calendar \
--enable-ctype --with-ftp \
--enable-magic-quotes \
--enable-inline-optimization \
--with-bz2 \
--with-iconv</span></pre></td></tr></table></div><p>
</p>
<p>Notice that as we said before we have a different configuration path for PHP5 compared
with PHP4 as shown above. Also note that in order to build the CGI module we do not
configure the "apxs2" option. After successful configuration type
"<span class="command"><strong>make</strong></span>" but do not type "<span class="command"><strong>make install</strong></span>" in order
to compile PHP5. </p>
<p>After the compilation have finished copy "<code class="filename">sapi/cgi/php</code>" to
"<code class="filename">/srv/www/gamma2-cgi-bin/php</code>" since this is the place where our
virtual host expects to find the PHP5 CGI module. </p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="apj.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,66 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Part IV - Verifying the setup</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="apj.html" title="Appendix J. Setting up PHP5 in parallel with PHP4 in SuSE 10.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Part IV - Verifying the setup</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Appendix J. Setting up PHP5 in parallel with PHP4 in SuSE 10.1</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="section" title="Part IV - Verifying the setup"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2655112"></a>Part IV - Verifying the setup</h2></div></div></div>
<p>The only small thing remaining, in case You haven't done so already, is to create
suitable "<code class="filename">php.ini</code>" scripts that are copied to the previous
specified PHP4 and PHP5 config file directories,
"<code class="filename">/etc/php4/apache2/</code>" and
"<code class="filename">/etc/php5/apache2/</code>". </p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>It is recommended to enable all warnings and errors in each php.ini file
unless You have very, very good reasons not to do this. Use the default php.ini
files in the PHP distribution as the initial template. For use with JpGraph it
is recommended to do the following modifications: </p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Increase maximum allowed memory to 32MB </p>
</li><li class="listitem">
<p>Increase maximum allowed script running time to 30s</p>
</li><li class="listitem">
<p>Set full error reporting </p>
</li></ol></div><p>
</p>
</div><p>
</p>
<p>Assuming the IP-addresses shown in the configuration above we are now ready to test
out setup. In order to do this make sure that each document root have the "phpinfo.php"
test script (see above). </p>
<p>We can now test the different setups by using the URLs </p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p><code class="filename">http://192.168.0.50/phpinfo.php</code>
</p>
<p>This URL would send back configuration showing that the server is running
PHP4. Verify that the config path used is set to
"<code class="filename">/etc/php4/apache2/</code>". </p>
</li><li class="listitem">
<p><code class="filename">http://192.168.0.51/phpinfo.php</code>
</p>
<p>This URL would send back configuration showing that the server is running
PHP5 Verify that the config path used is set to
"<code class="filename">/etc/php5/apache2/</code>". </p>
</li></ol></div><p>
</p>
<div class="section" title="Troubleshooting"><div class="titlepage"><div><div><h3 class="title"><a name="id2655206"></a>Troubleshooting</h3></div></div></div>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>If your browser asks you to download content with mime-type
"<code class="code">mime/x-httpd-application</code>" when you try to visit the
PHP script it means that Apache does not yet run PHP as a module (now
module have accepted to handle the x-http-application mime type). Make
sure you have included the "php4" in the <code class="code">APACHE_MODULES</code>
string as described above and that you added the
"<code class="filename">php4.conf</code>" file in the
"<code class="filename">/etc/apache2/conf.d/</code>" directory. </p>
</li><li class="listitem">
<p>We had some issues with FireFox insisting on downloading
"<code class="filename">phpinfo.php</code>" as a file even when other browser
showed the page properly, using "<span class="command"><strong>etherreal</strong></span>" we could
confirm that Firefox was using a previous cached version before we had
enabled PHP in the apache configuration. To solve this we had to clear
the Firefox cache. </p>
</li></ol></div><p>
</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="apj.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,13 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Appendix K. Why it is not possible to add a SVG backend to JpGraph</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt09.html" title="Part IX. Appendices"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix K. Why it is not possible to add a SVG backend to JpGraph</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part IX. Appendices</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="appendix" title="Appendix K. Why it is not possible to add a SVG backend to JpGraph"><div class="titlepage"><div><div><h2 class="title"><a name="app.adding-svg"></a>Appendix K. Why it is not possible to add a SVG backend to JpGraph</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="apk.html#id2655305">K.1. Background</a></span></dt><dt><span class="sect1"><a href="apks02.html">K.2. Summary of findings</a></span></dt><dt><span class="sect1"><a href="apks03.html">K.3. Detailing the issue</a></span></dt><dd><dl><dt><span class="sect2"><a href="apks03.html#id2655351">K.3.1. The core problem</a></span></dt><dt><span class="sect2"><a href="apks03.html#id2655400">K.3.2. Why is this a problem ?</a></span></dt><dt><span class="sect2"><a href="apks03.html#id2655415">K.3.3. Possible workarounds</a></span></dt><dt><span class="sect2"><a href="apks03.html#id2655446">K.3.4. What would be required ?</a></span></dt><dt><span class="sect2"><a href="apks03.html#id2655488">K.3.5. DOM scripting and GetBBox()</a></span></dt><dt><span class="sect2"><a href="apks03.html#id2655518">K.3.6. A final comment</a></span></dt></dl></dd></dl></div>
<div class="sect1" title="Background"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2655305"></a>Background</h2></div></div></div>
<p>We have received many suggestions to add SVG as output from the library to achieve
better quality in off-screen reproduction of graphs. Adding SVG output would
significantly enhance the print quality as well as adding the possibility of
seamless zooming in graphs. For this reason we have done a brief pre-study on the
feasibility of such a backend. This short note will describe our findings. </p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt09.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,13 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Summary of findings</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="apk.html" title="Appendix K. Why it is not possible to add a SVG backend to JpGraph"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Summary of findings</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Appendix K. Why it is not possible to add a SVG backend to JpGraph</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Summary of findings"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2655321"></a>Summary of findings</h2></div></div></div>
<p>To our surprise we have to conclude that with the current SVG standard 1.1 as well
as with the upcoming 1.2 (based on SVG-T) it will not be possible to implement a
full backend in SVG. </p>
<p>The primary hinder is the lack of adequate text manipulation in the current SVG
standard. In addition the implementation of the text supporting feature in current
SVG viewers range from poor and erroneous to non-existing. </p>
<p>The only way to solve this would be to drastically reduce some functionality of
the library in regards to text handling and require the user of the library to
supply text sizes to be used in many places of the library where that is needed.
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="apk.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,122 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Detailing the issue</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="apk.html" title="Appendix K. Why it is not possible to add a SVG backend to JpGraph"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Detailing the issue</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Appendix K. Why it is not possible to add a SVG backend to JpGraph</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Detailing the issue"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2655344"></a>Detailing the issue</h2></div></div></div>
<div class="sect2" title="The core problem"><div class="titlepage"><div><div><h3 class="title"><a name="id2655351"></a>The core problem</h3></div></div></div>
<p>It all boils down to one critical issue: </p>
<p>With the current SVG 1.1 (and draft 1.2) standard there is no way to
statically find out the bounding box of an arbitrary text string for later usage
in the SVG script. </p>
<p>This very surprising omission in the SVG standard makes it in principal
impossible to even do such a simple thing as drawing a frame around a text
programatically since there is no easy way to find out the size, in the given
coordinate system, of the string. </p>
<p>Since the actual bounding box is dependent on both font, style, size, etc as
well as the actual SVG viewer text-layout engine implementation this calculation
cannot be done outside the viewer. It must be part of the SVG standard elements. </p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p> Now, anyone who are familiar with SVG would jump in here and point out
that this is not entirely correct. For the specific case of a frame around a
text it would be possible to use a filter function as specified by the
standard but that is a special case that just could be used to draw an
effect that looks like a frame around a text (using the objectBoundingBox
property). It is still not possible to find out the bounding box. </p>
<p>The second approach would be to to add some DOM Javascript code in the SVG
script which upon execution of the script could in theory find out the
bounding box and adjust suitable attributes in the script. </p>
</div>
</div>
<div class="sect2" title="Why is this a problem ?"><div class="titlepage"><div><div><h3 class="title"><a name="id2655400"></a>Why is this a problem ?</h3></div></div></div>
<p>There are many places in the library where it is absolutely essential to find
out the bounding box of a text string to adjust the position of other object in
the graph. For example margins for titles, column width in gantt charts and
legends and so on. Without this functionality it will be impossible to add SVG
output without significantly reducing the functionality and in essence create a
new version of the library suitable for this reduced functionality that is
brought upon us by the use of SVG. </p>
</div>
<div class="sect2" title="Possible workarounds"><div class="titlepage"><div><div><h3 class="title"><a name="id2655415"></a>Possible workarounds</h3></div></div></div>
<p>Looking at this from a more positive view instead of explaining why it cannot
be done there are in principal only two workarounds (neither which is a 100%
solution) </p>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Using a single fixed font. Restricting the library to one specific
fixed font would make it possible to calculate the bounding box for the
string. Due to differences in the existing viewers it would be necessary
to have some safety margins built in when doing this calculation.
However this would significantly impact the visual appearance of the
graphs. </p>
</li><li class="listitem">
<p>Using heuristics By establishing some "good enough" heuristics for a
plain font we can try to find a guesstimate of the size of the string.
Unfortunately it is a big difference in length between "iiiii" and
"wwwww" even though they have the same number of characters. So without
fully implementing the same algorithm as some SVG viewer text-layout
engine uses this method cannot guarantee that the text will always fit
without making the box fit the worst case. In addition this method will
have some difficulty in handling rotated text strings. </p>
</li></ol></div>
</div>
<div class="sect2" title="What would be required ?"><div class="titlepage"><div><div><h3 class="title"><a name="id2655446"></a>What would be required ?</h3></div></div></div>
<p>What would be required in the standard to solve this is a new basis element
which could be used to record the bounding box of a particular text string for
later reference. To just give some idea on what is needed some "pseudo-SVG" that
we would need is something along the lines of: </p>
<div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">&lt;def&gt;
&lt;boundingbox id=&quot;bb1&quot;
text=&quot;This is a text&quot; style=&quot; /&gt;
&lt;/def&gt;
&lt;rect x=&quot;50+#bb1.x1-10&quot; y=&quot;50+#bb1.y1-10&quot;
width=&quot;#bb1.width+20&quot;
height=&quot;#bb1.height+20&quot; /&gt;
&lt;text x=&quot;50&quot; y=&quot;50&quot; &gt;
&lt;tref xlink:href=&quot;#bb1&quot; /&gt;
&lt;/text&gt;</span></pre></td></tr></table></div>
<p>The basic idea is that in the def-section all text strings to later be used in
the script is defined together with the font (and any other formatting
applicable). These text strings are defined in the new SVG element "boundingbox"
which will calculate the bounding box of the given text. These text string is
later referenced in the actual text with a standard tref element. The bounding
box attributes can then be used in the positioning of the text with a "#"
reference based on the id of the new introduced element "boundingbox" The above
script would then draw a text string positioned at (50,50) with a frame around
it with a 10 units margin all around.</p>
</div>
<div class="sect2" title="DOM scripting and GetBBox()"><div class="titlepage"><div><div><h3 class="title"><a name="id2655488"></a>DOM scripting and GetBBox()</h3></div></div></div>
<p>Since we make no claim to be experts in all aspects of the SVG standard (which
is fairly big) it might be possible that there is some way to still solve this
that has eluded us so we would be very interested in getting a second opinion of
these findings. We are aware of the SVG method GetBBox() but this would not work
in the library very well. The reason is that this is not a static function but
requires the context of a DOM script. This would require a substantially rewrite
of the library since there are graphs where every single coordinate would have
to be back-patched in the end (possible in multiple passes - since the
calculation of one bounding box would be needed to adjust another element). </p>
<p>This means that the script would no longer be static but would require the
library to generate "self-modifying" DOM script at the end. The logic of the
library assumes that the bounding box of text can be found out at the place of
creation and then this bounding box can be used to adjust subsequent
coordinates. </p>
<p>So to summarize this we do not feel that the potential back patching of every
single element in the SVG image at the end in a DOM script is a solution.
</p>
</div>
<div class="sect2" title="A final comment"><div class="titlepage"><div><div><h3 class="title"><a name="id2655518"></a>A final comment</h3></div></div></div>
<p>Since we still find it very hard to believe this giant oversight in the
standard we would be happy to receive comments on these conclusions. </p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="apk.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,267 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Appendix L. The JpGraph configuration file</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt09.html" title="Part IX. Appendices"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix L. The JpGraph configuration file</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part IX. Appendices</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="appendix" title="Appendix L. The JpGraph configuration file"><div class="titlepage"><div><div><h2 class="title"><a name="app.jpg-config"></a>Appendix L. The JpGraph configuration file</h2></div></div></div>
<div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment">=======================================================================</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> File: JPG-CONFIG.INC</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Description: Configuration file for JpGraph library</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Created: 2004-03-27</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Ver: </span><span class="hl-inlinedoc">$Id: jpg-config.inc.php 1839 2009-09-25 12:36:15Z ljp $</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Copyright (c) Aditus Consulting. All rights reserved.</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment">========================================================================</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment">------------------------------------------------------------------------</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Directories for cache and font directory.</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> CACHE_DIR:</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> The full absolute name of the directory to be used to store the</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> cached image files. This directory will not be used if the USE_CACHE</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> define (further down) is false. If you enable the cache please note that</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> this directory MUST be readable and writable for the process running PHP.</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Must end with '/'</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> TTF_DIR:</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Directory where TTF fonts can be found. Must end with '/'</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> The default values used if these defines are left commented out are:</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> UNIX:</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> CACHE_DIR /tmp/jpgraph_cache/</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> TTF_DIR /usr/share/fonts/truetype/</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> MBTTF_DIR /usr/share/fonts/truetype/</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> WINDOWS:</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> CACHE_DIR $SERVER_TEMP/jpgraph_cache/</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> TTF_DIR $SERVER_SYSTEMROOT/fonts/</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> MBTTF_DIR $SERVER_SYSTEMROOT/fonts/</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment">------------------------------------------------------------------------</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> define('CACHE_DIR','/tmp/jpgraph_cache/');</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> define('TTF_DIR','/usr/share/fonts/truetype/');</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> define('MBTTF_DIR','/usr/share/fonts/truetype/');</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment">-------------------------------------------------------------------------</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Cache directory specification for use with CSIM graphs that are</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> using the cache.</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> The directory must be the filesysystem name as seen by PHP</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> and the 'http' version must be the same directory but as</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> seen by the HTTP server relative to the 'htdocs' ddirectory.</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> If a relative path is specified it is taken to be relative from where</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> the image script is executed.</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> </span><span class="hl-inlinedoc">Note:</span><span class="hl-comment"> The default setting is to create a subdirectory in the</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> directory from where the image script is executed and store all files</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> there. As ususal this directory must be writeable by the PHP process.</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">define</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">CSIMCACHE_DIR</span><span class="hl-quotes">'</span><span class="hl-code">,</span><span class="hl-quotes">'</span><span class="hl-string">csimcache/</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-reserved">define</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">CSIMCACHE_HTTP_DIR</span><span class="hl-quotes">'</span><span class="hl-code">,</span><span class="hl-quotes">'</span><span class="hl-string">csimcache/</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment">------------------------------------------------------------------------</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Various JpGraph Settings. Adjust accordingly to your</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> preferences. Note that cache functionality is turned off by</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> default (Enable by setting USE_CACHE to true)</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment">------------------------------------------------------------------------</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Deafult locale for error messages.</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> This defaults to English = 'en'</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">define</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">DEFAULT_ERR_LOCALE</span><span class="hl-quotes">'</span><span class="hl-code">,</span><span class="hl-quotes">'</span><span class="hl-string">en</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Deafult graphic format set to 'auto' which will automatically</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> choose the best available format in the order png,gif,jpeg</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> (The supported format depends on what your PHP installation supports)</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">define</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">DEFAULT_GFORMAT</span><span class="hl-quotes">'</span><span class="hl-code">,</span><span class="hl-quotes">'</span><span class="hl-string">auto</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Should the cache be used at all? By setting this to false no</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> files will be generated in the cache directory.</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> The difference from READ_CACHE being that setting READ_CACHE to</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> false will still create the image in the cache directory</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> just not use it. By setting USE_CACHE=false no files will even</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> be generated in the cache directory.</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">define</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">USE_CACHE</span><span class="hl-quotes">'</span><span class="hl-code">,</span><span class="hl-reserved">true</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Should we try to find an image in the cache before generating it?</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Set this define to false to bypass the reading of the cache and always</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> regenerate the image. Note that even if reading the cache is</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> disabled the cached will still be updated with the newly generated</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> image. Set also 'USE_CACHE' below.</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">define</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">READ_CACHE</span><span class="hl-quotes">'</span><span class="hl-code">,</span><span class="hl-reserved">true</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Determine if the error handler should be image based or purely</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> text based. Image based makes it easier since the script will</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> always return an image even in case of errors.</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">define</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">USE_IMAGE_ERROR_HANDLER</span><span class="hl-quotes">'</span><span class="hl-code">,</span><span class="hl-reserved">true</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Should the library examine the global php_errmsg string and convert</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> any error in it to a graphical representation. This is handy for the</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> occasions when, for example, header files cannot be found and this results</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> in the graph not being created and just a 'red-cross' image would be seen.</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> This should be turned off for a production site.</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">define</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">CATCH_PHPERRMSG</span><span class="hl-quotes">'</span><span class="hl-code">,</span><span class="hl-reserved">true</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Determine if the library should also setup the default PHP</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> error handler to generate a graphic error mesage. This is useful</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> during development to be able to see the error message as an image</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> instead as a 'red-cross' in a page where an image is expected.</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">define</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">INSTALL_PHP_ERR_HANDLER</span><span class="hl-quotes">'</span><span class="hl-code">,</span><span class="hl-reserved">false</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Should usage of deprecated functions and parameters give a fatal error?</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> (Useful to check if code is future proof.)</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">define</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">ERR_DEPRECATED</span><span class="hl-quotes">'</span><span class="hl-code">,</span><span class="hl-reserved">true</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> The builtin GD function imagettfbbox() fuction which calculates the bounding box for</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> text using TTF fonts is buggy. By setting this define to true the library</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> uses its own compensation for this bug. However this will give a</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> slightly different visual apparance than not using this compensation.</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Enabling this compensation will in general give text a bit more space to more</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> truly reflect the actual bounding box which is a bit larger than what the</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> GD function thinks.</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">define</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">USE_LIBRARY_IMAGETTFBBOX</span><span class="hl-quotes">'</span><span class="hl-code">,</span><span class="hl-reserved">true</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment">------------------------------------------------------------------------</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> The following constants should rarely have to be changed !</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment">------------------------------------------------------------------------</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> What group should the cached file belong to</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> (Set to '' will give the default group for the 'PHP-user')</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Please note that the Apache user must be a member of the</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> specified group since otherwise it is impossible for Apache</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> to set the specified group.</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">define</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">CACHE_FILE_GROUP</span><span class="hl-quotes">'</span><span class="hl-code">,</span><span class="hl-quotes">'</span><span class="hl-string">www</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> What permissions should the cached file have</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> (Set to '' will give the default persmissions for the 'PHP-user')</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">define</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">CACHE_FILE_MOD</span><span class="hl-quotes">'</span><span class="hl-code">,</span><span class="hl-number">0664</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt09.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,72 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Appendix M. Theme class</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt09.html" title="Part IX. Appendices"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix M. Theme class</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part IX. Appendices</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="appendix" title="Appendix M. Theme class"><div class="titlepage"><div><div><h2 class="title"><a name="app.theme-class"></a>Appendix M. Theme class</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="apm.html#id1947627">M.1. Theme class</a></span></dt><dt><span class="section"><a href="apms02.html">M.2. Bulk (Re-seller license)</a></span></dt></dl></div>
<div class="section" title="Theme class"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1947627"></a>Theme class</h2></div></div></div>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Theme class test.</p>
</li><li class="listitem">
<p>This irrevocable, perpetual license covers versions 1.x &amp; 2.x of
JpGraph</p>
</li><li class="listitem">
<p>This license gives the holder right to install JpGraph libraries on One Server
which can run one or several virtual HTTP servers.</p>
</li><li class="listitem">
<p>The license holder is allowed to make modifications to the JpGraph sources but
in no event will the original copyright holders of this library be held
responsible for action or actions resulting from any modifications of the
source.</p>
</li><li class="listitem">
<p>The license holder is not required to publicize or otherwise make available
any software used in conjunction with JpGraph.</p>
</li><li class="listitem">
<p>The license holder may not re-distribute the library on it's own or versions
thereof to third party without prior written permission of the copyright
holder.</p>
</li><li class="listitem">
<p>JpGraph License does not allow the library to be redistributed as part of
another product.</p>
</li><li class="listitem">
<p>In no event shall the copyright notice in any of the source files supplied in
JpGraph be removed or modified.</p>
</li><li class="listitem">
<p>The names "JpGraph" or "Aditus" must not be used to endorse or promote
products derived from this software without prior written permission.</p>
</li><li class="listitem">
<p>The license may be transferred to another server by removing all installed
files from the old server.</p>
</li><li class="listitem">
<p>The wording of this license may change without notice for future versions of
JpGraph.</p>
</li><li class="listitem">
<p>By acquiring a license the licensee agrees to all terms and conditions in this
license text.</p>
</li><li class="listitem">
<p><span class="bold"><strong>Limitations of Liability</strong></span></p>
<p>In no event, except for intellectual property claim, shall the initial
developers or copyright holders be liable for any damages whatsoever, including
- but not restricted to - lost revenue or profits or other direct, indirect,
special, incidental or consequential damages, even if they have been advised of
the possibility of such damages, except to the extent invariable law, if any,
provides otherwise.</p>
<p>In addition, in no event does this license authorize you to use JpGraph in
applications or systems where JpGraphs failure to perform can reasonably be
expected to result in a physical injury, loss of life or any economical damage.
Any such use by the licensee is entirely at the licensees own risk, and the
licensee agrees to hold the original copyright holders of JpGraph harmless from
any claims or losses relating to any such unauthorized use.</p>
</li><li class="listitem">
<p><span class="bold"><strong>Limited Warranty</strong></span></p>
<p>JpGraph warrants that licensor is owner of the software with authority to
license the software to licensee and that the software does not infringe third
party intellectual property rights. Licensor agrees to indemnify, defend and
hold harmless licensee from any claims either that licensor does not own the
software or that the software infringes a third party's intellectual
property.</p>
<p>THE SOFTWARE AND THIS LICENSE DOCUMENT ARE PROVIDED AS IS. THE FOREGOING
WARRANTY IS IN LIEU OF ALL OTHER WARRANTIES, EXPRESS OR IMPLIED, OF ANY KIND,
INCLUDING WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.</p>
</li></ol></div>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt09.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,64 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Bulk (Re-seller license)</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="apm.html" title="Appendix M. Theme class"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Bulk (Re-seller license)</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Appendix M. Theme class</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="section" title="Bulk (Re-seller license)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1947750"></a>Bulk (Re-seller license)</h2></div></div></div>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>The JpGraph Professional License will be referred to as "The license" in the
remainder of this text.</p>
</li><li class="listitem">
<p>This irrevocable, perpetual license covers versions 1.x &amp; 2.x of
JpGraph</p>
</li><li class="listitem">
<p>This license gives the licensee the right to distribute the JpGraph libraries,
as part of its product portfolio and to use the Jpgraph libraries with its
hosted service offerings. Specifically this license gives the licensee the right
to deploy an unlimited number of JpGraph installations as part of their product
portfolio and offer an unlimited number of hosted services that use the JpGraph
libraries to an unlimited number of users.</p>
</li><li class="listitem">
<p>The license holder is allowed to make modifications to the JpGraph sources but
in no event will the original copyright holders of this library be held
responsible for action or actions resulting from any modifications of the
source.</p>
</li><li class="listitem">
<p>JpGraph libraries is only licensed to be redistributed as a part of the
licensees products. Specifically it may not be sold or re-distributed on it's
own.</p>
</li><li class="listitem">
<p>In no event shall the copyright notice in any of the source files supplied in
JpGraph be removed or modified.</p>
</li><li class="listitem">
<p>The names "JpGraph" or "Aditus" must not be used to endorse or promote
products derived from this software without prior written permission.</p>
</li><li class="listitem">
<p>The wording of this license may change without notice for future versions of
JpGraph.</p>
</li><li class="listitem">
<p>By acquiring a license the licensee agrees to all terms and conditions in this
license text.</p>
</li><li class="listitem">
<p><span class="bold"><strong>Limitations of Liability</strong></span></p>
<p>In no event, except for intellectual property claim, shall the initial
developers or copyright holders be liable for any damages whatsoever, including
- but not restricted to - lost revenue or profits or other direct, indirect,
special, incidental or consequential damages, even if they have been advised of
the possibility of such damages, except to the extent invariable law, if any,
provides otherwise.</p>
<p>In addition, in no event does this license authorize you to use JpGraph in
applications or systems where JpGraphs failure to perform can reasonably be
expected to result in a physical injury, loss of life or any economical damage.
Any such use by the licensee is entirely at the licensees own risk, and the
licensee agrees to hold the original copyright holders of JpGraph harmless from
any claims or losses relating to any such unauthorized use.</p>
</li><li class="listitem">
<p><span class="bold"><strong>Limited Warranty</strong></span></p>
<p>JpGraph warrants that licensor is owner of the software with authority to
license the software to licensee and that the software does not infringe third
party intellectual property rights. Licensor agrees to indemnify, defend and
hold harmless licensee from any claims either that licensor does not own the
software or that the software infringes a third party's intellectual
property.</p>
<p>THE SOFTWARE AND THIS LICENSE DOCUMENT ARE PROVIDED AS IS. THE FOREGOING
WARRANTY IS IN LIEU OF ALL OTHER WARRANTIES, EXPRESS OR IMPLIED, OF ANY KIND,
INCLUDING WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.</p>
</li></ol></div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="apm.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,29 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 1. About the library</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt01.html" title="Part I. Installing and verifying the configuring"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 1. About the library</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part I. Installing and verifying the configuring</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="chapter" title="Chapter 1. About the library"><div class="titlepage"><div><div><h2 class="title"><a name="chap_about"></a>Chapter 1. About the library</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ch01.html#id2472291">1.1. What is JpGraph?</a></span></dt><dt><span class="sect1"><a href="ch01s02.html">1.2. Software license</a></span></dt><dt><span class="sect1"><a href="ch01s03.html">1.3. Versions of the library covered</a></span></dt><dt><span class="sect1"><a href="ch01s04.html">1.4. Purpose and usage</a></span></dt><dt><span class="sect1"><a href="ch01s05.html">1.5. Prerequisites for running the library</a></span></dt><dt><span class="sect1"><a href="ch01s06.html">1.6. Who can use the library</a></span></dt><dt><span class="sect1"><a href="ch01s07.html">1.7. What you can do with the library</a></span></dt><dt><span class="sect1"><a href="ch01s08.html">1.8. What you shouldn't or cannot do with this library</a></span></dt><dt><span class="sect1"><a href="ch01s09.html">1.9. Feature-matrix for the library</a></span></dt><dt><span class="sect1"><a href="ch01s10.html">1.10. Where to find additional information</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch01s10.html#id2474782">1.10.1. Manuals and distributed documentation</a></span></dt><dt><span class="sect2"><a href="ch01s10.html#id2474831">1.10.2. On-line documentation and resources</a></span></dt></dl></dd></dl></div>
<p title="What you will learn in this chapter">
<b>What you will learn in this chapter. </b>
This chapter will go through what the library is, the licensing model, how it is
typically used and the detailed steps of installing it. This chapter will not
explain how to use the API in the library. It will help answering typical questions
such as "<span class="emphasis"><em>Should I use this library?</em></span>", <span class="emphasis"><em>"Is the library
suitable for use in my particular environment?</em></span>, <span class="emphasis"><em>"Do I have
enough knowledge to use this library?"</em></span>
</p>
<div class="sect1" title="What is JpGraph?"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2472291"></a>What is JpGraph?</h2></div></div></div>
<p>The JpGraph library is a 2D graph plotting library for PHP4 and PHP5. It is meant
to significantly simplify the creation of dynamic graphs using PHP scripting. The
libray can be used on its own or as an embedded part of a large WEB development
undertaking. In addition the library allows images to be created using the command
line version of PHP (the cli version).</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt01.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,20 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Software license</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch01.html" title="Chapter 1. About the library"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Software license</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 1. About the library</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Software license"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2472306"></a>Software license</h2></div></div></div>
<p>JpGraph is released under a dual license. For non-commercial usage the library is
released under QPL 1.0 (Qt-License) and for professional use it is released under
the JpGraph Professional License. See <a class="xref" href="apb.html" title="Appendix B. JpGraph Professional License">Appendix B. <i>JpGraph Professional License</i></a> for more details regarding the exact wording of
the license. The goal the license have is to be simple, fair and help recover some
of the development cost and hosting services that the library development brings
with it.</p>
<p>Broadly speaking commercial use is defined as</p>
<p>a) The library is included as an integral part of a product that is sold with a
cost that exceeds the cost of the distribution medium. </p>
<p>b) The library is offered as a WEB service for a fee </p>
<p>c) The library is used in an intranet in a company with more than 2
employees</p>
<p>One license entitles the user to install the library on one single physical
machine which may run one or several logical servers. In addition it also entitles
the license holder to install one version of the library on a separate development
server. The professional license is perpetual and is valid for one major
version.</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch01.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,39 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Versions of the library covered</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch01.html" title="Chapter 1. About the library"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Versions of the library covered</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 1. About the library</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Versions of the library covered"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2472351"></a>Versions of the library covered</h2></div></div></div>
<p>This manual covers versions up to v3.1 of JpGraph. There are three main branches
of the library: </p><div class="variablelist"><dl><dt><span class="term">The "1.x.y" branch</span></dt><dd>
<p>The 1.x.y series is only intended for PHP4 and is not compatible
with PHP5 running in strict mode. If you are running an older
installation with only PHP4 you must use this branch of the library.
In addition you must use this branch if for some obscure reason only
the very old GD 1.x library is available in the installation (teh GD
library is the low level graphic primitives library used by JpGraph
and available in PHP).</p>
<div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3>
<p>The 1.x.y series is since 31 Dec 2008 no longer maintained and
should be considered deprecated. There will be no more
maintenance releases made on this branch.</p>
</div>
</dd><dt><span class="term">The "3.x.y" branch</span></dt><dd>
<p>The "3.x.y" series is the current one and is only intended to run
on PHP5. This code is optimized for use both with PHP5 as well as
the new (and bundled version) of the GD 2.x library. Hence this will
not work if you only have the older GD 1.x graphic primitive library
installed. However, all modern PHP installations since 2006 have
shipped with GD 2.x so this should not in reality be any
problem.</p>
<div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3>
<p>Please note that it is not possible to run the "3.x.y" series
on PHP4. If you need to run on PHP4 then you <span class="bold"><strong>must</strong></span> use the 1.x version of the
library.</p>
</div>
</dd><dt><span class="term">The "3.x.y-p" branch (The pro-version)</span></dt><dd>
<p>This is in principle the same as the "3.x.y" branch with the
difference that the pro-version includes a number of additional
modules (see <a class="xref" href="pt05.html" title="Part V. Additional graph types available in the professional version">Part V. Additional graph types available in the professional version</a>) not available in the free
version. This includes both some additional graph types as well as
1D and 2D barcodes. In addition the professional license gives three
months of email support for installing and configuring the
library.</p>
</dd></dl></div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch01.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,88 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Purpose and usage</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch01.html" title="Chapter 1. About the library"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Purpose and usage</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 1. About the library</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Purpose and usage"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2472320"></a>Purpose and usage</h2></div></div></div>
<p>The purpose of the library is to make it possible to (very) easily create dynamic
images (a.k.a. graphs) using PHP scripting. The library hides as much as possible
all the details necessary to create dynamic images. Strictly speaking all the basic
low level functionality to draw images are already available in PHP since PHP comes
with the core GD library which is the very lowest layer to create images. The GD
library has graphic primitives to create lines, circles, points etc. but it has no
built-in intelligence to handle scales, labelling , colors etc. This logically makes
JpGraph library a higher type library more easily accessible than the raw GD
library. </p>
<div class="figure"><a name="id2472478"></a><p class="title"><b>Figure 1.1. JpGraph and PHP</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/jpgraph-and-php.png" alt="JpGraph and PHP"></div>
</div></div><br class="figure-break">
<p>There are several possible usage scenario for the library and it's different
parts. </p>
<p>The most common usage is most likely to visualize numeric data by creating basic
charts (for example line, bar or pie charts) that is included dynamically in a
WEB-page via a straight forward <code class="code">&lt;img&gt;</code> tag. The details on how to
create dynamic graphs will be fully covered in later sections of this manual The
library itself is agnostic to where the data comes from so it could for example be
retrieved from a database, from a plain text file or perhaps from some WEB-service.
In addition to this scenario the library could be used as a tool to create dynamic
charts that are stored as image files in a directory. This makes it possible to use
the library in an off-line batch mode from the command line (most likely using the
cli =command line version of PHP). For an example of using JpGraph in batch mode see <a class="xref" href="ch34.html" title="Chapter 34. Showing SPAM statistics">Chapter 34. <i>Showing SPAM statistics</i></a>.</p>
<p>In addition to these basic usage scenarios both the free and the slightly more
advanced pro-version of the library includes a multitude of additional functionality
which includes for example more advanced graph types (like spider graphs, polar
plots, contour plots etc.) and some non graph capabilities like the possibility to
create barcodes (only available in the pro-version) or to create Gantt-charts. The
usage of all of these types of graphs are explained in this manual.</p>
<p>
</p><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3>
<p>In order to use JpGraph the PHP installation must have support for the GD
libraries enabled. See Chapter 2 and 3 for details on checking the
installation.</p>
</div><p>
</p>
<p>In order to get a quick feel for how the library can be used we have included in <a class="xref" href="ch01s04.html#example.example0" title="Example 1.1. This is the very first example (example0.php)">Example 1.1. This is the very first example (<code class="filename">example0.php</code>) </a> a very basic type of line graph. Don't worry
right now about the details, the message here is that it only takes six lines of
real script code to create a basic graph. Have a look at the example and see just
how much of the script makes sense without us even having discussed any API
yet.</p>
<div class="example"><a name="example.example0"></a><p class="title"><b>Example 1.1. This is the very first example (<code class="filename">example0.php</code>) </b></p><div class="example-contents"> <div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code"> </span><span class="hl-comment">//</span><span class="hl-comment"> content=&quot;text/plain; charset=utf-8&quot;</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">require_once</span><span class="hl-code"> </span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">jpgraph/jpgraph.php</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-reserved">require_once</span><span class="hl-code"> </span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">jpgraph/jpgraph_line.php</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Some data</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$ydata</span><span class="hl-code"> = </span><span class="hl-reserved">array</span><span class="hl-brackets">(</span><span class="hl-number">11</span><span class="hl-code">,</span><span class="hl-number">3</span><span class="hl-code">,</span><span class="hl-number">8</span><span class="hl-code">,</span><span class="hl-number">12</span><span class="hl-code">,</span><span class="hl-number">5</span><span class="hl-code">,</span><span class="hl-number">1</span><span class="hl-code">,</span><span class="hl-number">9</span><span class="hl-code">,</span><span class="hl-number">13</span><span class="hl-code">,</span><span class="hl-number">5</span><span class="hl-code">,</span><span class="hl-number">7</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Create the graph. These two calls are always required</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code"> = </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">Graph</span><span class="hl-brackets">(</span><span class="hl-number">350</span><span class="hl-code">,</span><span class="hl-number">250</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetScale</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">textlin</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Create the linear plot</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$lineplot</span><span class="hl-code">=</span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">LinePlot</span><span class="hl-brackets">(</span><span class="hl-var">$ydata</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$lineplot</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetColor</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">blue</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Add the plot to the graph</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Add</span><span class="hl-brackets">(</span><span class="hl-var">$lineplot</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Display the graph</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Stroke</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div></div></div><br class="example-break"> <div class="figure"><a name="fig.example0"></a><p class="title"><b>Figure 1.2. This is the very first example <code class="uri"><a class="uri" href="example_src/example0.html" target="_top">(<code class="filename">example0.php</code>)</a></code> </b></p><div class="figure-contents"> <span class="inlinemediaobject"><img src="images/example0.png" alt="This is the very first example (example0.php)"></span> </div></div><br class="figure-break">
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch01.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,21 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Prerequisites for running the library</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch01.html" title="Chapter 1. About the library"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Prerequisites for running the library</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 1. About the library</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Prerequisites for running the library"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2472465"></a>Prerequisites for running the library</h2></div></div></div>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p>Any 32bit operating system capable of running PHP5</p>
</li><li class="listitem">
<p>PHP5, requires version &gt;= 5.1.0 (it might work with earlier versions
but this is not officially supported)</p>
</li><li class="listitem">
<p>Enabled GD 2.x library in PHP installation. This is normally bundled
with the PHP5 distribution. It is strongly recommended that you use the
included version of GD with PHP5 and not try to install it
separately.</p>
</li></ul></div><p>
</p>
<div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3>
<p>There are known issues so running the library under a 64 bit OS so the library
does not officially support any 64 bit OS:es</p>
</div>
<p>For more detailed information on PHP settings in <code class="filename">php.ini</code> see <a class="xref" href="ch03s02.html#sec.verifying-phpgd-inst" title="Verifying the PHP/GD installation">Verifying the PHP/GD installation</a></p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch01.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,10 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Who can use the library</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch01.html" title="Chapter 1. About the library"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Who can use the library</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 1. About the library</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Who can use the library"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2472657"></a>Who can use the library</h2></div></div></div>
<p>Even though the library hides a lot of details it needs to be pointed out that
this is still a programmers library. It is assumed that the user of the library has
basic skills in programming PHP and is familiar, at least to a basic extent, with
the concept of objects and object oriented programming since the entire library is
built around this paradigm. Fully understanding basic concepts such as classes,
methods, class instances and class inheritage will substantially help in trying to
understand how to use the library.</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch01.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,33 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>What you can do with the library</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch01.html" title="Chapter 1. About the library"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">What you can do with the library</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 1. About the library</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="What you can do with the library"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2472677"></a>What you can do with the library</h2></div></div></div>
<p>One should probably differentiate between the two basic usage scenarios</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p><span class="bold"><strong>Online.</strong></span> That is, the image is dynamically
generated when a user is viewing a particular WEB-page. This means that
the time it takes to generate the image will add to the delay the user
is experiencing when trying to view the page. (The library supports a
caching mechanism to reduce the number of times an image has to
generated, see <a class="xref" href="ch05s06.html" title="Efficient graph generation using the built-in cache subsystem">Efficient graph generation using the built-in cache subsystem</a> for a thorough
discussion). For this scenario one should probably keep the images as
basic as possible in order to have as small latency as possible. </p>
<p>In practice this means that the number of data points to visualize
should be kept in the order of hundreds and not thousands. In later
sections we will discuss in details what can be done to improve the
performance of the library.</p>
<p> </p>
</li><li class="listitem">
<p><span class="bold"><strong>Offline</strong></span>. That is, the images are generated by
some "batch" processing (possible command line based). In this scenario
the delay is not an issue and one could create much more complicated
images and process many more data points. Even though the library in
itself does not impose any restriction of the number of data points to
process the memory and time limits set for PHP will. </p>
<p>In practice if you need to process images with sizes above 2000x2000
pixels resulting from processing 500,000 data points then it is probably
better to find a more suitable way to produce these graphs rather than a
PHP script (unless you are prepared to give PHP a couple of 100 MB of
allowed memory)</p>
</li></ol></div><p>
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch01.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,32 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>What you shouldn't or cannot do with this library</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch01.html" title="Chapter 1. About the library"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">What you shouldn't or cannot do with this library</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 1. About the library</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="What you shouldn't or cannot do with this library"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2472757"></a>What you shouldn't or cannot do with this library</h2></div></div></div>
<p>If the primary usage is heavy scientific processing where you need to visualize
complex 2D/3D scenarios then this library is not for you. In this case it is
probably better to use one of the scientific tools like Matlab or Maple.</p>
<p>In addition, if you for example intend to implement a large scale project planning
tool with several thousand activities that you want to manipulate and display using
the support Gantt charts in this library this is probably stretching it a bit too
far. Again, this is probably better done with more dedicated tools like MS Project. </p>
<p>In addition may we again point out that the library does not officially support
any 64bit OS due to issues with PHP/GD.</p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>Some of the 2D barcodes will simply not work in a 64bit OS. This is
consequence of the computation of the error correcting codes which in some
instances assumes 32bit integers. For the basic graphs there is no known
issues but since the library is not verified on a 64bit OS we do not
officially support this.</p>
</div><p>
</p>
<p>There is also a question on sever load that should be taken into account. Due to
the CPU intensive nature of image processing the complexity of the generated images
needs to be kept as low as possible for any sites that would expect heavy load.
Since it is normally necessary to increase the allowed memory for PHP (see <a class="xref" href="ch03s03.html#sec3.setting-up-php-ini" title="Setting up your php.ini file">Setting up your php.ini file</a>) when working with images this could
easily make the server hit it's physical memory limit if the load is very high. </p>
<p>For example, the practical lowest memory that should be set for PHP when working
with images is 32MB (recommended is at least 64MB), if your system must cope with 50
simultaneous users it means that the HTTP processes alone will need roughly 1.6GB
just to secure the basics. Handling 50 simultaneous executing image scripts will
also require some heavy processing and the server needs to have a CPU capacity to
handle this. Some discussions about dimensioning a server can be found in <a class="xref" href="ch05s06.html" title="Efficient graph generation using the built-in cache subsystem">Efficient graph generation using the built-in cache subsystem</a>.</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch01.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,368 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Feature-matrix for the library</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch01.html" title="Chapter 1. About the library"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Feature-matrix for the library</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 1. About the library</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Feature-matrix for the library"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2472823"></a>Feature-matrix for the library</h2></div></div></div>
<p>JpGraph library is an OO graph library which makes it easy to both draw a "quick and
dirty" graph with a minimum of code and quite complex graphs which requires a very fine
grain of control. The library tries to assign sensible default values for most parameters
hence making the learning curve quite flat since for most of the time very few commands are
required to draw graphs with a pleasing esthetic look.</p>
<p>The following list makes no claim to be complete but it will give a birds view of some of
the main (and in some cases unique) features of the library. The list will also illustrate
the difference between the free and the pro-version.</p>
<p>
</p><div class="table"><a name="id2472846"></a><p class="title"><b>Table 1.1. Feature matrix for JpGraph library</b></p><div class="table-contents">
<table summary="Feature matrix for JpGraph library" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><thead><tr><th>Feature</th><th>Free version</th><th>Pro-version</th></tr></thead><tbody><tr><td>Supports PNG, GIF, JPG image formats</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Flexible scales, supports text-lin, text-log, lin-lin, lin-log,
log-lin and log-log and integer scales </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Supports both PNG, GIF and JPG graphic formats. Note that the
available formats are dependent on the specific PHP installation where
the library is used.</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Supports caching of generated graphs to lessen burden of a HTTP
server. </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Supports batch mode to only generate images to a file</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Supports client side image maps which makes it easy to produce drill
down images. </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Intelligent auto-scaling which gravitates towards esthetic values,
i.e. multiples of 2:s and 5:s </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Fully supports manual scaling, with fine grain control of position of
ticks. </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Multiple Y-axes (and scales) and multiple data series in the same
graph</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Supports background images with different formatting options</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>User specified grace for auto-scaling</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Supports unlimited number of y-axes, </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Supports, line-plots, filled line-plots, accumulated line-plots, bar
plots, accumulated bar plots, grouped bar plots, error plots, line error
plots, scatter plots, gantt-charts, radar plots, 2D and 3D pie charts. </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Supports unlimited number of plots in each graph, makes it easy to
compose complex graph which consists of several plot types </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>User specified position of axis</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Designed as a flexible OO framework which makes it easy to add new
types of plots </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Supports automatic legend generation with custom formatting</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Supports both vertical and horizontal grids</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Supports anti-aliasing of lines</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Supports background images as well as unlimited number of icons in
the graph </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Supports rotation of linear graphs</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>More then 400 named colors</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Designed modularly - you don't have to include code which isn't used </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Supports user specified callback for fine tuning scale labels</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Support for text augmentation of graphs</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Support for PHP Accelerator</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Support for a large set of 1D barcodes (EAN-128, ...)</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Support for Windrose plots</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Support for discontinuities in graphs</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Enhanced anti-aliasing for PieCharts</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>More advanced formatting of graph titles including 3D Bevel effects. </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Additional 3D Bevel formatting feature for the entire Graph </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Footer text on all graph types </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Full support for color alpha blending </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Advanced interpolation with cubic splines to get smooth curves from
just a few data points. </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Several different fill styles for line plots</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Some image 3D effects built-in without external image manipulation
programs </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Additional built-in images for plot marks including 3D rendered
markers like diamonds, squares, bevels, balls, pins etc </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Support for calculation of linear regression</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Text strings can be added to the plot using scale coordinates </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Support for all primitive URL parameter types with CSIM graphs. </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Hare/Niemeyer Integer compensation for Pie Plots </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Possibility to use Vertical Gradient fill for line plots. </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Improved error handling. The visual appearance of the error handling
now tries to mimic any windows system window (in graphic) </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Builtin support to display over 200 country flag and the possibility
to use them as icons or markers in the graphs. All the flag images are
builtin with JpGraph in an efficient pre-compiled data format. </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Support for both Chinese and Japanese character sets </td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Support for custom TTF fonts</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Support for 2D contour plots of 3D functions</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Unlimited number of data points (up to memory and CPU limit of
server)</td><td align="center">
<p class="checkmark">
</p>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Windrose plots</td><td align="center">
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Odometer plots</td><td align="center">
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Graphic excel like tables</td><td align="center">
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>1D Linear barcodes (e.g. EAN8,13,128, Code39, 128, 2of5, Code-11,
Codabar etc)</td><td align="center">
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>2D-Barcode PDF417</td><td align="center">
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>2D-Barcode Datamatrix</td><td align="center">
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>2D-Barcode QR-code</td><td align="center">
</td><td align="center">
<p class="checkmark">
</p>
</td></tr><tr><td>Matrix visualization</td><td>
</td><td align="center">
<p class="checkmark">
</p>
</td></tr></tbody></table>
</div></div><p><br class="table-break">
</p>
<p>In addition to these high level features the library has been designed to be orthogonal
and consistent in its' naming convention. For example, to specify color each object (i.e.
axis, grids, texts, titles etc) within the graph implements the method
<code class="code">SetColor()</code> with the same signature. </p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch01.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,79 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Where to find additional information</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch01.html" title="Chapter 1. About the library"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Where to find additional information</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 1. About the library</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Where to find additional information"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2472803"></a>Where to find additional information</h2></div></div></div>
<p>The primary source for information is this manual together with the<code class="uri"><a class="uri" href="http://jpgraph.net/" target="_top">JpGraph web site</a></code> which also
contains further links to many external sources of information.</p>
<div class="sect2" title="Manuals and distributed documentation"><div class="titlepage"><div><div><h3 class="title"><a name="id2474782"></a>Manuals and distributed documentation</h3></div></div></div>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>The JpGraph user manual (this document)</p>
</li><li class="listitem">
<p>The JpGraph API reference manual. This reference contains details
about all public APIs available together with the classes.</p>
</li><li class="listitem">
<p>JpGraph UML static class diagram. This is an experimental
documentation which shows the static class dependency between all
classes in the library.</p>
</li><li class="listitem">
<p>The <code class="uri"><a class="uri" href="http://jpgraph.intellit.nl/index.php" target="_top">JpGraph
community forum</a></code>. This is a discussion board for users of
the JpGraph library where users both give examples on how they have
used the library as well as asking and answering generic and
specific questions.</p>
</li><li class="listitem">
<p>The FAQ. This is available both <code class="uri"><a class="uri" href="http://jpgraph.net/" target="_top">on-line</a></code> and in <a class="xref" href="apc.html" title="Appendix C. FAQ">Appendix C. <i>FAQ</i></a> to this manual. </p>
</li></ol></div><p>
</p>
</div>
<div class="sect2" title="On-line documentation and resources"><div class="titlepage"><div><div><h3 class="title"><a name="id2474831"></a>On-line documentation and resources</h3></div></div></div>
<p>The JpGraph document portal can be be found at <code class="uri"><a class="uri" href="http://jpgraph.net/doc/" target="_top">http://jpgraph.net/doc/</a></code>
in addition to the distributed documentation there are several "HowTo" sections
which explains with some larger examples how to accomplish some specific type of
graphs and solve common problems.</p>
<p>In addition to the <code class="uri"><a class="uri" href="http://jpgraph.net/" target="_top">JpGraph Web site</a></code> there are
a number of external sites with tutorials and examples on how JpGraph has been
used. This is not a complete list (nor will it ever be) but it lists a few of
the tutorials/examples that we are aware of. The following is a partial list of
known external tutorial showing more or less advanced examples on how to use
specific features of the library. </p>
<p>
</p><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3>
<p>Usual caveats apply in that we can take no responsibility for the
correctness of these tutorials since we have no influence over
them.</p>
</div><p>
</p>
<p>
</p><div class="table"><a name="id2474910"></a><p class="title"><b>Table 1.2. External JpGraph tutorial</b></p><div class="table-contents">
<table summary="External JpGraph tutorial" border="0"><colgroup><col class="c1"><col class="c3"></colgroup><thead><tr><th>Name/Link</th><th>Description</th></tr></thead><tbody><tr><td><span class="bold"><strong>Chart Dog Application.</strong></span></td><td>Application example</td></tr><tr><td colspan="2">
<code class="uri"><a class="uri" href="http://www.jimwrightonline.com/php/chartdog_2_0/chartdog.php" target="_top">http://www.jimwrightonline.com/php/chartdog_2_0/chartdog.php</a></code></td></tr><tr><td><span class="bold"><strong>Découverte de la librairie Php
JpGraph</strong></span></td><td>French tutorial</td></tr><tr><td colspan="2">
<code class="uri"><a class="uri" href="http://eric-pommereau.developpez.com/tutoriels/decouverte-jpgraph/" target="_top">http://eric-pommereau.developpez.com/tutoriels/decouverte-jpgraph/</a></code></td></tr><tr><td><span class="bold"><strong>Einführung zu JPGraph</strong></span></td><td>German tutorial</td></tr><tr><td colspan="2">
<code class="uri"><a class="uri" href="http://www.binnendijk.net/jpgraph/index.php" target="_top">http://www.binnendijk.net/jpgraph/index.php</a></code></td></tr><tr><td><span class="bold"><strong>Des graphes en Php avec
JpGraph</strong></span></td><td>French tutorial</td></tr><tr><td colspan="2">
<code class="uri"><a class="uri" href="http://www.journaldunet.com/developpeur/tutoriel/php/011121php_jpgraph.shtml" target="_top">http://www.journaldunet.com/developpeur/tutoriel/php/011121php_jpgraph.shtml</a></code></td></tr><tr><td><span class="bold"><strong>Developing Professional Quality Graphs with
PHP</strong></span></td><td>English tutorial</td></tr><tr><td colspan="2">
<code class="uri"><a class="uri" href="http://devzone.zend.com/article/1260-Developing-Professional-Quality-Graphs-with-PHP" target="_top">http://devzone.zend.com/article/1260-Developing-Professional-Quality-Graphs-with-PHP</a></code></td></tr><tr><td><span class="bold"><strong>PHPHacks.com Posts Creating charts with
JPGraph</strong></span></td><td>English tutorial</td></tr><tr><td colspan="2">
<code class="uri"><a class="uri" href="http://devzone.zend.com/article/994-PHPHacks.com-Posts-Creating-charts-with-JPGraph" target="_top">http://devzone.zend.com/article/994-PHPHacks.com-Posts-Creating-charts-with-JPGraph</a></code></td></tr><tr><td><span class="bold"><strong>Simple linear regression with
PHP</strong></span></td><td>IBM developer works article</td></tr><tr><td colspan="2">
<code class="uri"><a class="uri" href="http://www.ibm.com/developerworks/web/library/wa-linphp2/" target="_top">http://www.ibm.com/developerworks/web/library/wa-linphp2/</a></code></td></tr><tr><td><span class="bold"><strong>Dreamweaver Article</strong></span></td><td>How to integrate with Dreamweaver</td></tr><tr><td colspan="2">
<code class="uri"><a class="uri" href="http://www.adobe.com/devnet/dreamweaver/articles/php_graphics_11.html" target="_top">http://www.adobe.com/devnet/dreamweaver/articles/php_graphics_11.html</a></code></td></tr><tr><td><span class="bold"><strong>JPGraph Library V2.2
Tutorial</strong></span></td><td>Typo3 integration</td></tr><tr><td colspan="2">
<code class="uri"><a class="uri" href="http://typo3.org/documentation/document-library/extension-manuals/rt_jpgraphtutor/current/" target="_top">http://typo3.org/documentation/document-library/extension-manuals/rt_jpgraphtutor/current/</a></code></td></tr><tr><td><span class="bold"><strong>Introduction to JPGraph (Part
I)</strong></span></td><td>Basic introduction</td></tr><tr><td colspan="2">
<code class="uri"><a class="uri" href="http://www.devtutorials.info/articles/1334_Introduction_to_JPGraph__Part_I_.asp" target="_top">http://www.devtutorials.info/articles/1334_Introduction_to_JPGraph__Part_I_.asp</a></code></td></tr><tr><td><span class="bold"><strong> PHP Graphics With JpGraph
</strong></span></td><td>Downloadable tutorials</td></tr><tr><td colspan="2">
<code class="uri"><a class="uri" href="http://rosihanari.net/web-tutorial/php-graphics/" target="_top">http://rosihanari.net/web-tutorial/php-graphics/</a></code></td></tr><tr><td><span class="bold"><strong>JpGraph: PHP Graphs &amp; Charts
On-The-Fly</strong></span></td><td>Basic introduction</td></tr><tr><td colspan="2">
<code class="uri"><a class="uri" href="http://www.communitymx.com/abstract.cfm?cid=2AB8E" target="_top">http://www.communitymx.com/abstract.cfm?cid=2AB8E</a></code></td></tr><tr><td><span class="bold"><strong>Using JpGraph</strong></span></td><td>JpGraph and Cake</td></tr><tr><td colspan="2">
<code class="uri"><a class="uri" href="http://bakery.cakephp.org/articles/view/using-jpgraph" target="_top">http://bakery.cakephp.org/articles/view/using-jpgraph</a></code></td></tr><tr><td><span class="bold"><strong>Create High Quality Graphs with
Jpgraph</strong></span></td><td>Basic introduction</td></tr><tr><td colspan="2">
<code class="uri"><a class="uri" href="http://phpkitchen.com/2002/05/create-high-quality-graphs-with-jpgraph/" target="_top">http://phpkitchen.com/2002/05/create-high-quality-graphs-with-jpgraph/</a></code></td></tr><tr><td><span class="bold"><strong>JpGraph tutorial </strong></span></td><td>Integration with Prado</td></tr><tr><td colspan="2">
<code class="uri"><a class="uri" href="http://www.pradosoft.com/wiki/index.php/JpGraph_tutorial" target="_top">http://www.pradosoft.com/wiki/index.php/JpGraph_tutorial</a></code></td></tr></tbody></table>
</div></div><p><br class="table-break">
</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch01.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,72 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 2. The Short Version: Installing the library (for PHP/Apache experts)</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt01.html" title="Part I. Installing and verifying the configuring"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 2. The Short Version: Installing the library (for PHP/Apache experts)</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part I. Installing and verifying the configuring</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="chapter" title="Chapter 2. The Short Version: Installing the library (for PHP/Apache experts)"><div class="titlepage"><div><div><h2 class="title"><a name="id2475446"></a>Chapter 2. The Short Version: Installing the library (for PHP/Apache experts)</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ch02.html#id2475509">2.1. Installing</a></span></dt><dt><span class="sect1"><a href="ch02s02.html">2.2. Running the examples</a></span></dt><dt><span class="sect1"><a href="ch02s03.html">2.3. Basic trouble shooting</a></span></dt></dl></div>
<p title="What you will learn in this chapter">
<b>What you will learn in this chapter. </b>
This chapter will show you how to unpack the library and lists the minimum
prerequisites that is needed to get the library running. It is assumed that your are
familiar with adjusting the PHP configuration file <code class="filename">php.ini</code> and
that you already have a working PHP installation.
</p>
<div class="sect1" title="Installing"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2475509"></a>Installing</h2></div></div></div>
<p>Please follow the steps below:</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Either download the free library from <code class="uri"><a class="uri" href="http://jpgraph.net/download/" target="_top">http://jpgraph.net/download/</a></code>
or use your license information and download the pro-version from
<code class="uri">http://jpgraph.net/pro/login.php</code>. The download
is just a packed zip (or tar.gz) of php files. There are no automatic
installation scripts.</p>
</li><li class="listitem">
<p>Unpack the library where you normally store PHP libraries. This should
be in your PHP include path. When you unpack the library it will be
named "jpgraph-3.x" (where x corresponds to the version you have
downloaded).</p>
</li><li class="listitem">
<p>Now either rename the unpacked the directory to just jpgraph or if the
system us Unix based create a soft symbolic link, for example</p>
<p><code class="prompt">ln -s jpgraph-2.x jpgraph</code></p>
<p>This will allow you to access the library files in your own program
for with a <code class="code">require_once('jpgraph/jpgraph.php')</code></p>
</li><li class="listitem">
<p>Make sure that the GD extension is enabled in your
<code class="filename">php.ini</code> file (check the output from
<code class="code">phpinfo()</code> ) </p>
</li><li class="listitem">
<p>[Optional] Verify that the paths defined in
<code class="filename">jpg-config.inc.php</code> corresponds to the server
setup. The path to your TTF fonts must be correct. If you get an error
saying that some TTF fonts cannot be found or read then the path needs
to be adjusted in this configuration file.</p>
</li><li class="listitem">
<p>[Optional] Check that you have sufficient memory and execution time
set in your <code class="filename">php.ini</code> file. It is recommended to
allow at least 32Mb memory for PHP if you intend to run anything else
than very basic graph scripts.</p>
</li><li class="listitem">
<p>[Optional] To allow for better debugging in conjunction with graph
scripts the output buffering should also be disabled in
<code class="filename">php.ini</code></p>
</li><li class="listitem">
<p>[Optional] To avoid warning messages it might be necessary to set the
default timezone in <code class="filename">php.ini</code> if this has not already
been done. Starting with PHP 5.2 a warning is generated if the timezone
for PHP is not set.</p>
</li></ol></div><p>
</p>
<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
<p>When you install the library on a production server then you should not
install the library in the document root. Instead it should be installed so that
only the script can directly access the library files (somewhere in the PHP
path). </p>
<p>If you have the pro-version you really should install the pre-compiled version
of the library (available under directory <code class="filename">PhpExpress-src</code>.
This will significantly increase the performance of the library. The only
prerequisite is that you also need to install the (free) PhpExpress PHP
Accelerator from NuSphere Corporation. See <a class="xref" href="ch11.html" title="Chapter 11. NuSphere PHP accelerator">Chapter 11. <i>NuSphere PHP accelerator</i></a> for information on how to install the
freely available PHP Accelerator.</p>
</div>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt01.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,14 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Running the examples</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch02.html" title="Chapter 2. The Short Version: Installing the library (for PHP/Apache experts)"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Running the examples</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 2. The Short Version: Installing the library (for PHP/Apache experts)</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Running the examples"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2475669"></a>Running the examples</h2></div></div></div>
<p>The best way to verify that the installation is working is to run one of the
included example scripts. Assuming that the library is installed locally in the
document root on the HTTP server under <code class="filename">jpgraph/</code> pointing the
browser to <code class="filename">"http://localhost/jpgraph/Examples/example0.php"</code>
should show the same image as can be seen in <a class="xref" href="ch01s04.html#example.example0" title="Example 1.1. This is the very first example (example0.php)">Example 1.1. This is the very first example (<code class="filename">example0.php</code>) </a>.</p>
<p>In order to generate all the examples available there is a "meta script" that will
just do this. Point the browser to </p>
<p><code class="filename">"http://localhost/jpgraph/Examples/testsuit.php"</code></p>
<p>just note that this will generate a page with more than 300 examples. Depending on
the capacity of the server it might take a few seconds before this script is
done.</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch02.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,27 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Basic trouble shooting</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch02.html" title="Chapter 2. The Short Version: Installing the library (for PHP/Apache experts)"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Basic trouble shooting</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 2. The Short Version: Installing the library (for PHP/Apache experts)</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Basic trouble shooting"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2475716"></a>Basic trouble shooting</h2></div></div></div>
<p>If none of the examples above to work there is a couple of things that needs to be
checked. If not any of these quick fixes solves the problem then it is best to read
the long version of the installation instructions before continuing the trouble shooting.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Verify that the GD library is really working by running
<code class="code">phpinfo()</code> and check that your output includes a GD
section which should show similar information as the image below</p>
<p>
</p><div class="figure"><a name="id2475748"></a><p class="title"><b>Figure 2.1. <code class="code">phpinfo()</code> GD sections</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/phpinfo-gd.png" alt="phpinfo() GD sections"></div>
</div></div><p><br class="figure-break">
</p>
</li><li class="listitem">
<p>Make sure you have enabled strict error checking and disabled output
buffering in <code class="filename">php.ini</code>. This might not solve the
problem by itself but it will enable (better) error messages to trouble
shoot the installation.</p>
</li><li class="listitem">
<p>Make sure that you are using a recent version of PHP (e.g. ≥
PHP 5.2.x)</p>
</li><li class="listitem">
<p>Make sure that the path to the TTF directories are correctly specified
in <code class="filename">jpg-cnfig.inc.php</code></p>
</li></ol></div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch02.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,83 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 3. The Long Version: Installing the Library</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt01.html" title="Part I. Installing and verifying the configuring"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 3. The Long Version: Installing the Library</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part I. Installing and verifying the configuring</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="chapter" title="Chapter 3. The Long Version: Installing the Library"><div class="titlepage"><div><div><h2 class="title"><a name="id2475768"></a>Chapter 3. The Long Version: Installing the Library</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ch03.html#id2475830">3.1. Downloading the library</a></span></dt><dt><span class="sect1"><a href="ch03s02.html">3.2. Necessary system requirements for the library</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch03s02.html#sec.verifying-phpgd-inst">3.2.1. Verifying the PHP/GD installation</a></span></dt><dt><span class="sect2"><a href="ch03s02.html#id2476056">3.2.2. Enabling GD library in php.ini for PH5</a></span></dt><dt><span class="sect2"><a href="ch03s02.html#id2489648">3.2.3. Verifying TTF fonts</a></span></dt><dt><span class="sect2"><a href="ch03s02.html#id2490624">3.2.4. Support for different image formats</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch03s03.html">3.3. Installing the library</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch03s03.html#sec2.config-dev-server">3.3.1. Configuring JpGraph/PHP on a development server</a></span></dt><dt><span class="sect2"><a href="ch03s03.html#sec2.config-prod-server">3.3.2. Configuring JpGraph/PHP on a production server</a></span></dt><dt><span class="sect2"><a href="ch03s03.html#sec2.adjusting-php-include-path">3.3.3. Adjusting PHP include path</a></span></dt><dt><span class="sect2"><a href="ch03s03.html#id2491659">3.3.4. Using Apache2 alias configuration during development</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch03s04.html">3.4. Installing and configuring Font support</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch03s04.html#sec1.getting_add_fonts">3.4.1. Configuring TTF fonts</a></span></dt><dt><span class="sect2"><a href="ch03s04.html#sec2.using-non-latin-fonts">3.4.2. Using non-latin based fonts with JpGraph</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch03s05.html">3.5. Adapting and customizing the installation</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch03s05.html#id2492366">3.5.1. Setting up necessary paths</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch03s06.html">3.6. Verifying the library installation</a></span></dt><dt><span class="sect1"><a href="ch03s07.html">3.7. Troubleshooting the installation</a></span></dt></dl></div>
<p title="What you will learn in this chapter">
<b>What you will learn in this chapter. </b>
You will learn in detail how to configure and setup an environment to be able to
run the JpGraph library. The chapter will explain all configuration necessary in
great details and will also list some more extensive trouble shooting steps if you
encounter problems trying to get the library running. The only assumption is that
you have a working PHP installation together with your HTTP server.
</p>
<div class="sect1" title="Downloading the library"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2475830"></a>Downloading the library</h2></div></div></div>
<p>
</p><div class="variablelist"><dl><dt><span class="term">Downloading the free version</span></dt><dd>
<p>Point the browser to
<code class="filename">"http://jpgraph.net/download/"</code>
and select the 3.x series if your are running PHP5 and the 1.x
series if you are still running a PHP4 installation. </p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>The 1.x series of the library is no longer maintained so
in case you have not yet upgraded top PHP5 you should
strongly consider this.</p>
</div><p>
</p>
</dd><dt><span class="term">Downloading the pro version</span></dt><dd>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Locate your license file that was sent to you when you
purchased the library. You will need both the license
number as well as the registered license mail as stated
in the license. Your license information should look
similar to: </p>
<p>
</p><pre class="screen"><code class="computeroutput">----------------------------------------------------------
: Your license key : JPGP-0920-1234657
: Name on license : A. JpGraph User
: E-mail : jpgraph-user@example.com
----------------------------------------------------------
</code></pre><p>
</p>
</li><li class="listitem">
<p>Point the browser to
<code class="filename">http://jpgraph.net/pro/login.php</code>
and enter your licence email and key on the
website.</p>
<p>
</p><div class="figure"><a name="id2475939"></a><p class="title"><b>Figure 3.1. Pro-login dialogue on JpGraph Website</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/pro-login.jpg" alt="Pro-login dialogue on JpGraph Website"></div>
</div></div><p><br class="figure-break">
</p>
</li><li class="listitem">
<p>Depending on your system you should now download
either the 1.x or the (preferred) 3.x series. There is a
choice to either download the library as a "*.zip" file
or as a compressed "*.tar.gz" file (which is the
preferred format in a Unix environment). Save the
downloaded file to a temporary directory of your
choice.</p>
</li><li class="listitem">
<p>[Optional] Verify your downloaded file against the
given MD5 sum on the website. On a Unix system this can
be done by running the <span class="command"><strong>md5</strong></span> program
and give the downloaded library as the argument.</p>
<p>For example: <code class="prompt">$&gt;</code>
<span class="command"><strong>md5</strong></span>
<code class="filename">jprgaph-3.0.0p.tar.gz</code></p>
</li><li class="listitem">
<p>Unpack the library to a suitable directory that is in
your PHP include path as is described in <a class="xref" href="ch03s03.html" title="Installing the library">Installing the library</a></p>
</li></ol></div><p>
</p>
</dd></dl></div><p>
</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt01.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

File diff suppressed because one or more lines are too long

View File

@ -0,0 +1,444 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Installing the library</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch03.html" title="Chapter 3. The Long Version: Installing the Library"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Installing the library</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 3. The Long Version: Installing the Library</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Installing the library"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec1.installing-library"></a>Installing the library</h2></div></div></div>
<p>When you have verified the necessary preconditions as described in the previous
paragraphs it is time to install the library. The "installing" part is nothing more
than copying the files in the distribution to a place in the directory structure
where you script can find the library files. On a Unix system it is common to
install PHP libraries under "<code class="filename">/usr/share/php/</code>". On a windows
system there is really no standard path for installing PHP libraries so you have to
decide your self. </p>
<p>The important thing here is that the path to the library is included in the PHP
search path, i.e. it is in one of the paths that PHP searches when it tries to
resolve a "<code class="code">require_once</code>" or "<code class="code">include</code>" statements.
Furthermore, the included examples and demo applications (included in the pro
version) assumes that the library is installed under the directory
"<code class="filename">jpgraph/</code>".</p>
<p>As an example the following commands will install a specific version of the
library on a Unix server. If we assume that you have downloaded the library to the
"<code class="filename">/tmp/</code>" directory and are already standing in this
directory the following commands will setup the library to be used</p>
<p>
</p><pre class="screen">root:/tmp&gt; tar xzf jpgraph-2.5.tar.gz
root:/tmp&gt; cp -r jpgraph-2.5 /usr/shar/php/
root:/tmp&gt; ln -s /usr/shar/php/jpgraph-2.5 /usr/shar/php/jpgraph</pre><p>
</p>
<p>The last line makes a symbolic link from "jpgraph" to the actual version of the
library. This way you can try out different versions of the library without having
to make any changes in your scripts. You just point out a different version of the
library in the symbolic link.</p>
<div class="sect2" title="Configuring JpGraph/PHP on a development server"><div class="titlepage"><div><div><h3 class="title"><a name="sec2.config-dev-server"></a>Configuring JpGraph/PHP on a development server</h3></div></div></div>
<div class="sect3" title="Setting up your php.ini file"><div class="titlepage"><div><div><h4 class="title"><a name="sec3.setting-up-php-ini"></a>Setting up your php.ini file</h4></div></div></div>
<p>
</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
<p>To find the location of your <code class="filename">php.ini</code> file
create and run a script with the single line <code class="code">&lt;?php
phpinfo(); ?&gt;</code> . The look at the output for a line saying
"php.ini file used" and you will see which
<code class="filename">php.ini</code> file is used.</p>
</div><p>
</p>
<p><span class="bold"><strong>Setting the memory limits</strong></span></p>
<p>In many default configuration the allowed memory for PHP is not enough for
complex graph script since they (as many other image manipulation programs)
can require a lot of memory. On a development server there should be at
least 32MB memory allowed for the HTTP/PHP process. To verify this do the
following</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Open <code class="filename">php.ini</code> for editing.</p>
</li><li class="listitem">
<p>Locate the line saying</p>
<p><code class="code">memory_limit = xx</code></p>
<p>where "xx" is some number. Now make sure that you have at
least 32MB allowed by making sure the line reads</p>
<p><code class="code">memory_limit = 32M</code></p>
<p>Note that fore very large images this might not be enough.
Consider the following example.</p>
<p>Assume you need to create an 1200x1024 image in true color.
Just the plain image in itself will require 1200x1020x4 bytes,
which is roughly 4.7MB RAM during internal processing the
library can need up to three times that amount of memory so this
means that just for the image the library needs around of ~15MB
of RAM. If we then take the memory needed to load PHP as well as
the entire JpGraph library and dynamically execute and parse the
library it can easily consume another ~15MB RAM. If the image is
very complex and requires a huge number of objects to be created
(a typical example is a large Gantt chart) it might be necessary
to double the allowed memory to 64MB RAM. </p>
</li></ol></div><p>
</p>
<p></p>
<p><span class="bold"><strong>Setting maximum allowed run time</strong></span></p>
<p>By default many installations have very short maximum run time for the PHP
scripts. Common figures are 10s. For normal interactive use involving plain
text processing this is usually adequate. However, producing large and
complex images might take considerable time (as do all images processing).
For this reason the maximum time limit for PHP should be increased to a
minimum of 20s (depending on the complexity of your images as well as any
associated data processing it might be necessary to allow up to
30-40s).</p>
<p>The allowed running time is controlled by the <code class="filename">php.ini</code>
setting</p>
<p><code class="code">max_execution_time = xx</code></p>
<p>where "xx" is some number. Recommended setting is therefore </p>
<p><code class="code">max_execution_time = 30</code></p>
<p></p>
<p><span class="bold"><strong>Disabling output buffer</strong></span></p>
<p>The next part of the <code class="filename">php.ini</code> file that might need
changing is the output buffer. In short this should be disabled and we will
shortly explain why. To check this do the following</p>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Open <code class="filename">php.ini</code> for editing</p>
</li><li class="listitem">
<p>Locate the line saying </p>
<p><code class="code">output_buffering = xx</code></p>
<p>where "xx" is some number. Make sure that this line is
commented out, i.e. it reads</p>
<p><code class="code">; output_buffering = xx</code></p>
</li></ol></div><p>This reason we want this to be commented out is that during
development we want to be able to see the potential error messages produced
by the library and having the output buffering enabled will actually prevent
this. Fully understanding why this is the case is good first step into the
added complexity of producing images with PHP compared with just outputting
text. Understanding this requires us to understand a few basic principles
about the HTTP protocol. Especially how MIME encodings of data works.</p>
<p>The following explanation is slightly simplified since a full description
of the HTTP protocol would bring us a bit to far in this manual</p>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>A client (e.g. browser) requests data from the server by
issuing a GET (or possible a POST) command to the server. This
is what happens when you enter a URI i the address bar in the
browser.</p>
</li><li class="listitem">
<p>The server replies with a data stream (or an error if the
requested data wasn't available). This data stream is prepended
with header (MIME header) that tells the client (e.g. the
browser) how to interpret the data that follows. The most common
type (and the default type if no header is sent by a faulty
server) is "text/html" . This tells the client to interpret the
data as plain text with embedded HTML encoding. </p>
<p>When the data is to be interpreted as an image the header will
instead be one of the image headers, for example
<code class="code">"image/png"</code> or <code class="code">"image/jpeg"</code>. When
the client receives this header it will Interpret all the
following data as an image encoded in the indicated format. </p>
<p>The important thing to keep in mind here is that each server
reply can have one and only one MIME type. This is the key to
further understanding the specific issues with dynamic image
generation. This explains why if a PHP script running on the
server sends a header first indicating that the following data
it sends should be interpreted by the client as an image it
cannot send both image data and some text.</p>
</li></ol></div><p>We are now in a position to explain how output buffering would
make debugging more difficult.</p>
<p>Normally all output from a PHP script is sequentially, i.e. the header
must first be sent and then the data. If no header is sent or plain text is
sent without a header the client will interpret this as
<code class="code">"text/html"</code>. One purpose with "output_buffer" it to
circumvent this to allow a certain amount of output to be put in a buffer
for a while and later when some processing has determined what header should
be sent the data is prepended with the correct header and the rest of the
data is then sent. </p>
<p>What could now happen is the following (not unlikely scenario): </p>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>The scripts starts executing and the image starts to be
build.</p>
</li><li class="listitem">
<p>Your script has some minor issues which produces some warnings
from PHP. These warning does not get sent directly back to the
client (the browser) to allow you to act on these warnings
instead they will be put into the output buffer. When later the
scripts starts outputting the proper image header and the image
data it gets added to the output buffer where your previous
textual PHP warning already are stored. </p>
</li><li class="listitem">
<p>Your client now receives the header that indicates that the
following data should be interpreted as an image but since that
image data is mixed with the textual warning messages it will
fail to decode the data (since it is not proper image data) and
will typical just show the image as a square with a red-cross
(FireFox) or some message along the lines of "<span class="italic">Cannot decode image</span>". This is all
depending on how a certain client handles a corrupt
image.</p>
</li></ol></div><p>The above scenario makes it impossible to debug your script
since it will give no clue to what caused or where in your script these
warnings were generated. The way to counteract this scenario is to disable
output buffering. In this way the warning will be sent back to the client as
soon as they are generated by PHP and will allow you to act on them. </p>
<p></p>
<p><span class="bold"><strong>Enabling adequate error checking</strong></span></p>
<p>The final part of the <code class="filename">php.ini</code> file that should be
adjusted (and this is not only for the JpGraph library) is the error level.
To ensure maximum interoperability of the developed scripts they should all
run completely silent no matter what error levels are set on the server.
This means that development of all scripts should always be done with
maximum error checking enabled. The JpGraph library can safely run
completely silent even when all error checking is enabled.</p>
<p>The error checking should therefore be specified as</p>
<p><code class="code">error_reporting = E_ALL | E_STRICT</code></p>
<p>to enable the highest degree of PHP error checking</p>
<p></p>
<p>
</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
<p>In addition to the above setting it is a good idea to also to
makes sure that the following options are set</p>
<p><code class="code">zend.ze1_compatibility_mode = Off</code></p>
<p>Zend engine 1 compatibility might cause problems with the
library</p>
<p><code class="code">implicit_flush = On</code></p>
<p>This can reduce the performance and shouldn't be used on a
production server but will make all outputs sent back to the client
as soon as possible and will aid in debugging.</p>
<p><code class="code">allow_call_time_pass_reference = Off</code></p>
<p>This is just a general good idea since call time pass references
is deprecated in PHP 5.0 and higher</p>
<p><code class="code">display_errors = On</code></p>
<p>This makes sure all error are displayed</p>
<p><code class="code">display_startup_errors = On</code></p>
<p>This makes sure that any initial errors thrown by PHP will be
reported</p>
</div><p>
</p>
<p><span class="bold"><strong>Setting default timezone</strong></span></p>
<p>Starting with PHP 5.2 a warning will now be generated unless a default
time zone is explicitly specified in <code class="filename">php.ini</code>. To set
this find the line <code class="code">date.timezone</code> in the
<code class="code">[Date]</code>section and set this to valid zone. For example to
specify GMT+1 one could specify</p>
<p><code class="code">date.timezone = Europe/Paris</code></p>
<p>Note: There should be no citation signs around the time zone.</p>
<p>
</p><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3>
<p>In order to use the LED module (See <a class="xref" href="ch17.html#sec.led-graph-type" title="LED bill boards">LED bill boards</a>) the PHP installation must
have multi-byte strings enabled so that the function
<span class="command"><strong>mb_strlen()</strong></span> is available. This is normally
enabled at compile time for PHP by specifying the options
<code class="code">--enable-mbstring --enable-mbregex</code> when configuring
the compile options.</p>
</div><p>
</p>
<p>
</p><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3>
<p>In order to use the PDF417 barcode module (See <a class="xref" href="ch25.html" title="Chapter 25. PDF417 (2D-Barcode)">Chapter 25. <i>PDF417 (2D-Barcode)</i></a>) it is necessary for the PHP
installation to support the function <span class="command"><strong>bcmod()</strong></span>.
This is enabled when compiling PHP by making sure that the option
<code class="code">--enable-bcmath</code> is given when configuring PHP at
compile time.</p>
</div><p>
</p>
</div>
<div class="sect3" title="Setting up your jpg-config.inc.php"><div class="titlepage"><div><div><h4 class="title"><a name="id2491276"></a>Setting up your jpg-config.inc.php</h4></div></div></div>
<p>Apart from the standard configuration described in <a class="xref" href="ch03s04.html" title="Installing and configuring Font support">Installing and configuring Font support</a> and <a class="xref" href="ch03s05.html" title="Adapting and customizing the installation">Adapting and customizing the installation</a> there is only one important
configuration that is specific for a development server and that is the
localization setting for error messages. </p>
<p>As of version 3.0.0 there are three localization options</p>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>English error messages ("en")</p>
</li><li class="listitem">
<p>German error messages ("de")</p>
</li><li class="listitem">
<p>Production error messages ("prod"). This is not really a
localization but a different set of error messages which does
not give detailed error messages but a generic message suitable
for a production server where the end user is not helped by
detailed graph script errors. Instead a generic message is shown
together with an error code that corresponds to the detailed
error. ("prod")</p>
</li></ol></div><p>In order to specify the error message localization the
following define in <code class="filename">jpg-config.inc.php</code> must be set the </p>
<p><code class="code">define('DEFAULT_ERR_LOCALE','en');</code></p>
<p>The possible options are</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>"en", English locale</p>
</li><li class="listitem">
<p>"de", German locale</p>
</li><li class="listitem">
<p>"prod", The production version of the error messages.</p>
</li></ol></div><p>
</p>
<p>
</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
<p>In addition to specifying the locale in the
<code class="filename">jpg-config.inc.php</code> file it can also be
specified dynamically in each script by calling</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">JpGraphError::SetErrLocale($aLocale);</span></pre></td></tr></table></div><p>
</p>
</div><p>
</p>
</div>
</div>
<div class="sect2" title="Configuring JpGraph/PHP on a production server"><div class="titlepage"><div><div><h3 class="title"><a name="sec2.config-prod-server"></a>Configuring JpGraph/PHP on a production server</h3></div></div></div>
<div class="sect3" title="Setting up your php.ini file"><div class="titlepage"><div><div><h4 class="title"><a name="id2491419"></a>Setting up your php.ini file</h4></div></div></div>
<p>Apart from what is applicable to a development server as described in <a class="xref" href="ch03s03.html#sec2.config-dev-server" title="Configuring JpGraph/PHP on a development server">Configuring JpGraph/PHP on a development server</a> the following changes should be
considered in a production environment.</p>
<p>
<span class="bold"><strong>Setting the memory limits</strong></span>
</p>
<p>The one thing to keep in mind here is that each active connection will
spawn a unique PHP instance (HTTP process). This means that the memory limit
set per PHP process can cause a very high memory demand on a busy server
with many simultaneous connections. For this reason it is important that
during system test (before going into production) the actual needed memory
limit is determined. </p>
<p>For a busy server it is not uncommon to dimension it so it can handle 100
simultaneous connections. If the limit of r each PHP process is set to 32MB
this means that the server needs at least ~3.2GB memory just to handle the
PHP processes (if they are all using there maximum allowed memory).</p>
<p>
<span class="bold"><strong>Setting maximum allowed run time</strong></span>
</p>
<p>The same principle applies to a the allowed run time. For a production
server with high load and many simultaneous users it might be necessary to
increase the maximum allowed execution time just to be sure no process is
terminated due to it reaching its maximum allowed run time. When that
happens the PHP process will be killed an no output sent back to the client
(e.g. the browser).</p>
<p>
<span class="bold"><strong>Disabling output buffer</strong></span>
</p>
<p>The output buffer should be disabled on the production server as well
since enabling this will slow down the PHP and put a higher demand on the
memory requirements.</p>
<p>
<span class="bold"><strong>Enabling adequate error checking</strong></span>
</p>
<p>On a production server it is not a good idea to display all PHP error
messages to the end user so the display of error messages should be disabled
and the error messages should only be logged to a file.</p>
<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
<p> On a production server it is also a good to idea to have the
following settings: </p>
<p>
<code class="code">display_errors = Off</code>
</p>
<p>This makes sure that now PHP errors are displayed</p>
<p>
<code class="code">display_startup_errors = Off</code>
</p>
<p>This makes sure that any initial errors thrown by PHP is not displayed
to the end user</p>
<p><code class="code">log_errors = On</code></p>
<p><code class="code">error_log = &lt;name-of-log-file&gt;</code></p>
<p>This makes sure all server PHP errors are logged to a specified
file</p>
</div>
</div>
<div class="sect3" title="Setting up your jpg-config.inc.php"><div class="titlepage"><div><div><h4 class="title"><a name="id2491421"></a>Setting up your <code class="filename">jpg-config.inc.php</code></h4></div></div></div>
<p>On a production server it is best not to show detailed error messages to
an end user. Instead it is better to have a generic error message that
indicates a server problem and give an error code which can be decoded by
looking it up in the table in <a class="xref" href="aph.html" title="Appendix H. Error messages">Appendix H. <i>Error messages</i></a> Using a generic error message is achieved by
setting the following define:</p>
<p><code class="code">define('DEFAULT_ERR_LOCALE','prod');</code></p>
</div>
</div>
<div class="sect2" title="Adjusting PHP include path"><div class="titlepage"><div><div><h3 class="title"><a name="sec2.adjusting-php-include-path"></a>Adjusting PHP include path</h3></div></div></div>
<p>As was mentioned before the library should be installed somewhere in the PHP
include path. There are two ways of configuring the include path:</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>setting the include path in <code class="filename">php.ini</code></p>
<p><code class="code">include_path = &lt;file-path&gt;</code></p>
</li><li class="listitem">
<p>adjusting the include path directly in the code by using the PHP
command <code class="code">php_ini_set()</code> at the top of the script</p>
</li></ol></div><p>
</p>
<p>The library examples assume that the library is available under a directory
called "<code class="filename">jpgraph/</code>" . This will allow the scripts to include
the library files by, for example, writing "<code class="code">include</code>" or
"<code class="code">require_once</code>" statements such as </p>
<p><code class="code">require_once( 'jpgraph/jpgraph.php')</code></p>
</div>
<div class="sect2" title="Using Apache2 alias configuration during development"><div class="titlepage"><div><div><h3 class="title"><a name="id2491659"></a>Using Apache2 alias configuration during development</h3></div></div></div>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>This section only discusses alias setting using the Apache HTTP server
so this section can be skipped at first time reading the manual without
loss of continuation.</p>
</div><p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>More detailed information on the alias directive is also available in
the official Apache documentation at <code class="uri"><a class="uri" href="http://httpd.apache.org/docs/2.2/mod/mod_alias.html#alias" target="_top">http://httpd.apache.org/docs/2.2/mod/mod_alias.html</a></code></p>
</div><p>
</p>
<p>When accessing examples and test code through a regular bowser during
development the scripts must be available in document root (or somewhere beneath
that root) the root is traditionally named <code class="code">/htdocs</code>. Having a
development code/repository directly under this root directory is not a good
idea. For example, write access to a document root (even on a development
server) should be restricted, in addition the paths given to a test team should
be the same whatever version is currently under test so storing different
versions with different names under the root is also a poor setup.</p>
<p>A much better and easy, approach is to use the powerful concept of alias in
Apache. This is a way of mapping a URL to a specific directory on the server.
For example if <code class="uri"><a class="uri" href="http://www.eclipse.org/projects/project-plan.php?projectid=tools.pdt" target="_top">Eclipse-PDT</a></code>
is used as an IDE to develop PHP it is mandatory to have a workspace setup where
all the working files resides. Assuming that a local developer has his workspace
directly in his home directory, say <code class="filename">~joe/workspace</code>, we
could configure an alias so that the workspace is accessible by the alias
"<code class="filename">http://localhost/ws/</code>" by adding the following
configuration in the Apache setup file(s)</p>
<div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">Alias /ws /home/joe/worksapce
&lt;Directory /home/joe/workspace&gt;
Order allow,deny
Allow from all
&lt;/Directory&gt;</span></pre></td></tr></table></div>
<p>In this particular setup we use very liberal settings, allowing basically
everyone with server access to access the directory. Using this approach makes
it very easy to use the same test setup but allow testing of different
branches/versions of the code.</p>
<p>Depending on the system these configurations can reside in different places.
However, a very common structure is to keep all these small configuration files
under <code class="filename">/etc/apache/conf.d/</code> The main Apache configuration
then reads all the files (regardless of there name) that are stored under this
directory. </p>
<p>As a final example we show a further slightly more complex example (which
actually shows how most of our developers have there systems setup for PHP5
development). This example adds options to do directory listing and allows the
server to follow symbolic links. More information on available argument for the
directive option is available in the official Apache documentation <code class="uri"><a class="uri" href="http://httpd.apache.org/docs/2.2/mod/core.html#options" target="_top">http://httpd.apache.org/docs/2.2/mod/core.html#options</a></code></p>
<p>
</p><div class="example"><a name="id2491770"></a><p class="title"><b>Example 3.5. Alias configuration for a development server running Apache with
Eclipse-PDT</b></p><div class="example-contents">
<div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code"># Configuration for Eclipse workspace
#
&lt;IfModule mod_php5.c&gt;
Alias /ws/ /home/joe/workspace/
&lt;Directory /home/joe/workspace/&gt;
Options +Indexes +Multiviews +FollowSymLinks
order allow,deny
allow from all
&lt;/Directory&gt;
&lt;/IfModule&gt;</span></pre></td></tr></table></div>
</div></div><p><br class="example-break">
</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch03.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,178 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Installing and configuring Font support</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch03.html" title="Chapter 3. The Long Version: Installing the Library"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Installing and configuring Font support</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 3. The Long Version: Installing the Library</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Installing and configuring Font support"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec1.installing-fonts"></a>Installing and configuring Font support</h2></div></div></div>
<p>JpGraph supports two types of fonts, bitmap and TTF fonts. The advantage with
bitmap fonts are that they are supported from within the library without further
configuration. TTF fonts require some configuration and possible installation of the
actual TTF font specification file. (For more on installing TTF fonts see <a class="xref" href="ch03s04.html#sec1.getting_add_fonts" title="Configuring TTF fonts">Configuring TTF fonts</a>.) </p>
<p>The drawbacks, on the other hand, with bitmap fonts are quite a few</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p>they look quite crude and are only available in a few sizes</p>
</li><li class="listitem">
<p>italic font style is not supported for bitmap fonts</p>
</li><li class="listitem">
<p>they only support 7-bit ASCII characters</p>
</li><li class="listitem">
<p>they only support 0 and 90 degree rotated text</p>
</li></ul></div><p>
</p>
<p>You can read more about how to use and select among the different fonts in <a class="xref" href="ch08.html" title="Chapter 8. Text and font handling">Chapter 8. <i>Text and font handling</i></a></p>
<div class="sect2" title="Configuring TTF fonts"><div class="titlepage"><div><div><h3 class="title"><a name="sec1.getting_add_fonts"></a>Configuring TTF fonts</h3></div></div></div>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>This could be considered an optional section since the library will
work even without TTF fonts. However, for th reasons listed previously
it is strongly recommended that TTF support is configured.</p>
</div><p>
</p>
<p>In the following we will assume that the FreeType library is enabled and
verified in the PHP installation (See <a class="xref" href="ch03s02.html#fig.phpinfo-gd" title="Figure 3.2. phphinfo() GD-Information">Figure 3.2. phphinfo() GD-Information</a>)</p>
<p>Due to various legal issues no TTF fonts are included in the distribution of
JpGraph since many commonly used TTF font files are copyrighted and there
distribution restricted. For the most commonly used WEB-fonts (the Microsoft
Core Fonts) the status is unclear. For many years Microsoft distributed them
freely but they are no longer available from Microsofts home page. Instead they
are available from <code class="uri"><a class="uri" href="http://corefonts.sourceforge.net/" target="_top">http://corefonts.sourceforge.net/</a></code>
</p>
<p>There are however a fair amount of freely available high quality TTF fonts
(see below). The first thing needed is to make sure that the path defines in the
file <code class="filename">jpg-config.inc.php</code> corresponds to the server setup (so
that the library can find the font files)</p>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Open <code class="filename">jpg-config.inc.php</code> for editing</p>
</li><li class="listitem">
<p>Locate the define <code class="code">TTF_DIR</code> (this is the define that
possible needs updating depending on your system). By default this path
will have a sensible values depending on if the library is installed on
a Windows or a Unix system.</p>
</li><li class="listitem">
<p>If you are on a Windows platform you can just point the TTF directory
path in JpGraph to use the standard Window font directory (e.g
<code class="filename">C:\windows\fonts\</code>)</p>
</li><li class="listitem">
<p>If you are on a Unix platform, which may not have any TTF fonts
installed, you can download and install the core MS WEB-initiative fonts
from <code class="uri"><a class="uri" href="http://corefonts.sourceforge.net/" target="_top">http://corefonts.sourceforge.net/</a></code>
many Linux distributions also have automatic ways to install these
fonts. These fonts were put in the public domain by the Microsoft
Corporation but they are no longer available directly from
Microsoft.</p>
</li><li class="listitem">
<p>You can also chose to install the freely available Vera Bitstream TTF
fonts available from <code class="uri"><a class="uri" href="http://www.gnome.org/fonts/" target="_top">http://www.gnome.org/fonts/</a></code></p>
</li><li class="listitem">
<p>You can also chose to install the freely available DejaVu TTF fonts <code class="uri"><a class="uri" href="http://sourceforge.net/projects/dejavu/" target="_top">http://sourceforge.net/projects/dejavu</a></code></p>
</li></ol></div>
<p>JpGraph uses a standard naming convention for the TTF font files in order to
be able to find the correct font file that correspond to a particular font
family. This naming convention follows the standard naming of the available font
files from the distributions listed above. </p>
<p>If the installation of the library is made on a computer running MS Windows
then it is recommended to use the already available font files in Windows
(usually located in <code class="filename">C:\WINDOWS\FONTS</code>). </p>
<p>If the installation is made on a UNIX derivate running X11 then the font
location can differ between versions and UNIX brands. One commonly used path in
modern installations are "<code class="filename">/usr/share/fonts/truetype/</code>" (In
older installations it was common to put the truetype fonts under
"<code class="filename">/usr/X11R6/lib/X11/fonts/truetype/</code>".)</p>
<p>Finally we note that it is possible to install additional fonts not natively
supported by the library by using the <code class="code">SetUserFont()</code> family of
methods. (In theory it is also possible to patch the jpgraph source files to
include support for other font files natively but since this requires code
modifications of the library we do not discuss this further here in the
introduction.)</p>
<p>Freely available TTF fonts can be found, for example, from</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="uri"><a class="uri" href="http://www.webfontlist.com" target="_top">http://www.webfontlist.com</a></code></p>
</li><li class="listitem">
<p><code class="uri"><a class="uri" href="http://www.webpagepublicity.com/free-fonts.html" target="_top">http://www.webpagepublicity.com/free-fonts.html</a></code></p>
</li><li class="listitem">
<p><code class="uri"><a class="uri" href="http://www.fontonic.com/fonts.asp?width=do&amp;offset=120" target="_top">http://www.fontonic.com/fonts.asp?width=do&amp;offset=120</a></code></p>
</li><li class="listitem">
<p><code class="uri"><a class="uri" href="http://www.fontspace.com/category/famous" target="_top">http://www.fontspace.com/category/famous</a></code></p>
</li></ul></div><p>
</p>
</div>
<div class="sect2" title="Using non-latin based fonts with JpGraph"><div class="titlepage"><div><div><h3 class="title"><a name="sec2.using-non-latin-fonts"></a>Using non-latin based fonts with JpGraph</h3></div></div></div>
<p>In addition to European fonts it is also possible to use non-latin based fonts
such as Cyrillic, Japanese, Chinese, Hebrew and Greek. For any of these
languages a suitable TTF font that supports the non-latin based language must be
made available to the library. Some specific rules also applies to each of the
supported languages due to the necessary character encoding needed due to
different convention when writing the character for some languages. </p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p>For Cyrillic support the define <code class="code">LANGUAGE_CYRILLIC</code> in
<code class="filename">jpg-config.php</code> must be set to
<code class="code">true</code>. It is then possible to use a suitable
Cyrillic font as replacement of the ordinary font. This setting
combined with the <code class="code">CYRILLIC_FROM_WINDOWS</code> and
<code class="code">LANGUAGE_CHARSET</code> is used to fine tune the handling
cyrillic input. The rules are as follows:</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>If <code class="code">LANGUAGE_CYRILLIC</code> is <span class="bold"><strong>false</strong></span> no specific handling of
Cyrillic characters at all will be done.</p>
</li><li class="listitem">
<p>If <code class="code">CYRILLIC_FROM_WINDOWS</code> is <span class="bold"><strong>true</strong></span> then it will be assumed
the input coding by default is encoded using <span class="bold"><strong>WINDOWS-1251</strong></span>. </p>
<p>The conversion is then done via a call to
<code class="code">convert_cyr_string($aTxt, 'w', 'k')</code>
where <code class="code">$aTxt</code> is replaced with the input
string to be encoded.</p>
</li><li class="listitem">
<p>If <code class="code">CYRILLIC_FROM_WINDOWS</code> is <span class="bold"><strong>false</strong></span> then it will be assumed
the input coding by default is encoded using <span class="bold"><strong>KOI8-R</strong></span>.</p>
<p>The conversion is then done via the sequence of
callls</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-var">$isostring</span><span class="hl-code"> = </span><span class="hl-identifier">convert_cyr_string</span><span class="hl-brackets">(</span><span class="hl-var">$aTxt</span><span class="hl-code">, </span><span class="hl-quotes">&quot;</span><span class="hl-string">k</span><span class="hl-quotes">&quot;</span><span class="hl-code">, </span><span class="hl-quotes">&quot;</span><span class="hl-string">i</span><span class="hl-quotes">&quot;</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$unistring</span><span class="hl-code"> = </span><span class="hl-identifier">LanguageConv</span><span class="hl-code">::</span><span class="hl-identifier">iso2uni</span><span class="hl-brackets">(</span><span class="hl-var">$isostring</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div><p>
</p>
<p>in oder to get a proper utf-8 internal encoding
(internally the library only uses utf-8 encoding)</p>
</li><li class="listitem">
<p><code class="code">LANGUAGE_CHARSET</code> can be used to
dynamically adjust the conversion of the input character
set when using cyrillic characters. This constant is
used to auto-detect whether cyrillic conversion is
really necessary if enabled (via the If
<code class="code">LANGUAGE_CYRILLIC</code>=true) . This constant
can be set to a variable containing the currently used
character input set .A typical such string would be
'UTF-8' or 'utf-8' (the comparison is case-insensitive).
If this charset is not 'koi8-r' nor 'windows-1251'
derivate then no conversion is done. </p>
</li></ol></div><p>
</p>
<p></p>
</li><li class="listitem">
<p>For Chinese character set JpGraph supports both BIG5 and GB2312
encoding. For BIG5 encoding the PHP installation must have support
for the "<code class="code">iconv()</code>" function. Furthermore the define
<code class="code">CHINESE_TTF_FONT</code> must be set to the name of the
Chinese BIG5 font that is to be used. By default this is set to
"<code class="filename">bkai00mp.ttf</code>". To use the Chinese BIG5
font in the scripts one must then specify the font family as
<code class="code">FF_CHINESE</code>.</p>
<p>To use the alternative font files
"<code class="filename">simsun.ttc</code>" and
"<code class="filename">simhei.ttf</code>" (which uses the GB2312
encoding) the only step needed is to install those fonts in the
normal TTF font directory and then specify the font family as
<code class="code">FF_SIMSUN</code>, the "<code class="filename">simhei.ttf</code>" is
used when the font style is specified as
<code class="code">FS_BOLD</code>.</p>
</li></ul></div><p>
</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch03.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,42 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Adapting and customizing the installation</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch03.html" title="Chapter 3. The Long Version: Installing the Library"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Adapting and customizing the installation</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 3. The Long Version: Installing the Library</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Adapting and customizing the installation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec1.adapting-installation"></a>Adapting and customizing the installation</h2></div></div></div>
<p>All configuration of the library is done in the file
<code class="filename">jpg-config.inc.php</code>. Each option in the file is extensively
documented in <a class="xref" href="apl.html" title="Appendix L. The JpGraph configuration file">Appendix L. <i>The JpGraph configuration file</i></a> Here we will only cover the most important
configuration that it likely to have to be customized in order to successfully run
the library.</p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>All configuration settings comes with default values that should in normal
cases be enough for a "standard" system. However for a production system you
might want to fine tune this according to your specific system setup.</p>
</div><p>
</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
<p>During development (and to some extent even on a production server) it
might be necessary to adjust some parameters in your
<code class="filename">php.ini</code> file. For more on this see <a class="xref" href="ch03s03.html" title="Installing the library">Installing the library</a></p>
</div><p>
</p>
<div class="sect2" title="Setting up necessary paths"><div class="titlepage"><div><div><h3 class="title"><a name="id2492366"></a>Setting up necessary paths</h3></div></div></div>
<p>There are three categories of directory paths that can be specified. The
categories are:</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Font directories, this we already touched upon in <a class="xref" href="ch03s04.html#sec1.getting_add_fonts" title="Configuring TTF fonts">Configuring TTF fonts</a>. </p>
</li><li class="listitem">
<p>Cache directory, the cache feature of the library is extensively
discussed in <a class="xref" href="ch09.html" title="Chapter 9. Using the JpGraph cache system">Chapter 9. <i>Using the JpGraph cache system</i></a>. The important thing to notice
here is that whatever directory you chose to use as a cache
directory it must be a directory that is writable for the process
running PHP (normally the HTTP server process, e.g. Apache)</p>
</li><li class="listitem">
<p>CSIM Cache directory (if CSIM cache feature is used). CSIM stands
for Client Side Image Maps and is a way to construct client side
drill down charts. (Today this is the only inpractice used image
mapping method but it is also possible to have Server Side Image
Maps).</p>
</li></ol></div><p>
</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch03.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,30 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Verifying the library installation</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch03.html" title="Chapter 3. The Long Version: Installing the Library"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Verifying the library installation</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 3. The Long Version: Installing the Library</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Verifying the library installation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2492431"></a>Verifying the library installation</h2></div></div></div>
<p>After installing the library a good check that everything works is to run the
included example scripts. Worth noting is that some of the examples uses TTF fonts.
This means that if you try to run those examples on an installation that does not
have any TTF fonts configured an error message will be displayed.</p>
<p><span class="bold"><strong>Running your first example</strong></span></p>
<p>If we assume that you have installed the library directly under the document root
on the HTTP server in a directory named "<code class="code">jpgraph/</code>" you can access the
examples in the "<code class="filename">jpgraph/Examples/</code>" directory by pointing your
browser for example to "<code class="filename">jpgraph/Examples/example0.php</code>" . This
should then show the same image as is displayed in <a class="xref" href="ch01s04.html#fig.example0" title="Figure 1.2. This is the very first example (example0.php)">Figure 1.2. This is the very first example <code class="uri"><a class="uri" href="example_src/example0.html" target="_top">(<code class="filename">example0.php</code>)</a></code> </a></p>
<p>If the above example works correctly you can run all the included examples by
pointing the browser to the script
"<code class="filename">jpgraph/Examples/testsuit.php</code>". This will automatically
generate all non-CSIM examples (for an explanation of CSIM graphs see ??) and show
them in one long list. Note that since this has more than 300 images it can take
some time to generate all example images.</p>
<p>
</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
<p>In order to generate all CSIM examples you can run the testsuit with the
URL argument <code class="code">?type=2</code></p>
<p><code class="code">jpgraph/Examples/testsuit.php?type=2</code></p>
<p>You will then get a number of examples of so called drill-down charts
where a number of areas of the graphs a re hotspots which can be clicked to
open a specified URL. However, in these examples all the click-URL have just
dummy values which points back to the same file.</p>
</div><p>
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch03.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,122 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Troubleshooting the installation</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch03.html" title="Chapter 3. The Long Version: Installing the Library"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Troubleshooting the installation</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 3. The Long Version: Installing the Library</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Troubleshooting the installation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2492535"></a>Troubleshooting the installation</h2></div></div></div>
<p>Unfortunately there are many parameters in a server installation that may affect
the execution of PHP so the steps below can only give some indications of how to
further investigate some potential problems.</p>
<p>Experience shows that most of the trouble are caused by either an old buggy
version of the free-type TTF library or using an old antiquated version of the GD
library. So before starting trouble shooting the scripts please make sure that you
have an up to date PHP installation with the bundled version of the GD library (as
describe in the previous sections) and a working FreeType library installed.</p>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p><span class="bold"><strong>No image is displayed.</strong></span></p>
<p>The first thing you should do is to isolate the problem by calling
your graph script directly in the browser. There are then two variants
of this problem. </p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem">
<p>No data is sent back from the server.</p>
<p>You can verify this by calling your graph script directly
in the browser and then check the source (click "view
source" menu item in the browser). If this is a truly blank
image then no data was sent back from the browser.</p>
<p>This means that the PHP process has been terminated
prematurely before it could send any data back. This could
be caused by either the PHP process crashing (due to a bug
in either PHP or your HTTP server) or the HTTP server
crashed. This is often due to a broken PHP installation and
more than often a problem with the True Type libraries. </p>
<p>It could also be caused by the PHP script running longer
than the maximum allowed execution time (as specified in
<code class="filename">php.ini</code>). The first thing you
should do is to increase the maximum allowed execution time.
If this does not solve the problem you should look in the
log files for both your HTTP server and PHP to try to find
clues to if the PHP process really crashed. Another
possibility is that the PHP process uses more than the
maximum allowed memory (as set in
<code class="filename">php.ini</code>) and then it is terminated.
So a good first step is to put some really high values for
memory and time just to take away these parameters.</p>
</li><li class="listitem">
<p>The data sent back is corrupt.</p>
<p>Depending on your browser this can show up differently but
a common symptom is a "red X" in the browser. In order to
debug this you should make sure that you have followed the
steps in <a class="xref" href="ch03s03.html#sec2.config-dev-server" title="Configuring JpGraph/PHP on a development server">Configuring JpGraph/PHP on a development server</a> to make sure you
have output buffering disabled and have maximum error
checking enabled in PHP. The most common cases for this type
of problem is having enabled output buffering and some minor
errors in the script which causes PHP to emit warnings which
gets included in the image data. </p>
<p>A very common mistake is to have some white spaces in the
script before the opening "<code class="code">&lt;?php</code>". This
white space will be added to the output buffer and then get
mixed up with the image data causing the image data to be
corrupt. A similar problem can occur if multiple newlines
are added after the final <code class="code">"?&gt;"</code>
</p>
</li></ol></div><p>
</p>
</li><li class="listitem">
<p><span class="bold"><strong>An error message saying "Fonts are not available or not
readable" </strong></span></p>
<p>When an image contains TTF fonts you might get an error message saying
that the fonts are not available or not readable. If this is the case it
is first necessary to check that the font files really exist in the
directory that is specified in <code class="filename">jpg-config.inc.php</code>
and that they are also readable by the HTTP/PHP process. If this is the
case then it is necessary to check that the names of the font files are
the one that JpGraph assumes, see <a class="xref" href="ch03s02.html#sec3.name-of-ttf-files" title="Name of TTF font files">Name of TTF font files</a>. Another problem can be if
the PHP installation is running in "safe mode" (See <code class="uri"><a class="uri" href="http://se.php.net/manual/en/ini.sect.safe-mode.php" target="_top">PHP
Manual: Security and safe mode</a></code>) and has enabled strict
directory policy via an "<code class="code">open_basedir</code>" restriction. This
will prevent the PHP process from reading any files outside the
specified base directory. If this is enabled there is no way around for
PHP to read any files outside this restriction and any TTF files
necessary must be moved so that they can be accessed within the realms
of the specified basedirectory.</p>
<p>If you are running IIS and Win2k and get the error "Can't find font"
when trying to use TTF fonts then try to change the paths to UNIX style,
i.e. "<code class="filename">/usr/local/fonts/ttf/</code>". Remember that the
path is absolute and not relative to the <code class="filename">htdocs</code>
catalogue.</p>
<p>If you are running on Unix server please keep in mind that file names
are case sensitive.</p>
</li><li class="listitem">
<p><span class="bold"><strong>An error message saying "Headers have already been
sent"</strong></span></p>
<p>A common mistake is to have a space in the beginning of the image
script which the HTTP server will send back to the browser. The browser
now assumes that the data coming back from this script is text since it
hasn't received an explicit header. When then the image headers get sent
back to the browser to forewarn the browser of the forthcoming image
data the browser will not like that as it has already assumed the data
stream was a text stream. The browser will then give the infamous
"Headers already sent error".</p>
<p>Make sure that your script has no white space before the opening
"<code class="code">&lt;?php</code>" statement or a number of blank lines after
the concluding "<code class="code">?&gt;</code>"</p>
</li><li class="listitem">
<p><span class="bold"><strong>Issues specific to Windows and IIS</strong></span></p>
<p>Some windows installations seems to have a problem with a PHP script
ending in more than one newline (This newline seems to be sent to the
browser and will cause a <span class="italic">Header already sent error</span>). To correct this
problem check all your scripts for more than one empty newline after the
ending "<code class="code">?&gt;</code>" statement. All files provided with the library
end in exactly one final newline and should not be a problem.</p>
</li><li class="listitem">
<p><span class="bold"><strong>TTF fonts are not displayed correctly</strong></span></p>
<p>If the TTF fonts only shows up as yellow then the installation is used
a buggy (too old) installation of the FreeType font library and the only
thing to do is to re-install and setup PHP+GD again with a newer version
of the FreeType library. Another symptom of a an (old) buggy FreeType
library is that the fonts are not correctly rotated (the text string is
rotated but not the individual characters).</p>
</li></ol></div><p>As a final advise you should read the FAQ (available in this manual
see <a class="xref" href="apc.html" title="Appendix C. FAQ">Appendix C. <i>FAQ</i></a>) or on the JpGraph website at <code class="uri"><a class="uri" href="http://jpgraph.net/doc/faq.php" target="_top">http://jpgraph.net/doc/faq.php</a></code></p>
<p>Depending on your sever it might also help to recompile PHP yourself instead of
the version included with the system. You can find typical configuration scripts to
compile PHP4 and PHP5 in the appendices, see <a class="xref" href="api.html" title="Appendix I. Compiling PHP">Appendix I. <i>Compiling PHP</i></a>
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch03.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,26 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 4. Your first graph script</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt02.html" title="Part II. Basic graph creation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 4. Your first graph script</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part II. Basic graph creation</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="chapter" title="Chapter 4. Your first graph script"><div class="titlepage"><div><div><h2 class="title"><a name="id2492877"></a>Chapter 4. Your first graph script</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ch04.html#id2492897">4.1. Some words of caution</a></span></dt><dt><span class="sect1"><a href="ch04s02.html">4.2. Graphing the number of sun spots during the 19th Century</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch04s02.html#id2492934">4.2.1. The historic data</a></span></dt><dt><span class="sect2"><a href="ch04s02.html#sec.preparing-sunspots-data">4.2.2. Preparing the data</a></span></dt><dt><span class="sect2"><a href="ch04s02.html#id2492973">4.2.3. A basic line graph</a></span></dt><dt><span class="sect2"><a href="ch04s02.html#id2493198">4.2.4. A basic bar graph</a></span></dt></dl></dd></dl></div>
<p title="What you will learn in this chapter">
<b>What you will learn in this chapter. </b>
This chapter will illustrate how a basic line and bar graph can be created and it
will also show how input data should be prepared so it can be read and used by the
library.
</p>
<div class="sect1" title="Some words of caution"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2492897"></a>Some words of caution</h2></div></div></div>
<p>In order to quickly show a very first example we will create both a basic line
graph and a basic bar graph that depicts the number of sun spots (a.k.a. solar
flares) during the 19th century. The goal of this example is not to show every
possible configuration and parameter supported by the library but rather show how
simple it is to create a basic graph.</p>
<p>In the sections following this one we will describe more in details the
idiosyncrasies about dynamic graph generation and JpGraph so even if you don't fully
understand all the detail it will give a flavor of what is to come. As with all
complex libraries one has to start somewhere and sometimes accept some practices
without yet fully understand them. However, the goal of this manual is that after
reading it through you will fully understand every single detail shown in this
script.</p>
<p>So, without further due, let's start.</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt02.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,573 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Graphing the number of sun spots during the 19th Century</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch04.html" title="Chapter 4. Your first graph script"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Graphing the number of sun spots during the 19th Century</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 4. Your first graph script</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Graphing the number of sun spots during the 19th Century"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec1.graphing-sun-spots"></a>Graphing the number of sun spots during the 19th Century</h2></div></div></div>
<div class="sect2" title="The historic data"><div class="titlepage"><div><div><h3 class="title"><a name="id2492934"></a>The historic data</h3></div></div></div>
<p>It is a well known fact that sun spots have a certain pattern and regularity.
The cause of these regular patterns are not currently fully understood (even
though investigation into this phenomenon has been made since beginning of the
17:th century). The fact that solar storms affects the earth in terms of
interference with radio traffic and other sensitive electronic devices makes it
very interesting to keep careful records of the suns activities.</p>
<p>For this reason the data of solar storm is readily available and makes an
interesting first example. The data used here is taken from SIDC (The Solar
Influences Data Analysis Center) in Belgium (<code class="uri"><a class="uri" href="http://sidc.oma.be/sunspot-data/SIDCpub.php" target="_top">http://sidc.oma.be/sunspot-data/SIDCpub.php</a></code>).
In this example we will use the summary historical data that shows the total
number of sun spots per year since 1700.. </p>
</div>
<div class="sect2" title="Preparing the data"><div class="titlepage"><div><div><h3 class="title"><a name="sec.preparing-sunspots-data"></a>Preparing the data</h3></div></div></div>
<p>The first step is to get the data into our PHP script which makes for a first
good discussion since all graphs needs to get data from some source. The library
itself is agnostic in regards to from where the data is collected and only needs
(and requires) data stored in a PHP array of numbers (integers or floats). </p>
<p>In principle the data to be plotted in the graph can come from :</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Hard-coded data in the script. This is the least flexible and can
only really be recommended for examples and really static
data.</p>
</li><li class="listitem">
<p>Data stored in plain text files. (This is what we will use in this
example.)</p>
</li><li class="listitem">
<p>Data stored in binary format in flat files. </p>
</li><li class="listitem">
<p>Data stored in a database</p>
</li><li class="listitem">
<p>Data sent to the script via URI parameter passing (either GET or
POST HTTP constructs can be used).</p>
</li></ol></div><p>
</p>
<p>What is common among all these methods is that the creator of the script has
to read the data into one (or several) data arrays that can be used by the
library. For our example the data of sunspots are stored in a plain text file in
two columns, one column for the year (with a ".5" added which indicates the
average of the year) and one column for the number of sunspots for the
corresponding year. As illustration the first 10 lines of data is shown in <a class="xref" href="ch04s02.html#fig.first-ten-sunspot" title="Figure 4.1. The first ten rows of data of sunspot activities from year 1700">Figure 4.1. The first ten rows of data of sunspot activities from year
1700</a>.</p>
<p>
</p><div class="figure"><a name="fig.first-ten-sunspot"></a><p class="title"><b>Figure 4.1. The first ten rows of data of sunspot activities from year
1700</b></p><div class="figure-contents">
<div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">1700.5 5.0
1701.5 11.0
1702.5 16.0
1703.5 23.0
1704.5 36.0
1705.5 58.0
1706.5 29.0
1707.5 20.0
1708.5 10.0
1709.5 8.0</span></pre></td></tr></table></div>
</div></div><p><br class="figure-break">
</p>
<p>From this data we need to create two arrays, one with the number of sunspots
and one with the corresponding years. If we assume that the data is stored in a
text file named "<code class="filename">yearssn.txt</code>" in the same directory as the
script file the function in <a class="xref" href="ch04s02.html#fig.getsunspots" title="Figure 4.2. Reading numeric tabulated sunspot data from a file">Figure 4.2. Reading numeric tabulated sunspot data from a file</a>will read the data into two arrays</p>
<p>
</p><div class="figure"><a name="fig.getsunspots"></a><p class="title"><b>Figure 4.2. Reading numeric tabulated sunspot data from a file</b></p><div class="figure-contents">
<a name="pl.getsunspots"></a><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-reserved">function</span><span class="hl-code"> </span><span class="hl-identifier">readsunspotdata</span><span class="hl-brackets">(</span><span class="hl-var">$aFile</span><span class="hl-code">, &amp;</span><span class="hl-var">$aYears</span><span class="hl-code">, &amp;</span><span class="hl-var">$aSunspots</span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-var">$lines</span><span class="hl-code"> = @</span><span class="hl-identifier">file</span><span class="hl-brackets">(</span><span class="hl-var">$aFile</span><span class="hl-code">,</span><span class="hl-identifier">FILE_IGNORE_NEW_LINES</span><span class="hl-code">|</span><span class="hl-identifier">FILE_SKIP_EMPTY_LINES</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-reserved">if</span><span class="hl-brackets">(</span><span class="hl-code"> </span><span class="hl-var">$lines</span><span class="hl-code"> === </span><span class="hl-reserved">false</span><span class="hl-code"> </span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-reserved">throw</span><span class="hl-code"> </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">JpGraphException</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">Can not read sunspot data file.</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-brackets">}</span><span class="hl-code">
</span><span class="hl-reserved">foreach</span><span class="hl-brackets">(</span><span class="hl-code"> </span><span class="hl-var">$lines</span><span class="hl-code"> </span><span class="hl-reserved">as</span><span class="hl-code"> </span><span class="hl-var">$line</span><span class="hl-code"> =&gt; </span><span class="hl-var">$datarow</span><span class="hl-code"> </span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-var">$split</span><span class="hl-code"> = </span><span class="hl-identifier">preg_split</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">/[\s]+/</span><span class="hl-quotes">'</span><span class="hl-code">,</span><span class="hl-var">$datarow</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$aYears</span><span class="hl-brackets">[</span><span class="hl-brackets">]</span><span class="hl-code"> = </span><span class="hl-identifier">substr</span><span class="hl-brackets">(</span><span class="hl-identifier">trim</span><span class="hl-brackets">(</span><span class="hl-var">$split</span><span class="hl-brackets">[</span><span class="hl-number">0</span><span class="hl-brackets">]</span><span class="hl-brackets">)</span><span class="hl-code">,</span><span class="hl-number">0</span><span class="hl-code">,</span><span class="hl-number">4</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$aSunspots</span><span class="hl-brackets">[</span><span class="hl-brackets">]</span><span class="hl-code"> = </span><span class="hl-identifier">trim</span><span class="hl-brackets">(</span><span class="hl-var">$split</span><span class="hl-brackets">[</span><span class="hl-number">1</span><span class="hl-brackets">]</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-brackets">}</span><span class="hl-code">
</span><span class="hl-brackets">}</span><span class="hl-code">
</span><span class="hl-var">$year</span><span class="hl-code"> = </span><span class="hl-reserved">array</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$ydata</span><span class="hl-code"> = </span><span class="hl-reserved">array</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-identifier">readsunspotdata</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">yearssn.txt</span><span class="hl-quotes">'</span><span class="hl-code">,</span><span class="hl-var">$year</span><span class="hl-code">,</span><span class="hl-var">$ydata</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div>
</div></div><p><br class="figure-break">
</p>
<p>In the function above we have deviated from the common practice of not
including even the most basic error handling in examples by adding an exception
in case the data file could not be read. This is to emphasize that graph scripts
which reads data from potentially disconnected sources must have real quality
error and exception handling. As this is the first example we will not discuss
the details of the error handling other than saying that the library provides
one exception class <code class="code">JpGraphException</code> that is meant to be used by
clients to signal unrecoverable errors in the code. The full details on error
handling in the library is discussed in <a class="xref" href="ch06.html" title="Chapter 6. Error handling">Chapter 6. <i>Error handling</i></a></p>
<p>
</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
<p>In the library there is an auxiliary utility class
<code class="code">ReadFileData</code> to help read data from text files. In this
class there are methods to read data from a file in either of the
following formats</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p> CSV (Comma Separated Values) format.
<code class="code">ReadFileData::FromCSV()</code></p>
</li><li class="listitem">
<p>two column format (almost) as we did manually above with
<code class="code">ReadFileData::From2Col()</code></p>
</li><li class="listitem">
<p>one column format
<code class="code">ReadFileData::From1Col()</code></p>
</li></ul></div><p>
</p>
</div><p>
</p>
<p>Armed with the data in the two arrays <code class="code">$year</code> and
<code class="code">$ydata</code> we will now plot the data in a basic line graph with
some variations and then show the data in a bar graph.</p>
</div>
<div class="sect2" title="A basic line graph"><div class="titlepage"><div><div><h3 class="title"><a name="id2492973"></a>A basic line graph</h3></div></div></div>
<p>As the very first start we will create a line graph which shows sun spots as a
line graph. To keep the code focused on the graph we do not include the previous
function to read the data again in the code snippet shown below. Before we get
into the code we start by briefly discuss how your script can include the
necessary library files.</p>
<p>All graph scripts must include at least two files,
<code class="filename">jpgraph.php</code> and some plot module. If we want to create
a line plot we must include <code class="filename">jpgraph_line.php</code>. Slightly
depending on the server setup and what paths are defined for PHP include files
(as discussed in <a class="xref" href="ch03s03.html#sec2.adjusting-php-include-path" title="Adjusting PHP include path">Adjusting PHP include path</a>) the include paths for the
library might look a bit different. However, we recommend that you install the
library files so they can be accessed, for example using,
<code class="code">require_once('jpgraph/jpgraph.php')</code> (since this is what is
assumed by the library examples). Furthermore, we would recommend that the
<code class="code">require_once()</code> construct is used to avoid including the same
file multiple times.</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Width and height of the graph</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$width</span><span class="hl-code"> = </span><span class="hl-number">600</span><span class="hl-code">; </span><span class="hl-var">$height</span><span class="hl-code"> = </span><span class="hl-number">200</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Create a graph instance</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code"> = </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">Graph</span><span class="hl-brackets">(</span><span class="hl-var">$width</span><span class="hl-code">,</span><span class="hl-var">$height</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Specify what scale we want to use,</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> int = integer scale for the X-axis</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> int = integer scale for the Y-axis</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetScale</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">intint</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Setup a title for the graph</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">title</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Set</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">Sunspot example</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Setup titles and X-axis labels</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">xaxis</span><span class="hl-code">-&gt;</span><span class="hl-identifier">title</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Set</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">(year from 1701)</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Setup Y-axis title</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">yaxis</span><span class="hl-code">-&gt;</span><span class="hl-identifier">title</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Set</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">(# sunspots)</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Create the linear plot</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$lineplot</span><span class="hl-code">=</span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">LinePlot</span><span class="hl-brackets">(</span><span class="hl-var">$ydata</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Add the plot to the graph</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Add</span><span class="hl-brackets">(</span><span class="hl-var">$lineplot</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Display the graph</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Stroke</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div><p>
</p>
<p>Before we explain this code in some more detail it is a good idea to visualize
what we get when we execute this as script. The result of running this script is
shown in <a class="xref" href="ch04s02.html#fig.sunspotsex1" title="Figure 4.3. Line plot showing the number of sun spots since 1700 (sunspotsex1.php)">Figure 4.3. Line plot showing the number of sun spots since 1700 <code class="uri"><a class="uri" href="example_src/sunspotsex1.html" target="_top">(<code class="filename">sunspotsex1.php</code>)</a></code> </a></p>
<p>
</p><div class="figure"><a name="fig.sunspotsex1"></a><p class="title"><b>Figure 4.3. Line plot showing the number of sun spots since 1700 <code class="uri"><a class="uri" href="example_src/sunspotsex1.html" target="_top">(<code class="filename">sunspotsex1.php</code>)</a></code> </b></p><div class="figure-contents"> <span class="inlinemediaobject"><img src="images/sunspotsex1.png" alt="Line plot showing the number of sun spots since 1700 (sunspotsex1.php)"></span> </div></div><p><br class="figure-break">
</p>
<p>
</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
<p>You can always click on the filename in the title of a figure to view
the complete source code.</p>
</div><p>
</p>
<p>Let us now walk through this code in some details.</p>
<p>
</p><div class="variablelist"><dl><dt><span class="term">Line 1-12</span></dt><dd>
<p>The size of the graph must always be specified so the first
thing to do is to create a new graph object and set the width
and height of the overall graph. All graph scripts will need to
create at least one instance of the <code class="code">Graph()</code> class.
By convention in all our scripts we will name the created
instance of the Graph class "<code class="code">$graph</code>"..</p>
<p>The second thing that all graph scripts must specify is what
kind of scales should be used. The library supports linear,
integer, logarithmic, text and date scales. Since we know that
our data consist of only integers we keep things simple and set
both the X and the Y axis scale to be integers. The scale is
specified as a string where the first half of the string
denominates the X-axis scale and the second half denominates the
Y-axis scale. So in our example we specify
'<code class="code">intint'</code>. With this explanation you can probably
guess what '<code class="code">intlog</code>' or '<code class="code">linlog</code>' would
do. Why not try it ?</p>
</dd><dt><span class="term">Line 13-21</span></dt><dd>
<p>These lines sets some different text labels. By the naming
convention used in the library you can probably guess what all
those lines are doing. They set the overall graph title as well
as the X- and Y-axis titles. To keep the example as lean as
possible we use the default font and default size and color of
the text strings.</p>
</dd><dt><span class="term">Line 22-27</span></dt><dd>
<p>Each graph must have at least one plot (data series) that is
added to the graph. In our case we wanted to create a line graph
so we must create an instance of the class
'<code class="code">LinePlot</code>'. We create a new instance of this
class and as a parameter use the data for the data series we
want to create the line plot from, in our case the data array
with the sun spot numbers.</p>
</dd><dt><span class="term">Line 29</span></dt><dd>
<p>Understanding this single line is key to understanding dynamic
graph generation with PHP. This line instructs the library to
actually create the graph as an image, encode it in the chosen
image format (e.g. png, jpg, gif, etc) and stream it back to the
browser with the correct header identifying the data stream that
the client receives as a valid image stream. When the client
(most often a browser) calls the PHP script it will return data
that will make the browser think it is receiving an image and
not, as you might have done up to now from PHP scripts, text. </p>
<p>This is something that can be conceptually difficult to fully
understand at first and that is why we are spending the entire
next chapter <a class="xref" href="ch05.html" title="Chapter 5. Fundamentals of dynamic graph generation">Chapter 5. <i>Fundamentals of dynamic graph generation</i></a> on further exploring
this. But for now please accept that this works and by calling
the script above in your browser (it is available in the
"<code class="filename">Examples/</code>" directory in the
distribution as '<code class="filename">sunspotsex1.php</code>') you
should get the exact same image as shown above in <a class="xref" href="ch04s02.html#fig.sunspotsex1" title="Figure 4.3. Line plot showing the number of sun spots since 1700 (sunspotsex1.php)">Figure 4.3. Line plot showing the number of sun spots since 1700 <code class="uri"><a class="uri" href="example_src/sunspotsex1.html" target="_top">(<code class="filename">sunspotsex1.php</code>)</a></code> </a></p>
</dd></dl></div><p>
</p>
<p>Let's now make a small variation of the above line graph. Let's make it a
filled line graph. instead. In order to do this we only have to add one single
line</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-var">$lineplot</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetFillColor</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">orange@0.5</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div><p>
</p>
<p>The line above actually does two things. First it sets the basic color to
'orange' and then it modifies this color to be 50% opaque (0.5) which makes the
grid line shine through the fill color to some extent. The whole color handling
in the library is further describe both in <a class="xref" href="apd.html" title="Appendix D. Named color list">Appendix D. <i>Named color list</i></a> as well as in <a class="xref" href="ch07.html" title="Chapter 7. Color handling">Chapter 7. <i>Color handling</i></a>. The result of adding the line above is
shown in <a class="xref" href="ch04s02.html#fig.sunspotsex2" title="Figure 4.4. Displaying sun spots with a semi filled line graph (sunspotsex2.php)">Figure 4.4. Displaying sun spots with a semi filled line graph <code class="uri"><a class="uri" href="example_src/sunspotsex2.html" target="_top">(<code class="filename">sunspotsex2.php</code>)</a></code> </a></p>
<p>
</p><div class="figure"><a name="fig.sunspotsex2"></a><p class="title"><b>Figure 4.4. Displaying sun spots with a semi filled line graph <code class="uri"><a class="uri" href="example_src/sunspotsex2.html" target="_top">(<code class="filename">sunspotsex2.php</code>)</a></code> </b></p><div class="figure-contents"> <span class="inlinemediaobject"><img src="images/sunspotsex2.png" alt="Displaying sun spots with a semi filled line graph (sunspotsex2.php)"></span> </div></div><p><br class="figure-break">
</p>
<div class="sect3" title="Adding tick labels to the X-axis"><div class="titlepage"><div><div><h4 class="title"><a name="id2493501"></a>Adding tick labels to the X-axis</h4></div></div></div>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>This section can be skipped at first reading since it contains
some slightly more advanced material. The reason why we have
included this section already now is that some of the issues
discussed here is an often repeated question among newcomers to the
library.</p>
</div><p>
</p>
<p>There is one bit of the available data that we haven't used yet and that
is the actual years. In the example above we can only see the count from
1700. (If we just want to look at the cyclic behaviour of the number of
sunspots this is fine since what year a specific number of sunspots appeared
is not relevant.) To make it easier to see what year corresponds to the
different sunspot numbers we must change the label on the X-axis scale to
show the years instead.</p>
<p>There is actually a couple of ways to do this. The easiest way is to just
add the labels we have (<code class="code">$years</code>) on the X-axis and instruct the
library to use them instead. This is done with a call to the method
<code class="code">SetTickLabels()</code> on the X-axis. This method call takes an
array as argument and uses the values in that array to populate all labels
on major tick marks. In order to make adequate room for the scale the
library automatically selects a suitable distance between each major tick
mark.</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">xaxis</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetTickLabels</span><span class="hl-brackets">(</span><span class="hl-var">$year</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div><p>
</p>
<p>Adding this line to our previous graph will generate the graph shown in <a class="xref" href="ch04s02.html#fig.sunspotsex3" title="Figure 4.5. Adding tick labels to the graph (sunspotsex3.php)">Figure 4.5. Adding tick labels to the graph <code class="uri"><a class="uri" href="example_src/sunspotsex3.html" target="_top">(<code class="filename">sunspotsex3.php</code>)</a></code> </a></p>
<p>
</p><div class="figure"><a name="fig.sunspotsex3"></a><p class="title"><b>Figure 4.5. Adding tick labels to the graph <code class="uri"><a class="uri" href="example_src/sunspotsex3.html" target="_top">(<code class="filename">sunspotsex3.php</code>)</a></code> </b></p><div class="figure-contents"> <span class="inlinemediaobject"><img src="images/sunspotsex3.png" alt="Adding tick labels to the graph (sunspotsex3.php)"></span> </div></div><p><br class="figure-break">
</p>
<p>However, there is a problem in the graph above. There are valid years on
the X-axis up to "2000" but then there is a single label "320". </p>
<p><span class="bold"><strong>What is going on here?</strong></span> Have we already discovered
a bug in the library? </p>
<p>No, not really. In the way we have setup the graph we have not provided
the library with enough labels. What has happened is that the integer scale
has chosen a suitable interval between each tick label to have enough space
to be able to show the labels. As can be seen from the figure the distance
chosen with this particular graph seems to be 20 years between each tick.
The way the default labeling works is that the end tick should be labelled
and hence be an even multiple of 20 years (in this case).</p>
<p>Since the library needs to have tick labels for all ticks it uses the
labels we supplied as far as they go (up to 2008) but since we didn't supply
data more than up to "2008" (in the <code class="code">$year</code> array) the library
does what it can do and continues with the ordinal numbers where we failed
to provide enough labels.</p>
<p>Now, there are a some standard ways of correcting this abomination.</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>We can set a manual scale to make sure the scale ends exactly
at 2008, i.e. the scale is exactly as long as our data. This is
done by submitting the wanted scale min/max as additional
argument in the <code class="code">SetScale()</code> method. First the
min/max for the Y-axis and then the min/max for the X-scale.
Since we still want the Y-scale to be fully automatically
determined we just put a "0" for both min and max on the Y-scale
and specify 0 for the min x-value and then the exact number of
sunspots we have measured as the maximum x-value.</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetScale</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">intint</span><span class="hl-quotes">'</span><span class="hl-code">,</span><span class="hl-number">0</span><span class="hl-code">,</span><span class="hl-number">0</span><span class="hl-code">,</span><span class="hl-number">0</span><span class="hl-code">,</span><span class="hl-identifier">max</span><span class="hl-brackets">(</span><span class="hl-var">$year</span><span class="hl-brackets">)</span><span class="hl-code">-</span><span class="hl-identifier">min</span><span class="hl-brackets">(</span><span class="hl-var">$year</span><span class="hl-brackets">)</span><span class="hl-code">+</span><span class="hl-number">1</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div><p>
</p>
<p>The result of this is shown in <a class="xref" href="ch04s02.html#fig.sunspotsex4" title="Figure 4.6. Manually specifying the X scale to use just the supplied X values (sunspotsex4.php)">Figure 4.6. Manually specifying the X scale to use just the supplied X values <code class="uri"><a class="uri" href="example_src/sunspotsex4.html" target="_top">(<code class="filename">sunspotsex4.php</code>)</a></code> </a></p>
<p>
</p><div class="figure"><a name="fig.sunspotsex4"></a><p class="title"><b>Figure 4.6. Manually specifying the X scale to use just the supplied X values <code class="uri"><a class="uri" href="example_src/sunspotsex4.html" target="_top">(<code class="filename">sunspotsex4.php</code>)</a></code> </b></p><div class="figure-contents"> <span class="inlinemediaobject"><img src="images/sunspotsex4.png" alt="Manually specifying the X scale to use just the supplied X values (sunspotsex4.php)"></span> </div></div><p><br class="figure-break">
</p>
</li><li class="listitem">
<p>An alternative way to get labels is to use a callback function
to specify the labels. This works so that the library calls the
user specified function and as argument passes the label (or the
value of the label) that the library intends to put on a tick.
The library will then use as the actual label whatever string
value we return from our function. Since we know that the
integer label 0 (the first tick) corresponds to the first value,
i.e. "1700" we can simply take whatever label we get as
argument, add "1700" and return that value. This way all labels
will be properly named and even if the scale extends far beyond
where we have data a sensible tick label will be shown.</p>
<p>A suitable callback function together with the method to
instruct the library to use this callback would be</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> ...</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Label callback</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">function</span><span class="hl-code"> </span><span class="hl-identifier">year_callback</span><span class="hl-brackets">(</span><span class="hl-var">$aLabel</span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-reserved">return</span><span class="hl-code"> </span><span class="hl-number">1700</span><span class="hl-code">+</span><span class="hl-brackets">(</span><span class="hl-identifier">int</span><span class="hl-brackets">)</span><span class="hl-var">$aLabel</span><span class="hl-code">;
</span><span class="hl-brackets">}</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> ...</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">xaxis</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetLabelFormatCallback</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">year_callback</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> ...</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div><p>
</p>
<p>and the result can be seen in <a class="xref" href="ch04s02.html#fig.sunspotsex5" title="Figure 4.7. Using a callback to get correct values on the x axis (sunspotsex5.php)">Figure 4.7. Using a callback to get correct values on the x axis <code class="uri"><a class="uri" href="example_src/sunspotsex5.html" target="_top">(<code class="filename">sunspotsex5.php</code>)</a></code> </a></p>
<p>
</p><div class="figure"><a name="fig.sunspotsex5"></a><p class="title"><b>Figure 4.7. Using a callback to get correct values on the x axis <code class="uri"><a class="uri" href="example_src/sunspotsex5.html" target="_top">(<code class="filename">sunspotsex5.php</code>)</a></code> </b></p><div class="figure-contents"> <span class="inlinemediaobject"><img src="images/sunspotsex5.png" alt="Using a callback to get correct values on the x axis (sunspotsex5.php)"></span> </div></div><p><br class="figure-break">
</p>
</li><li class="listitem">
<p>There is one more way to handle this issue which we will not
cover in detail yet. This is to use a "text" scale. The
"text"scale can be used when there is no need to show numeric
values on the axis. A typical use for text scale would be to add
labels to mark bar graphs. Of course a text can contain numeric
strings that would make it visually indistinguishable from a
"real" numeric value.</p>
<p>For text scales every label counts. So by default the library
will assign a tick mark for each ordinal so that every label is
used. In some cases this will just be two dense and then the
tick and the labelling can be adjusted by calling the two
methods <code class="code">Axis::SetTextTickInterval()</code> and
<code class="code">Axis::SetTextLabelInterval()</code> to get to a wanted
result. But for now we do not discuss this technique further
here since it would bring too far.</p>
</li></ol></div><p>
</p>
</div>
</div>
<div class="sect2" title="A basic bar graph"><div class="titlepage"><div><div><h3 class="title"><a name="id2493198"></a>A basic bar graph</h3></div></div></div>
<p>As a final illustration we will show how easy it is to change the plot type.
We will make a small modification of the previous script and display the sun
spots as a bar graph instead. In order to do this we take the code from <a class="xref" href="ch04s02.html#fig.sunspotsex2" title="Figure 4.4. Displaying sun spots with a semi filled line graph (sunspotsex2.php)">Figure 4.4. Displaying sun spots with a semi filled line graph <code class="uri"><a class="uri" href="example_src/sunspotsex2.html" target="_top">(<code class="filename">sunspotsex2.php</code>)</a></code> </a> and just change the creation of an instance
of the <code class="code">LinePlot()</code> class to instead be an instance of the
<code class="code">BarPlot()</code> class (to make the code more readable we also change
the name of the variable where we store the instance so it makes more sense). In
order to use this class we must also change the include statement so that the
bar module is included by adding the statement
<code class="code">require_once('jpgraph/jpgraph_barplot.php')</code>. The changed code
would now look like this</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> ...</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Create the bar plot</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$barplot</span><span class="hl-code">=</span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">BarPlot</span><span class="hl-brackets">(</span><span class="hl-var">$ydata</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Add the plot to the graph</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Add</span><span class="hl-brackets">(</span><span class="hl-var">$barplot</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Display the graph</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Stroke</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div><p>
</p>
<p>and would result in the graph displayed in <a class="xref" href="ch04s02.html#fig.sunspotsex6" title="Figure 4.8. Changing the plot type to a bar plot instead (sunspotsex6.php)">Figure 4.8. Changing the plot type to a bar plot instead <code class="uri"><a class="uri" href="example_src/sunspotsex6.html" target="_top">(<code class="filename">sunspotsex6.php</code>)</a></code> </a></p>
<p>
</p><div class="figure"><a name="fig.sunspotsex6"></a><p class="title"><b>Figure 4.8. Changing the plot type to a bar plot instead <code class="uri"><a class="uri" href="example_src/sunspotsex6.html" target="_top">(<code class="filename">sunspotsex6.php</code>)</a></code> </b></p><div class="figure-contents"> <span class="inlinemediaobject"><img src="images/sunspotsex6.png" alt="Changing the plot type to a bar plot instead (sunspotsex6.php)"></span> </div></div><p><br class="figure-break">
</p>
<p>Since there are so many bars in small space we cannot see the individual bars
in the example in <a class="xref" href="ch04s02.html#fig.sunspotsex6" title="Figure 4.8. Changing the plot type to a bar plot instead (sunspotsex6.php)">Figure 4.8. Changing the plot type to a bar plot instead <code class="uri"><a class="uri" href="example_src/sunspotsex6.html" target="_top">(<code class="filename">sunspotsex6.php</code>)</a></code> </a>. So lets modify the script so that it only
shows the last 20 years of measurements so that we can see the individual bars.
To set this up there are two things we must do</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Change the scale ot a text scale since we want to make sure each
value is displayed. In addition the text scale actually changes one
more thing that we haven't mentioned. Using a text scale also
changes the alignment of the labels. For linear, integer,
logarithmic scales the labels are placed cantered below the tick
marks. For text labels they are instead place in between the tick
marks. This is the most common way of displaying bar graphs. This is
one more reason to think of text scales as a special scale mostly
suitable for bar graphs.</p>
</li><li class="listitem">
<p>Add two lines of code to "chop off" the extra not wanted data in
the input data arrays.</p>
</li></ol></div><p>
</p>
<p>The following code snippet shows the necessary modifications to the previous
script</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Just keep the last 20 values in the arrays</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$year</span><span class="hl-code"> = </span><span class="hl-identifier">array_slice</span><span class="hl-brackets">(</span><span class="hl-var">$year</span><span class="hl-code">, -</span><span class="hl-number">20</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$ydata</span><span class="hl-code"> = </span><span class="hl-identifier">array_slice</span><span class="hl-brackets">(</span><span class="hl-var">$ydata</span><span class="hl-code">, -</span><span class="hl-number">20</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> ...</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Specify what scale we want to use,</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> text = txt scale for the X-axis</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> int = integer scale for the Y-axis</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetScale</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">textint</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> ...</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div><p>
</p>
<p>The final graph with the "zoomed" last 20 years can now be seen in</p>
<p>
</p><div class="figure"><a name="fig.sunspotsex7"></a><p class="title"><b>Figure 4.9. Sunspots zoomed to only show the last 20 years <code class="uri"><a class="uri" href="example_src/sunspotsex7.html" target="_top">(<code class="filename">sunspotsex7.php</code>)</a></code> </b></p><div class="figure-contents"> <span class="inlinemediaobject"><img src="images/sunspotsex7.png" alt="Sunspots zoomed to only show the last 20 years (sunspotsex7.php)"></span> </div></div><p><br class="figure-break">
</p>
<p>Since the scale is larger we can now actually see the individual bars. By
default the library choses a light blue color to fill the interior. (Try to see
what happens if you add the method call
"<code class="code">$barplot-&gt;SetFillColor('orange@0.5');</code>" just after the
"<code class="code">$barplot</code>" variable has been assigned the new BarPlot
object.)</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch04.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,51 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 5. Fundamentals of dynamic graph generation</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt02.html" title="Part II. Basic graph creation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 5. Fundamentals of dynamic graph generation</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part II. Basic graph creation</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="chapter" title="Chapter 5. Fundamentals of dynamic graph generation"><div class="titlepage"><div><div><h2 class="title"><a name="chap.fund-dynamic-graph"></a>Chapter 5. Fundamentals of dynamic graph generation</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ch05.html#sec1.making-sense-of-HTTP-streams">5.1. Making sense of HTTP streams and MIME types</a></span></dt><dt><span class="sect1"><a href="ch05s02.html">5.2. What is an image?</a></span></dt><dt><span class="sect1"><a href="ch05s03.html">5.3. Static vs dynamic images</a></span></dt><dt><span class="sect1"><a href="ch05s04.html">5.4. Dynamic images on the command line</a></span></dt><dt><span class="sect1"><a href="ch05s05.html">5.5. How to generate images with JpGraph library</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch05s05.html#id2494467">5.5.1. The standard steps of setting up a graph</a></span></dt><dt><span class="sect2"><a href="ch05s05.html#id2494641">5.5.2. Choosing the image compression format for JpGraph</a></span></dt><dt><span class="sect2"><a href="ch05s05.html#id2494706">5.5.3. Sending back the image to the browser</a></span></dt><dt><span class="sect2"><a href="ch05s05.html#sec2.writing-miage-to-file">5.5.4. Writing the image directly to a file</a></span></dt><dt><span class="sect2"><a href="ch05s05.html#id2494959">5.5.5. Alternatives to streaming or storing the image</a></span></dt><dt><span class="sect2"><a href="ch05s05.html#sec2.forcing-browser-update">5.5.6. Forcing the browser to update your graph</a></span></dt><dt><span class="sect2"><a href="ch05s05.html#id2495089">5.5.7. Printing the generated image</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch05s06.html">5.6. Efficient graph generation using the built-in cache subsystem</a></span></dt></dl></div>
<p title="What you will learn in this chapter">
<b>What you will learn in this chapter. </b>
The purpose of this chapter is to put dynamic image generation in perspective and
illustrate how HTML tags is used to call image generating scripts. Even if You are
familiar with PHP it is strongly recommended to quickly browse through this chapter
to make sure all concepts are known. If You fully understand and can explain the
concept of MIME types, HTTP streams and why the "<span class="italic">Headers already sent error</span>" error is a very common
error when generating dynamic images with PHP it is probably safe to skip this
chapter. Otherwise it might be wise to read through this chapter at least
once.
</p>
<div class="sect1" title="Making sense of HTTP streams and MIME types"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec1.making-sense-of-HTTP-streams"></a>Making sense of HTTP streams and MIME types</h2></div></div></div>
<p>The following explanation is slightly simplified since a full description of the
HTTP protocol would bring us a bit too far in this manual </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>A client (e.g. browser) requests data from the server by issuing a GET
(or possible a POST) command to the server. This is what happens when
you enter a URI in the address bar in the browser.</p>
</li><li class="listitem">
<p>The server replies with a data stream (or an error if the requested
data wasn't available). This data stream is prepended with header (MIME
header) that tells the client (e.g. the browser) how to interpret the
data that follows. The most common type (and the default type if no
header is sent by a faulty server) is "<span class="bold"><strong>text/html</strong></span>" . This tells the client to
interpret the data as plain text with embedded HTML encoding. </p>
<p>When the data is to be interpreted as an image the header will instead
be one of the image headers, for example "<span class="bold"><strong>image/png</strong></span>" or "<span class="bold"><strong>image/jpeg</strong></span>". When the client receives this
header it will interpret all the following data as an image encoded in
the indicated format. </p>
<p>The important thing to keep in mind here is that each server reply
(initiated by a call from the client) can only have one and only one
MIME type. This is the key to further understanding the specific issues
with dynamic image generation. This explains why if a PHP script running
on the server sends a header first indicating that the following data it
sends should be interpreted by the client as an image it cannot also
include text since only one header can be used for one HTTP stream.
</p>
</li></ol></div>
<p>What happens on a WEB-page with, for example, multiple <span class="markup">&lt;img&gt;</span>
tags is that the browser issues a separate GET command for each of these images. So
even though it can look like a fetching a single WEB-page can have different content
each individual request to the server only have one single MIME type.</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt02.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,49 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>What is an image?</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch05.html" title="Chapter 5. Fundamentals of dynamic graph generation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">What is an image?</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 5. Fundamentals of dynamic graph generation</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="What is an image?"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2494175"></a>What is an image?</h2></div></div></div>
<p>This might be strange question and you might already now the answer but having a
true understanding will help. An image is simply a data stream of octets (bytes)
specifying the exact color of a number of pixels. A typical image uses 32 bits to
specify the color which means it can encode 2^32 different colors (Homework: How
many gray levels is possible with 32 bits?). It would be perfectly possible to send
this data stream as it is and indeed this is how the bitmap (BMP) format specifies
the data. However, image data usually have a lot of redundancies that can be used to
reduce the size of the data that needs to be transmitted to specify any given image.
These compression formats are what is more commonly known as for example PNG, JPEG
or GIF type of images. So it is actually more correct, in our view, to look upon
these formats as different compression techniques rather than as true image formats. </p>
<p>Contrary to popular belief it is not the suffix on a file per se that identifies a
particular file as an image on a HTTP server but rather the mapping on the server
that instructs the server to send back a particular header for a particular file
type (as identified by the file suffix), the MIME type. This might not seem like an
important distinction to make but keeping this in mind will help understanding how
images are created with a PHP script.</p>
<p>A normal PHP scripts sends back character data (or more likely HTML encoded
character data) that is displayed by the browser. However it is nothing that stops
the PHP script from sending back data that instead should be interpreted as an image
assuming of course we know how to create such data.. </p>
<p>How the client (i.e. the browser) should interpret the data sent is all controlled
by the header that is sent before the data. So this now leads us to the idea that if
our PHP script by some means constructs a valid image, compressed in a known format
(say PNG), we can tell the client to interpret the data we send back as an image by
just making sure we first send a header indicating that the data is an image.</p>
<p>This could now lead us to the perhaps surprising but crucial insight that if we
call our script that sends back valid image data "<code class="filename">myimage.php</code>"
and open it in a browser, for example by opening the local URI
"<code class="filename">http://localhost/myimage.php</code>" for the browser this is no
different then opening an image directly (for example
"<code class="filename">http://localhost/myimage.png</code>") </p>
<p>The only difference is that in the first case (our PHP script) we create the
header and data our self and in the second case the HTTP server looks up the file
suffix (*.png) to find out what kind of header to send before reading the file and
just passing on the data to the client.</p>
<p>Armed with this new knowledge we realize that our PHP script <span class="italic">is</span> an image for all practical purposes and intent from
a clients point of view. So we could safely name our PHP script as a target for an
<span class="markup">&lt;img&gt;</span> tag. This gives us the final and most common way to
call a graph script in a HTML page. </p>
<p><code class="code">&lt;img src="myimage.php"&gt;</code></p>
<p>in exactly the same way as we would do with the old type of images. The "*.php"
suffix is no problem since the client (e.g. the browser) don't care what the file
ending is. It only cares about what header the server returns. If that header tells
the browser that the data received should be interpreted as a PNG image it will do
so regardless of the name of the source file on the server.</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,23 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Static vs dynamic images</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch05.html" title="Chapter 5. Fundamentals of dynamic graph generation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Static vs dynamic images</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 5. Fundamentals of dynamic graph generation</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Static vs dynamic images"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2494178"></a>Static vs dynamic images</h2></div></div></div>
<p>Having understood how we can generate images using a PHP script a new idea might
be forming. There is nothing that says that we have to create the same image using
the same data every time the graph script is called. We could for example randomly
select a pre-stored image in a directory and every time we call (the same) graph
script and new image is returned. Hence, with PHP scripts we can create dynamic
images that generate different images depending on some yet to be specified
parameters even though the script name stays the same. This is a new behaviour
compared with our normal images. </p>
<p>This could also lead to a new, and very real, problem which has to do with the
local caching most browsers do in order to avoid re-fetching already fetched objects
such as images. Normally a browser will check the time stamp on the file on the
server and compare with the latest fetched version it has stored locally. If the
browser sees that the file on the server is older than what it already has it will
not re-fetch the file. </p>
<p>Since a dynamic image is produced by a script and the script will stay the same
even if the produced image is changing (due to new data) the browser might still
think that the image has not changed since the script is the same and will not
bother re-fetching it again. The exact behavior of the browser cache is usually
adjustable by the end user and hence out of control for us who writes the script. A
simple way to always force the client to re-fetch the dynamic image is described in <a class="xref" href="ch05s05.html#sec2.forcing-browser-update" title="Forcing the browser to update your graph">Forcing the browser to update your graph</a></p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,36 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Dynamic images on the command line</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch05.html" title="Chapter 5. Fundamentals of dynamic graph generation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Dynamic images on the command line</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 5. Fundamentals of dynamic graph generation</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Dynamic images on the command line"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2494302"></a>Dynamic images on the command line</h2></div></div></div>
<p>It is also possible to generate images directly using the command line version of
PHP. This works the same way as the normal "through the browser" generation with the
exception that no HTTP headers will be generated. Only the binary image data.</p>
<p>This could be an effective way to make an efficient web-site by having some
automatic creation of images at regular interval (perhaps using some kind of
<code class="code">cron</code>-job) that are referenced as usual (with an
<span class="markup">&lt;img&gt;</span> tag) in the scripts. This will avoid having to
re-generate the image every time a visitor hits the site.</p>
<p>Please make sure that you run the command line version of PHP (cli). Using the CGI
SAPI version of PHP will not work since then the HTTP headers will be generated. </p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>If the CGI version is used the generation of headers may be suppressed by
adding the '-q' option. </p>
</div><p>
</p>
<p>You can easily check the version installed by the command line</p>
<p>
</p><pre class="screen">$/&gt; php --version</pre><p>
</p>
<p>this should give a reply with something like</p>
<pre class="screen">PHP 4.3.8 (cli) (built: Aug 29 2004 18:48:13) Copyright (c) 1997-2004 The PHP Group Zend Engine v1.3.0,
Copyright (c) 1998-2004 Zend Technologies</pre>
<p>The important thing here is the <code class="code">(cli)</code> marker. The JpGraph library
check from what SAPI API it is invoked from and adjusts the header generation
accordingly. </p>
<p>If all the above requirements are met then images can be generated directly on the
command line and stored in a suitable file. For example by </p>
<p>
</p><pre class="screen">$/&gt; php myimage.php &gt; image.png</pre><p>
</p>
<p>Please note that the file extension on the image file should match the format in
which the image is generated.</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,380 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>How to generate images with JpGraph library</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch05.html" title="Chapter 5. Fundamentals of dynamic graph generation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">How to generate images with JpGraph library</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 5. Fundamentals of dynamic graph generation</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="How to generate images with JpGraph library"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2494304"></a>How to generate images with JpGraph library</h2></div></div></div>
<p>The two common steps for creating and using a Graph on your Web-page are</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Create a script that constructs the graph, by getting the data and
specifying how the graph should look, the size, what colors to use, what
fonts to use and specifying other augmentations on the graph.</p>
</li><li class="listitem">
<p>On the HTML page where the graph(s) should be displayed include add
one or more <span class="markup">&lt;img&gt;</span> tags which links to the PHP graphs
script. Of course it is perfectly possible to call the image script
directly in the browser to just display the generated image in the
browser. This way it is possible to include any number of graphs on the
Web-page.</p>
</li></ol></div><p>
</p>
<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
<p>One further thing to keep in mind is that it is also possible to pass
arguments to the image script via the normal HTTP GET/POST arguments. </p>
<p>For example </p>
<p>
</p><pre class="screen">&lt;img src="showgraph.php?a=1&amp;b=2"&gt; </pre><p>
</p>
<p>This could be used to control the appearance of the image or perhaps send data
to the image which will be displayed. Note that this is probably not the best
way to send large amount of data to plot. Instead the only practical way, for
large data sizes, is to get all the data in the image script directly, perhaps
from a DB. Another alternative for large amount of data to be sent to the image
script is by creating a POST request to the image script. This is further
discussed in ?? (Getting hold of the data to be displayed)</p>
</div>
<div class="sect2" title="The standard steps of setting up a graph"><div class="titlepage"><div><div><h3 class="title"><a name="id2494467"></a>The standard steps of setting up a graph</h3></div></div></div>
<p>When it comes to the structure of your imaging script they will generally have
the following structure </p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> ... Include necessary headers </span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">require_once</span><span class="hl-code"> </span><span class="hl-quotes">'</span><span class="hl-string">jpgraph.php</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-reserved">require_once</span><span class="hl-code"> </span><span class="hl-quotes">'</span><span class="hl-string">....</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Create the graph instance</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code"> = </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">Graph</span><span class="hl-brackets">(</span><span class="hl-var">$width</span><span class="hl-code">,</span><span class="hl-var">$height</span><span class="hl-code">, ...</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Specify what scale should be used in the graph</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetScale</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">...</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> ... code to construct the graph details and plot objects</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Add one or many plot objects to the graph</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Add</span><span class="hl-brackets">(</span><span class="hl-code">..</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> ... and send back the graph to the client</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Stroke</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div><p>
</p>
<p>JpGraph is completely Object oriented so all calls will be action on specific
instances of classes. One of the fundamental classes is the <code class="code">Graph()</code>
class which represents the entire graph.</p>
<p>After the creation of the <code class="code">Graph()</code> object all the code lines to
construct the details of the graph are added. The final method called in an
image script will most likely be the <code class="code">Graph::Stroke()</code> method. This
will send the constructed image back to the browser. A variation of this is used
if the graph are supposed to have image maps (CSIM). In that case the final
method will be <code class="code">Graph::StrokeCSIM()</code></p>
<p>
</p><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3>
<p>As discussed in <a class="xref" href="ch05.html#sec1.making-sense-of-HTTP-streams" title="Making sense of HTTP streams and MIME types">Making sense of HTTP streams and MIME types</a> no text can be
returned from an image script. Beware!</p>
</div><p>
</p>
<p>In addition to this standard usage pattern you can also choose to:</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>... send the graph directly to a file. This is done by specifying
a filename as parameter to the final <code class="code">Stroke()</code> method
call. See <a class="xref" href="ch05s05.html#sec2.writing-miage-to-file" title="Writing the image directly to a file">Writing the image directly to a file</a> for more detailed
information.</p>
</li><li class="listitem">
<p>... access the GD image handler for further image processing (also
needed to include the image in an PDF file, see <a class="xref" href="apc.html" title="Appendix C. FAQ">Appendix C. <i>FAQ</i></a>)</p>
</li><li class="listitem">
<p>... make use of the built-in cache system to send back a
previously generated image. The cache system, which lessens the
burden of the PHP server, works by avoiding running all the code
that follows the initial <code class="code">Graph()</code> call by checking if
the image has already been created and in that case directly send
back the previously created (and stored in a file) image file to the
browser. The filename used for the image can be either manually
selected or automatically created based on the script name. In
addition it is also possible to specify a timeout value in the
initial call to the Graph() constructor to indicate how long the
image in the cache directory should be considered valid before a new
image is generated. A full description of the JpGraph cache system
is available in <a class="xref" href="ch05s06.html" title="Efficient graph generation using the built-in cache subsystem">Efficient graph generation using the built-in cache subsystem</a>.</p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>The cache system by default is disabled and must be
enabled by setting the proper define in the file
"j<code class="filename">pg-config.inc</code>"</p>
</div><p>
</p>
</li><li class="listitem">
<p>... combine several graphs in the same image using the
<code class="code">MGraph()</code> class (Multi-Graph). This is an advanced
technique described in ??.</p>
</li></ol></div><p>
</p>
</div>
<div class="sect2" title="Choosing the image compression format for JpGraph"><div class="titlepage"><div><div><h3 class="title"><a name="id2494641"></a>Choosing the image compression format for JpGraph</h3></div></div></div>
<p>By default JpGraph automatically chooses the image format to use in the order
PNG, JPEG and GIF. The exact format depends on what is available on the system
the library is installed on. There are two ways you can influence the way the
graphic format is chosen:</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Change the default graphic format by changing the DEFINE (in
<code class="filename">jpg-config.inc.php</code>)</p>
<p><code class="code">DEFINE('DEFAULT_GFORMAT','auto')</code></p>
<p>For example; if you by default want all your images to be
generated with JPG encodation the define should be changed to </p>
<p><code class="code">DEFINE('DEFAULT_GFORMAT','jpg')</code></p>
</li><li class="listitem">
<p>By dynamically (in your script) select the wanted compression
format with a call to</p>
<p><code class="code">Image::SetImgFormat()</code></p>
<p>For example; if you want your image to use the JPEG format </p>
<p>
<code class="code">$graph-&gt;img-&gt;SetImgFormat('jpeg')</code></p>
<p> (The above line assume that you have called your variable that
holds the instantiated <code class="code">Graph()</code> object
"<code class="code">$graph</code>"</p>
</li></ol></div><p>
</p>
</div>
<div class="sect2" title="Sending back the image to the browser"><div class="titlepage"><div><div><h3 class="title"><a name="id2494706"></a>Sending back the image to the browser</h3></div></div></div>
<p>The very last statement in almost all graph scripts is the line</p>
<p>
</p><pre class="screen">$graph-&gt;Stroke();</pre><p>
</p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>Actually there are some valid exceptions to this when you do some more
advanced graph generation involving caching together with the CSIM
functionality.</p>
</div><p>
</p>
<p>This line starts the actual graph creation. All method calls up to this stage
has just been to set the scene for the library and specify all necessary
parameters. It is first when you make the call to the <code class="code">Stroke()</code>
method the library actually starts to build the image. Assuming there are no
errors detected when the image is generated the library will now take the
following steps in principle:</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Start building the image in memory. This is done by analyzing the
specified parameters and making use of the supplied data in order to
create the various plots that have been specified.</p>
</li><li class="listitem">
<p>Check what headers are needed, i.e. what image compression are
used for the graph, and send that header back to the client.</p>
<p>The library also have to check how the library was called since if
it was called from the command line no MIME headers should be sent
back at all, just the raw image data. Running the command line
version of PHP will allow you to dynamically create images without
using a HTTP server.</p>
</li><li class="listitem">
<p>Send the actual image data representing the built up image back to
the client</p>
</li></ol></div><p>
</p>
<div class="warning" title="The dreaded: Headers has already been sent error" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">The dreaded: Headers has already been sent error</h3>
<p>This is an error that everyone, and we really mean everyone, will see one
time or the other when producing dynamic images with PHP.</p>
<p>First, this is not a problem with JpGraph per se. What has happened is
that your PHP script which produces the image has already returned some data
to the client before the image header has been sent. </p>
<p>This is most often caused by one or more spaces before the first
"<code class="code">&lt;?php</code>" statement. What happens is that the server
normally sends back all data it finds in the files it reads. Since the
server no sees a space, a perfectly valid character, it will send that data
back to the client. However, before it does that it will automatically
generate a header. Since it has seen a normal character data it will
generate a header telling the client to expect a data stream of
characters.</p>
<p>When later JpGraph tries to send its image header the server will detect
that a header has already been sent and since each HTTP data stream can only
have one type (and hence only one header) it will generate an error message
which is sent back to the client.</p>
<p>To correct this error check your files for any output (even a single
space) before the call to <code class="code">Graph::Graph()</code> (or
<code class="code">Graph::Stroke()</code>) If you are running on older version of a
Windows server this problem could also be caused by blank line at the end of
the files. On some older Windows versions together with PHP4 it might also
be called by a file ending in a newline (which all the JpGraph library files
does) Remove the newline so that the file ends just after the final
"<code class="code">?&gt;</code>" Also remember that when you include external file
using <code class="code">include/include_once</code> and so on PHP includes the whole
content of the file; this content of the file also includes any potential
carriage return/line feed or "blank" space before "<code class="code">&lt;?php</code>"
and after "<code class="code">?&gt;"</code> These "dirty characters" will cause the problem
just described. </p>
</div>
</div>
<div class="sect2" title="Writing the image directly to a file"><div class="titlepage"><div><div><h3 class="title"><a name="sec2.writing-miage-to-file"></a>Writing the image directly to a file</h3></div></div></div>
<p>In addition to just streaming the file back to the browser it is also possible
to write the file directly to a named file. The file name is given as an
argument to the Graph::Stroke() method. For example as </p>
<p><code class="code">$graph-&gt;Stroke('/tmp/myimage.png');</code></p>
<p>There are three important things to note here</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>The PHP process must have write permission on the directory you
are trying to write the image file on. If you are running PHP
through your browser this means that the HTTP server process must
have write permission on that directory.</p>
</li><li class="listitem">
<p>The file suffix (e.g. '<code class="code">.png</code>') should match the image
compression type used.</p>
</li><li class="listitem">
<p>If the image is streamed directly to a file and not back to the
browser the script can of course return ordinary text.</p>
</li></ol></div>
<div class="tip" title="Writing the image to both a file and stream it back to the browser" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Writing the image to both a file and stream it back to the
browser</h3>
<p>In this case you should instead use the method
<code class="code">Graph::StrokeStore($aFileName)</code> which was introduced in
version 2.5 of the library. If you are on a previous version and for various
reasons cannot upgrade then you can use the following "trick" to achieve
this.</p>
<p>The idea is to use the <code class="code">_IMG_HANDLER</code> option that forces the
<code class="code">Graph::Stroke()</code> to just return the image handler and then
stop. We can then manually first send the image to the chosen file and then
stream it back to the browser using some internal methods in the library.
The following code snippet shows how this is done.
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> ... necessary includes ...</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code"> = </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">Graph</span><span class="hl-brackets">(</span><span class="hl-number">400</span><span class="hl-code">,</span><span class="hl-number">300</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> ... code to generate a graph ...</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Get the handler to prevent the library from sending the</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> image to the browser</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$gdImgHandler</span><span class="hl-code"> = </span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Stroke</span><span class="hl-brackets">(</span><span class="hl-identifier">_IMG_HANDLER</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Stroke image to a file and browser</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Default is PNG so use &quot;.png&quot; as suffix</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$fileName</span><span class="hl-code"> = </span><span class="hl-quotes">&quot;</span><span class="hl-string">/tmp/imagefile.png</span><span class="hl-quotes">&quot;</span><span class="hl-code">;
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">img</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Stream</span><span class="hl-brackets">(</span><span class="hl-var">$fileName</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Send it back to browser</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">img</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Headers</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">img</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Stream</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div>
</div>
</div>
<div class="sect2" title="Alternatives to streaming or storing the image"><div class="titlepage"><div><div><h3 class="title"><a name="id2494959"></a>Alternatives to streaming or storing the image</h3></div></div></div>
<p>There are also two predefined filenames which have special meaning when
supplied as argument ot the <code class="code">Stoke()</code> method.</p>
<p>
</p><div class="variablelist"><dl><dt><span class="term"><code class="code">_IMG_AUTO</code></span></dt><dd>
<p>This will create a file in the same directory as the script
with the same name as the script but with the correct image
extension. </p>
</dd><dt><span class="term"><code class="code">_IMG_HANDLER</code></span></dt><dd>
<p>Specifying this filename will not create a an image to file
nor stream it back to the browser. Instead it will instruct the
<code class="code">Stroke()</code> method to just return the handle for
the GD image. This is useful if you later want to manipulate the
image in ways that are not yet supported by JpGraph. For example
include the image in a dynamically generated PDF file. See <a class="xref" href="apc.html" title="Appendix C. FAQ">Appendix C. <i>FAQ</i></a> for a detailed example how to
include an image in a PDF generated with the "fpdf"
library.</p>
</dd></dl></div><p>
</p>
</div>
<div class="sect2" title="Forcing the browser to update your graph"><div class="titlepage"><div><div><h3 class="title"><a name="sec2.forcing-browser-update"></a>Forcing the browser to update your graph</h3></div></div></div>
<p>Some browser may not send back a request to the HTTP server unless the user
presses "Refresh" (F5 - in most browsers). This can lead to problems that the
user is seeing old data since the file stamp of the script might not change but
the data the script is using to create the image/graph is. A simple trick is to
add a dummy time argument which is not used in the script. </p>
<p>For example </p>
<p><code class="code">&lt;img src="myimagescript.php?dummy=\'.now()."&gt;</code>
</p>
<p>Since the dummy argument will be a new number whenever the browser checks it
the browser understands that it must re-fetch the script and force the image to
be reloaded and redisplayed.</p>
<p>It is also important to be aware of any internal caching the browser might do.
The general problem with dynamically generated images is that the image
generating script (file) remains the same. This makes the browser believe that
the data hasn\'t changed (since the script is the same) and if the browser
already has issued a previous GET request and has the data cached it will not
send a new GET if the time stamp on the file is the same since it then believes
it should and can use the old browser cached version.</p>
</div>
<div class="sect2" title="Printing the generated image"><div class="titlepage"><div><div><h3 class="title"><a name="id2495089"></a>Printing the generated image</h3></div></div></div>
<p>Some browsers, most notable IE (&lt; v7) can have issues printing a dynamic
image. This is because the designers of IE assumed that all images are
traditional images that are available as static image files. Not that they could
be dynamically generated. This unfortunately have some implications.</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>IE will often (always?) re-fetch the page when preparing to print.
This means that a new image will be generated and is perhaps very
different from what the user thinks he is printing (if the data is
changing rapidly).</p>
</li><li class="listitem">
<p>Some older versions of IE simply refuses to print dynamic images
if they are not available as a static "*.png", "*.jpg" etc. file.
The only known workaround is to make sure to use static
images.</p>
</li></ol></div><p>
</p>
<p>There is one final reported problem to be aware of. Normally most browsers
will support "right-clicking" on an image to download the image locally.
However, some older versions of IE will become very confused when dynamic images
are used. This could manifest itself as that the file type is not the wanted,
for example, trying to download a "*.png" image could cause the file to be saved
as a "*.bmp" file instead. </p>
<p>Newer versions of IE seems to be able to handle dynamic images much
better.</p>
<p>It should also be mentioned that some older versions of FireFox (&lt; v3)
could in some circumstances fetch a dynamic image twice causing unnecessary load
on the server (See <code class="uri"><a class="uri" href="https://bugzilla.mozilla.org/show_bug.cgi?id=331126" target="_top">FireFox
Bugzilla</a></code>). However, there are no known issues with dynamic images in
current versions of FireFox and IE (i.e. IE v8).</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,77 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Efficient graph generation using the built-in cache subsystem</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch05.html" title="Chapter 5. Fundamentals of dynamic graph generation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Efficient graph generation using the built-in cache subsystem</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 5. Fundamentals of dynamic graph generation</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Efficient graph generation using the built-in cache subsystem"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec.efficient-graph-generation"></a>Efficient graph generation using the built-in cache subsystem</h2></div></div></div>
<p>The full explanation of how to use the JpGraph cache system is deferred to <a class="xref" href="ch09.html" title="Chapter 9. Using the JpGraph cache system">Chapter 9. <i>Using the JpGraph cache system</i></a> so this early section is just to explain the
principles and why you probably want to read through the full chapter later
on.</p>
<p>The core problem is that generating images can require a lot of CPU time. If we
combine this with the interpreted nature of PHP we can get a potential lethal
performance mixture. For example, if a web page uses one dynamically generated graph
and at its peak the site has 50 hits per second this means that the PHP graph script
also has to be called 50 times a second. On a high end server a typical graph takes
in the range of 0.02s up to 0.2s (and some complex graph, for example an
anti-aliased Contour-plot, can take up to 1s) to generate using a plain
non-accelerated installation (see more on supported PHP Accelerators in <a class="xref" href="ch11.html" title="Chapter 11. NuSphere PHP accelerator">Chapter 11. <i>NuSphere PHP accelerator</i></a>).</p>
<p>If we furthermore makes the realistic assumption that the site needs to run some
database services and generate other content as well the graph script itself might
not be allowed to use more than 50% of the available CPU bandwidth. It is now easy
to see that we are in trouble.</p>
<p>Continuing with the example. Assuming our graph is medium complex and takes a
whole 0.04s to generate. This means that if the server does not do anything more
than just creating images then we can crank out 1/0.04 or 25 graphs per second per
core at maximum. If we then take the 50% load into account it means that we could
only be allowed to generate ~12 graphs per second per core and remember that this
was on a high end server. If we now have more than 12 hits per second or have a more
average server with a less powerful CPU we are heading directly for a seriously
under dimensioned server.</p>
<p>If we assume we are running our server on a dual-core CPU this gives us an upper
practical limit of 24 graphs per second per server.</p>
<p>There are a couple of ways to counteract this problem but none is a 100%
solution.</p>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Introduce load balancing among several servers. This is a common way
to dynamically adjust to varying loads but without some serious
investments into a server farm it is still possible to overload the
system.</p>
</li><li class="listitem">
<p>Reduce the complexity of the graphs. However there is still a limit,
even very simple and basic graphs takes in the order of 0.02s on a high
end server due partly to the cost PHP parsing of all the library files.
This means that the upper limit is still valid.</p>
</li><li class="listitem">
<p>Make use of a PHP accelerator. If you are running a professional
server this is a must. We would go so far as to say that running a
professional PHP server without using any of the available PHP
accelerators borders on gross misconduct on the behalf of the
information architect that did the logical server design. Using a PHP
accelerator we can normally expect to get an almost 100% improvement.
Taking the previous example as a case we can probably expect an upper
limit of ~24 graphs per second per core instead of the normal
~12.</p>
</li><li class="listitem">
<p>Make use of the built in cache system in JpGraph. This system if set
up correctly will avoid the problem by not having to generate the same
(or almost the same) image over and over again. The core idea of the
system is the observation that the majority of the data presented on a
WEB page is changing only very slowly compared with the hits a server
gets. </p>
<p>For example, if a server has a graphical overview of defects by
showing inflow/outflow there is probably a good case to state that the
data change sufficiently slowly that it is probably not necessary to
re-generate the graph more than 6 times per day (or perhaps even just
once per day).</p>
<p>The JpGraph cache system allows you to do just that. What you do is
specify a timeout. When the server calls the graph script the script
first checks if a previous image has been generated. If that is the case
it then checks how old the image is and if it is newer than the timeout
limit then the existing image is sent back. It is just in the case that
there isn't already any image (the script has never been run) or that
the existing image is too old (older than the specified timeout limit)
that the image gets generated again.</p>
<p>You could of course do all of this manually but the library has built
in support for this that will allow you to use the system without
changing a single line in your existing scripts. It is all taken care of
in the background.</p>
</li></ol></div><p>For a production server the recommended setup is to use a combination
of load balancing, a suitable PHP accelerator and enabling the JpGraph cache
system.</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,67 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 6. Error handling</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt02.html" title="Part II. Basic graph creation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 6. Error handling</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part II. Basic graph creation</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="chapter" title="Chapter 6. Error handling"><div class="titlepage"><div><div><h2 class="title"><a name="chap.error-handling"></a>Chapter 6. Error handling</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ch06.html#id2495302">6.1. The problem with error messages and images</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch06.html#id2495400">6.1.1. Catching errors in other parts of the system while creating images</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch06s02.html">6.2. Available error messages</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch06s02.html#sec2.localizing-errmsg">6.2.1. Localizing error messages</a></span></dt><dt><span class="sect2"><a href="ch06s02.html#id2495515">6.2.2. Error messages on a production server</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch06s03.html">6.3. Using PHP Exceptions</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch06s03.html#id2495896">6.3.1. Selecting between text and image based error handling</a></span></dt><dt><span class="sect2"><a href="ch06s03.html#id2495901">6.3.2. Writing error message to a log file (or system logger)</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch06s04.html">6.4. Adding a new locale</a></span></dt></dl></div>
<div class="sect1" title="The problem with error messages and images"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2495302"></a>The problem with error messages and images</h2></div></div></div>
<p>Why a whole chapter on error handling? The answer is that error handling with
scripts that produces images requires a slightly different approach than normal
error messages. In order to appreciate the added complexity one needs to consider
how a graph script is called. Usually a graph script is called from an
<span class="markup">&lt;img&gt;</span> tag. This means that the client (e.g. the browser)
expect image data to be sent from the script. If we instead send a textual error
message the browser will not be able to display anything. It was expecting a stream
with image data and the data received was a representation of an error message which
of course cannot be interpreted as an image.</p>
<p>To handle this problem the error messages produced by the library are normally
generated as an image. A typical error message can be seen in <a class="xref" href="ch06.html#fig.errmsg-ex1" title="Figure 6.1. Typical image error message">Figure 6.1. Typical image error message</a></p>
<div class="figure"><a name="fig.errmsg-ex1"></a><p class="title"><b>Figure 6.1. Typical image error message</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/errmsg-ex1.png" alt="Typical image error message"></div>
</div></div><br class="figure-break">
<p>There is one exception to this rule and that is in the case of the "Headed already
sent" error message. This means that the client has already received an header and
with probability bordering on certainty this is a text header. Hence in this case it
does not make sense to send an image so this, and only this, error message is sent
as a normal "text/html" type message. A typical example how this message is shown in
the browser can be seen in <a class="xref" href="ch06.html#fig.errmsg-header-sent" title='Figure 6.2. The "Header already sent error message"'>Figure 6.2. The "Header already sent error message"</a></p>
<div class="figure"><a name="fig.errmsg-header-sent"></a><p class="title"><b>Figure 6.2. The "Header already sent error message"</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/errmsg-headersent.png" alt='The "Header already sent error message"'></div>
</div></div><br class="figure-break">
<p>When you get this error (and we mean when - not if) take a very close look at the
text in red. This will tell you in what file and what line the erroneous output
started. In most cases this will be an innocent looking space or a tab character. It
could also be caused by multiple newlines at the end of a file. Since by definition
these mistakes can be hard to spot since spaces and tabs are not normally visible in
an editor so take care! </p>
<div class="sect2" title="Catching errors in other parts of the system while creating images"><div class="titlepage"><div><div><h3 class="title"><a name="id2495400"></a>Catching errors in other parts of the system while creating images</h3></div></div></div>
<p>The problem described in the previous section will also apply to error
messages that are generated directly from PHP as well. In order to be able to
see any potential error messages during development it is possible to instruct
the library to intercept PHP error messages and convert them to image messages
instead. This is controlled by the two defines
<code class="code">INSTALL_PHP_ERR_HANDLER</code> and <code class="code">CATCH_PHPERR</code> define in
<code class="filename">jpg-config.inc.php</code>
</p>
<p>
</p><div class="variablelist"><dl><dt><span class="term"><code class="code">INSTALL_PHP_ERR_HANDLER</code></span></dt><dd>
<p>Setting this define to true will make the library install a
custom error handler which will catch all PHP error messages and
convert them into an image like what can be seen in <a class="xref" href="ch06.html#fig.errmsg-ex1" title="Figure 6.1. Typical image error message">Figure 6.1. Typical image error message</a>. </p>
<p>By default this is disabled.</p>
</dd><dt><span class="term"><code class="code">CATCH_PHPERR</code></span></dt><dd>
<p>This defines control whether the library shall check for any
generated error message that are stored in the global PHP
pre-defined variable <code class="code">php_errmsg</code>. This can be very
useful during development if an error has occurred prior to
calling the graph script. This error will then be displayed as
an image.</p>
<p>By default this is enabled.</p>
</dd></dl></div><p>
</p>
</div>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt02.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,78 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Available error messages</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch06.html" title="Chapter 6. Error handling"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Available error messages</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 6. Error handling</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Available error messages"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2495499"></a>Available error messages</h2></div></div></div>
<p>All error messages that can be generated by the library are listed in <a class="xref" href="aph.html" title="Appendix H. Error messages">Appendix H. <i>Error messages</i></a></p>
<div class="sect2" title="Localizing error messages"><div class="titlepage"><div><div><h3 class="title"><a name="sec2.localizing-errmsg"></a>Localizing error messages</h3></div></div></div>
<p>The library includes two (actually two and one pseudo) localizations of the
error messages. As of version 2.5 the library supports English and German error
messages. The choice of which localization of error messages that should be used
can be done in two ways; either by specifying a global define in
jpg-config.inc.php or</p>
<p>As of version 2.5 there are three localization options</p>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>English error messages ("en")</p>
</li><li class="listitem">
<p>German error messages ("de")</p>
</li><li class="listitem">
<p>Production error messages. This is not really a localization but a
different set of error messages which does not give detailed error
messages but a generic message suitable for a production server
where the end user is not helped by detailed graph script errors.
Instead a generic message is shown together with an error code that
corresponds to the detailed error. ("prod")</p>
</li></ol></div><p>In order to specify the error message localization the following
define in <code class="filename">jpg-config.inc.php</code> must be set the </p>
<p><code class="code">define('DEFAULT_ERR_LOCALE','en');</code></p>
<p>The possible (string) options are</p>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>"en", English locale</p>
</li><li class="listitem">
<p>"de", German locale</p>
</li><li class="listitem">
<p>"prod", The production version of the error messages.</p>
</li></ol></div><p>It is also possible to dynamically set the localization of error
messages by calling the static method
<code class="code">JpGraphErr::SetErrLocale($aLocaleString)</code> .For example, in order
to dynamically change to German locale the following method call would be
used:</p>
<p><code class="code">JpGraphErr::SetErrLocale('de');</code></p>
<p>As an example of the German locale the "<span class="italic">Header Already Sent</span>" error message localized in
German are shown in <a class="xref" href="ch06s02.html#fig.errmsg-de-headers-sent" title='Figure 6.3. The "Header already sent" error message using German locale'>Figure 6.3. The "Header already sent" error message using German locale</a></p>
<div class="figure"><a name="fig.errmsg-de-headers-sent"></a><p class="title"><b>Figure 6.3. The "Header already sent" error message using German locale</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/errmsg-headersent-de.png" alt='The "Header already sent" error message using German locale'></div>
</div></div><br class="figure-break">
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>There is one potential issue with specifying the locale dynamically. Since
the call to set the locale happens in the script at a certain point this
means that if the error occur before that point the locale change has not
yet happened and the default locale specified in
<code class="filename">jpg-config.inc.php</code> will be used.</p>
</div>
</div>
<div class="sect2" title="Error messages on a production server"><div class="titlepage"><div><div><h3 class="title"><a name="id2495515"></a>Error messages on a production server</h3></div></div></div>
<p>On a production server it is common not to show detailed specific error
messages to the public which could potentially give a away security
vulnerabilities. For this purpose there is a "pseudo" locale of the error
messages. This is specified by setting the locale (as described above) to the
string "prod". If this is done a generic error message with an error code will
be shown instead. The custom support receiving information on this error can
then pass on the detailed error code to the development team for further
investigation. In <a class="xref" href="ch06s02.html#fig.pseudo-locale" title='Figure 6.4. Using the production "pseudo" locale'>Figure 6.4. Using the production "pseudo" locale</a> the same error as is shown in <a class="xref" href="ch06.html#fig.errmsg-ex1" title="Figure 6.1. Typical image error message">Figure 6.1. Typical image error message</a> is displayed using the "prod" locale. As you
can see in this case only a more end-user appropriate message together with the
error code is displayed.</p>
<div class="figure"><a name="fig.pseudo-locale"></a><p class="title"><b>Figure 6.4. Using the production "pseudo" locale</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/errmsg-prod.png" alt='Using the production "pseudo" locale'></div>
</div></div><br class="figure-break">
<p>The problem number corresponds to the error codes that are listed in <a class="xref" href="aph.html" title="Appendix H. Error messages">Appendix H. <i>Error messages</i></a></p>
<p>
</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
<p>It is possible to customize this "production" error message by
changing the actual text in the file
"<code class="filename">lang/prod.inc.php</code>"</p>
</div><p>
</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch06.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,148 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Using PHP Exceptions</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch06.html" title="Chapter 6. Error handling"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Using PHP Exceptions</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 6. Error handling</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Using PHP Exceptions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2495627"></a>Using PHP Exceptions</h2></div></div></div>
<p>Starting with version v2.5 the library now have full support for PHP5 style
exceptions. The library provides an exception class named
<code class="code">JpGraphException</code> which is slightly different compared with
traditional exception classes in that this class can not only return an text string
as error but also an image. This is necessary in order to handle the case where a
script has an error and is called from within an <span class="markup">&lt;img&gt;</span> tag. The
only data that can then be displayed in a browser is image data and hence it is
necessary for the error to be formatted as an image.</p>
<p>In addition to providing an exception class the library also installs its own
default exception handler to properly display an image. This default exception
handler will be automatically called whenever an "uncaught" exception would
otherwise be generated. This means that it is strictly not necessary to use
"<code class="code">try {} catch() {}</code>" blocks around the library scripts.</p>
<p>When an exception is generated the default exception handler first validates that
the exception is a proper descendant of <code class="code">JpGraphException</code> and if so,
generates the image by calling the <code class="code">JpgraphException::Stroke()</code> method.
If the exception is not a <code class="code">JpGraphException</code> based exception then the
handler re-raises the error. This means that in script that you create that is meant
to be called from within an <span class="markup">&lt;img&gt;</span> tag all exception should be a
derivate of <code class="code">JpGraphException</code> in order to properly generate an error
image.</p>
<p>A typical example on how to raise an exception in your own code is shown in <a class="xref" href="ch06s03.html#ex.jpgraphexception1" title="Example 6.1. Throwing a JpGraph exception">Example 6.1. Throwing a JpGraph exception</a></p>
<p>
</p><div class="example"><a name="ex.jpgraphexception1"></a><p class="title"><b>Example 6.1. Throwing a JpGraph exception</b></p><div class="example-contents">
<div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-reserved">throw</span><span class="hl-code"> </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">JpGraphException</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string"> ... some error message ...</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div>
</div></div><p><br class="example-break">
</p>
<p>In case you need to handle the exception in a "<code class="code">try {} catch() {}</code>"
block (perhaps in order to do necessary cleanup) it is important to remember to call
the <code class="code">Stroke()</code> method which will create and stream the error message back
to the browser. An example of this is shown in <a class="xref" href="ch06s03.html#ex.jpgraphexception2" title="Example 6.2. Catching a JpGraph exception and sending it back as an image to the client">Example 6.2. Catching a JpGraph exception and sending it back as an image to the
client</a></p>
<p>
</p><div class="example"><a name="ex.jpgraphexception2"></a><p class="title"><b>Example 6.2. Catching a JpGraph exception and sending it back as an image to the
client</b></p><div class="example-contents">
<div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-reserved">try</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code"> = </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">Graph</span><span class="hl-brackets">(</span><span class="hl-var">$width</span><span class="hl-code">,</span><span class="hl-var">$height</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> ... Code to setup the graph</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">if</span><span class="hl-brackets">(</span><span class="hl-code"> </span><span class="hl-comment">/*</span><span class="hl-comment"> some error condition </span><span class="hl-comment">*/</span><span class="hl-code"> </span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-reserved">throw</span><span class="hl-code"> </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">JpGraphException</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string"> ... some error message ...</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-brackets">}</span><span class="hl-code">
</span><span class="hl-brackets">}</span><span class="hl-code"> </span><span class="hl-reserved">catch</span><span class="hl-code"> </span><span class="hl-brackets">(</span><span class="hl-code"> </span><span class="hl-identifier">JpGraphException</span><span class="hl-code"> </span><span class="hl-var">$e</span><span class="hl-code"> </span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> .. do necessary cleanup</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Send back error message</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$e</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Stroke</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-brackets">}</span><span class="hl-code">
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div>
</div></div><p><br class="example-break">
</p>
<p>
</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
<p>Another typical augmentation of the exception handling might be to also
log an error to some logging server or plain log file. This should be done
before the call to <code class="code">Stroke()</code> since that call will never
return.</p>
</div><p>
</p>
<p>An example of real life error handling with exception is shown in listing <a class="xref" href="ch04s02.html#sec.preparing-sunspots-data" title="Preparing the data">Preparing the data</a> in the introductory example with Sun
spots.</p>
<div class="sect2" title="Selecting between text and image based error handling"><div class="titlepage"><div><div><h3 class="title"><a name="id2495896"></a>Selecting between text and image based error handling</h3></div></div></div>
<p>By default an exception that occurs in the library will create an error image
as shown in the previous section. However there might be circumstance where a
text based error handling is preferred (usually when graph are created from the
command line). </p>
<p>This could be accomplished in two ways. By catching the exception in the
script and handle it accordingly or we could slightly modify the default
behavior of the default exception handler in the library. How this is done will
now be described.</p>
<p>In order to enable a text based error handler we just need to disable the
image based error handler. This is done with a call to the method</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">JpGraphError::SetImageFlag($aFlag)</code></p>
</li></ul></div><p>
</p>
<p>Since the error handling have global scope this is a static function which can
be called as the following example shows</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">JpGraphError::SetImageFlag(false); // Enable text based error handling</span></pre></td></tr></table></div><p>
</p>
<p>Adding the line above to a graph script will cause any error to be printed to
<code class="code">STDERR</code> when the script is called from the command line. This is
a very convenient way to show errors when command line constructions like</p>
<p>
</p><pre class="screen">$&gt; php mygraph.php &gt; mygraph.png</pre><p>
</p>
<p>is used since writing the error to <code class="code">STDOUT</code> will cause the error
message to be sent back to the console since the call above only redirected
<code class="code">STDOUT</code> and not <code class="code">STDERR</code>. </p>
<p>When the script is called from PHP embedded in a HTTP server (e.g. Apache)
there is no concept of a <code class="code">STDERR</code> and the error message will just be
sent back as normal text to the browser.</p>
</div>
<div class="sect2" title="Writing error message to a log file (or system logger)"><div class="titlepage"><div><div><h3 class="title"><a name="id2495901"></a>Writing error message to a log file (or system logger)</h3></div></div></div>
<p>In addition to the option of having the error sent back as a string to the
client it can instead be written to a named log file. The log file name is
specified with a call to the (static) method</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">JpGraphError::SetLogFile($aFileName)</code></p>
</li></ul></div><p>
</p>
<p>The file needs to be writable by the PHP process. All error messages are
appended to the end of the file and each error message is prepended by the date
and time (in <code class="uri"><a class="uri" href="http://www.faqs.org/rfcs/rfc2822" target="_top">RFC 2822</a></code> formatted
date).</p>
<p>If the filename is given as the string <code class="code">'syslog'</code> then the error
message will be written to the default system logger instead. When a script is
run from, for example, Apache this is normally on Unix
'<code class="filename">/var/log/apache2/error_log</code>'</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch06.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,22 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Adding a new locale</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch06.html" title="Chapter 6. Error handling"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Adding a new locale</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 6. Error handling</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Adding a new locale"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2495754"></a>Adding a new locale</h2></div></div></div>
<p>All error messages are stored in an array with a specific index that cannot be
changed. This index is used in the library to reference a specific error message. </p>
<p>Since error messages can also have additional parameters the error messages also
includes count that specifies how many arguments must be handled to enable some
error checking when using the error message in the code (to make sure we have enough
arguments).</p>
<p>The arguments are formatted in the error text in the same way as parameters in the
<code class="code">printf()</code> family of functions.</p>
<p>To create a localized error resource file You should first copy the
"<code class="filename">en.inc.php</code>" to a temporary file, rename it according to
the locale you are creating and then translate each error message according to the
locale. The make sure that the file is stored under the
"<code class="filename">jpgraph/lang/</code>" catalogue and the new localized error
messages can be used. </p>
<p>For example. To create a French version of the error messages the
<code class="filename">lang/en.inc.php</code> should be copied to
<code class="filename">lang/fr.inc.php</code> and the error messages translated. The
French locale can then be used by using the string "<code class="code">fr</code>" as identified
in <code class="code">SettErrLocale()</code> as described above.</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch06.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,40 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 7. Color handling</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt02.html" title="Part II. Basic graph creation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 7. Color handling</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part II. Basic graph creation</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="chapter" title="Chapter 7. Color handling"><div class="titlepage"><div><div><h2 class="title"><a name="chap.color-handling"></a>Chapter 7. Color handling</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ch07.html#id2496153">7.1. Specifying colors by name</a></span></dt><dt><span class="sect1"><a href="ch07s02.html">7.2. Specifying colors by RGB triples</a></span></dt><dt><span class="sect1"><a href="ch07s03.html">7.3. Using HTML color specifications</a></span></dt><dt><span class="sect1"><a href="ch07s04.html">7.4. Fine tuning the color</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch07s04.html#sec2.alpha-channel">7.4.1. Specifying the alpha channel (color transparency)</a></span></dt><dt><span class="sect2"><a href="ch07s04.html#id2496356">7.4.2. Adjusting the brightness</a></span></dt><dt><span class="sect2"><a href="ch07s04.html#id2496665">7.4.3. Combining brightness and transparency adjustment</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch07s05.html">7.5. Additional color handling</a></span></dt></dl></div>
<p>An important part of creating visually clear graphs is the use of appropriate colors.
In order to simplify color handling JpGraph supports several ways to adjust and
manipulate color both by value and by name. </p>
<p>Almost all color setting methods (with basically only one exception) for all objects
in the graph has one of two names</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">SetColor()</code>, Sets the outline color or if the object only have
one color (e.g. a font) it sets this color</p>
</li><li class="listitem">
<p><code class="code">SetFillColor()</code>, Specifies the area fill color for objects
which has a concept of an area.</p>
</li></ul></div><p>Both variants of methods take one argument which identifies the color by
one of the available color specification methods as described below.</p>
<div class="sect1" title="Specifying colors by name"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2496153"></a>Specifying colors by name</h2></div></div></div>
<p>There are a number of "standard colors" known by (more or less) illustrative
names. A list of all color names that can be used as well as actual color can be
found in <a class="xref" href="apd.html" title="Appendix D. Named color list">Appendix D. <i>Named color list</i></a>. </p>
<p>For example:</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">SetColor('white');</code></p>
</li><li class="listitem">
<p><code class="code">SetFillColor('orange');</code></p>
</li></ul></div><p>
</p>
<p>
</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
<p>Always use single quotes for strings when you do not need variable
substitution since this is faster.</p>
</div><p>
</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt02.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,21 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Specifying colors by RGB triples</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch07.html" title="Chapter 7. Color handling"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Specifying colors by RGB triples</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 7. Color handling</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Specifying colors by RGB triples"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2496141"></a>Specifying colors by RGB triples</h2></div></div></div>
<p>Using the named colors will of course be restricted to the colors known by the
library. If some other colors are needed then they must be specified
manually.</p>
<p>The first variant uses the RGB values for the color, i.e. the Red, Green and Blue
component of a color. Each component is specified as an integer in the range [0,255]
and the triple is specified as an array.</p>
<p>For example:</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">SetColor( array(255,255,255));</code></p>
</li><li class="listitem">
<p><code class="code">SetColor( array(0xff,0xff,0xff));</code></p>
</li><li class="listitem">
<p><code class="code">SetFillColor( array(0x44,0x54,0xa4));</code></p>
</li></ul></div><p>
</p>
<p>As usual a value of <code class="code">array(0,0,0)</code> specifies black and a value of
<code class="code">array(255,255,255)</code> specifies white.</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch07.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,18 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Using HTML color specifications</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch07.html" title="Chapter 7. Color handling"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Using HTML color specifications</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 7. Color handling</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Using HTML color specifications"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2496287"></a>Using HTML color specifications</h2></div></div></div>
<p>The second variant is more a less a the same as the RGB triples but instead of an
array the RGB triple is specified as a string with the hexadecimal RGB values. This
is commonly known as the "HTML color specification" since this form often used when
creating WEB pages (for example in CSS sheets).</p>
<p>For example:</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">SetColor('#333')</code>, note that this is a short form for
<code class="code">SetColor('#333333')</code></p>
</li><li class="listitem">
<p><code class="code">SetColor('#12be7a')</code></p>
</li><li class="listitem">
<p><code class="code">SetFillColor('#99eff5')</code></p>
</li></ul></div><p>
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch07.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,103 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Fine tuning the color</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch07.html" title="Chapter 7. Color handling"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Fine tuning the color</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 7. Color handling</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Fine tuning the color"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2496338"></a>Fine tuning the color</h2></div></div></div>
<div class="sect2" title="Specifying the alpha channel (color transparency)"><div class="titlepage"><div><div><h3 class="title"><a name="sec2.alpha-channel"></a>Specifying the alpha channel (color transparency)</h3></div></div></div>
<p>Colors can also be made semi-transparent by specifying a transparency value
(or as it is also known an <span class="italic">alpha channel value</span>). This will instruct the
library to mix the foreground color with a certain amount of the background
colors creating a "shine-through" effect.</p>
<p>The alpha channel is specified as a real number in the range [0.0, 1.0] where
0.0 means no transparency and 1.0 means full transparency (i.e. only the
background color is shown). The transparency is added as a postfix to the color
specification separated by a '@' (at) character. It is often most used with area
fills (i.e. when using <code class="code">SetFillColor()</code>)</p>
<p>For example the following are valid alpha channel modifiers</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">SetFillColor('red@0.2')</code>, A slightly transparent red
color</p>
</li><li class="listitem">
<p><code class="code">SetFillColor('red@0.8')</code>, An almost completely
transparent color</p>
</li></ul></div><p>
</p>
<p>The result of using different alpha modifiers are shown in <a class="xref" href="ch07s04.html#fig.alpha-channel" title="Figure 7.1. Using alpha channel modifiers">Figure 7.1. Using alpha channel modifiers</a> where the blue color is made more and more
transparent to allow the red bar in the background to become more and more
visible.</p>
<p>
</p><div class="figure"><a name="fig.alpha-channel"></a><p class="title"><b>Figure 7.1. Using alpha channel modifiers</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/alpha-channel.png" alt="Using alpha channel modifiers"></div>
</div></div><p><br class="figure-break">
</p>
<p>As a final example of how to use transparency we show a graph in <a class="xref" href="ch07s04.html#fig.barlinealphaex1" title="Figure 7.2. Making use of transparency to combine two plots (barlinealphaex1.php)">Figure 7.2. Making use of transparency to combine two plots <code class="uri"><a class="uri" href="example_src/barlinealphaex1.html" target="_top">(<code class="filename">barlinealphaex1.php</code>)</a></code> </a> that uses transparency to allow an area
plot to be mixed with a bar graph.</p>
<p>
</p><div class="figure"><a name="fig.barlinealphaex1"></a><p class="title"><b>Figure 7.2. Making use of transparency to combine two plots <code class="uri"><a class="uri" href="example_src/barlinealphaex1.html" target="_top">(<code class="filename">barlinealphaex1.php</code>)</a></code> </b></p><div class="figure-contents"> <span class="inlinemediaobject"><img src="images/barlinealphaex1.png" alt="Making use of transparency to combine two plots (barlinealphaex1.php)"></span> </div></div><p><br class="figure-break">
</p>
<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
<p>For all graph examples shown in this manual you can always click on the
file name in the title of the graph to view the actual source that created
the graph.</p>
</div>
</div>
<div class="sect2" title="Adjusting the brightness"><div class="titlepage"><div><div><h3 class="title"><a name="id2496356"></a>Adjusting the brightness</h3></div></div></div>
<p>Since all colors that can be displayed on a computer can be modeled with the
appropriate RGB triple the above ways will allow you to specify any colors you
might need. However, conceptually it might be easier to think of colors in terms
of "a light blue" instead of a modified RGB triple so the library allows you to
take a basic color and apply a brightness correction factor.</p>
<p>The brightness factor is a postfix to the color string separated from the core
color with a ':' (colon) character. The brightness factor is a real number in
the range of [0.0, 2.0]. Using a brightness factor of 0.0 means that the color
will be black (no brightness at all) and a factor of 2.0 means that the color is
white (maximum brightness). Using a factor of 1 will leave the original color
untouched.</p>
<p>The brightness factor can be specified for named and HTML colors, see <a class="xref" href="ch07s04.html#fig.orange-scale" title="Figure 7.3. Adjusting brightness of named color specifier">Figure 7.3. Adjusting brightness of named color specifier</a> and <a class="xref" href="ch07s04.html#fig.blueish-scale" title="Figure 7.4. Adjusting brightness of a HTML color specifier">Figure 7.4. Adjusting brightness of a HTML color specifier</a> for more examples how the factor adjusts
the color.</p>
<p>For example, the following code snippets show valid color brightness
modifiers</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">SetColor('red:0.8');</code>, A slightly darker red
color</p>
</li><li class="listitem">
<p><code class="code">SetColor('red:1.5');</code>, A brighter red color</p>
</li><li class="listitem">
<p><code class="code">SetColor('#3485a9:1.8);</code>, A bright blue-greenish
color</p>
</li></ul></div><p>
</p>
<div class="figure"><a name="fig.orange-scale"></a><p class="title"><b>Figure 7.3. Adjusting brightness of named color specifier</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/orange-scale.png" alt="Adjusting brightness of named color specifier"></div>
</div></div><br class="figure-break">
<div class="figure"><a name="fig.blueish-scale"></a><p class="title"><b>Figure 7.4. Adjusting brightness of a HTML color specifier</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/blueish-scale.png" alt="Adjusting brightness of a HTML color specifier"></div>
</div></div><br class="figure-break">
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>The brightness factor is a purely linear factor but due to the human eyes
non-linear sensitivity for colors the perceived difference between (for
example) "<code class="code">red:1.1</code>" and "<code class="code">red:1.2</code>" than between
"<code class="code">red:0.2</code>" and "<code class="code">red:0.3</code>" even though the
relative difference is the same.</p>
</div>
</div>
<div class="sect2" title="Combining brightness and transparency adjustment"><div class="titlepage"><div><div><h3 class="title"><a name="id2496665"></a>Combining brightness and transparency adjustment</h3></div></div></div>
<p>It is also possible to combine the two previous discussed modifiers. This is
done by first adding the transparency specifier and then the brightness
adjustment as the following examples demonstrates.</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">SetColor('red@0.7:1.2')</code>, A highly transparent
slightly bright red color</p>
</li><li class="listitem">
<p><code class="code">SetFillColor('#4545aa@0.3:1.5')</code>, A bright blueish
semi transparent color</p>
</li></ul></div><p>
</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch07.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,19 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Additional color handling</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch07.html" title="Chapter 7. Color handling"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Additional color handling</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 7. Color handling</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Additional color handling"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2496682"></a>Additional color handling</h2></div></div></div>
<p>Some plot types have additional color handling to facilitate easier handling and
differentiation between data sets.</p>
<p>
</p><div class="variablelist"><dl><dt><span class="term">Pie plots</span></dt><dd>
<p>Pie plots support the concept of color-themes. A color theme is
simple a set of colors used for consecutive slices within the Pie.
How to specify color-themes is further discussed in <a class="xref" href="ch16.html#sec.pie-color-themes" title="Specifying slice colors and using themes">Specifying slice colors and using themes</a>.</p>
</dd><dt><span class="term">Color maps</span></dt><dd>
<p>Matrix (Only available in the Pro-version) and contour plots also
have the concept of color maps. This is a range of colors used to
indicate the data in the plot. Examples of color maps can be found
in <a class="xref" href="ch22s08.html" title="Built in color maps">Built in color maps</a>. (Color maps are defined
and implemented in
"<code class="filename">jpgraph_colormap.inc.php</code>").</p>
</dd></dl></div><p>
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch07.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,97 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 8. Text and font handling</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt02.html" title="Part II. Basic graph creation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 8. Text and font handling</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part II. Basic graph creation</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="chapter" title="Chapter 8. Text and font handling"><div class="titlepage"><div><div><h2 class="title"><a name="chap.text_handling"></a>Chapter 8. Text and font handling</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ch08.html#id2496825">8.1. Different types of fonts</a></span></dt><dt><span class="sect1"><a href="ch08s02.html">8.2. Font families and font styles</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch08s02.html#id2496988">8.2.1. Default TrueType Font</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch08s03.html">8.3. Understanding text alignment and anchor point</a></span></dt><dt><span class="sect1"><a href="ch08s04.html">8.4. Rotating text</a></span></dt><dt><span class="sect1"><a href="ch08s05.html">8.5. Formatting text paragraphs</a></span></dt><dt><span class="sect1"><a href="ch08s06.html">8.6. Adding custom TTF fonts</a></span></dt><dt><span class="sect1"><a href="ch08s07.html">8.7. Inserting Unicode entities</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch08s07.html#id2499171">8.7.1. The utility class "SymChar"</a></span></dt><dt><span class="sect2"><a href="ch08s07.html#id2500148">8.7.2. Graph example with Greek labels</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch08s08.html">8.8. Character encoding</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch08s08.html#id2500277">8.8.1. Japanese encoding options</a></span></dt><dt><span class="sect2"><a href="ch08s08.html#id2500408">8.8.2. Chinese encoding options</a></span></dt><dt><span class="sect2"><a href="ch08s08.html#id2500502">8.8.3. Cyrillic encoding options</a></span></dt><dt><span class="sect2"><a href="ch08s08.html#id2500687">8.8.4. Hebrew encoding options</a></span></dt><dt><span class="sect2"><a href="ch08s08.html#id2500718">8.8.5. Greek encoding options</a></span></dt></dl></dd></dl></div>
<p>Before reading this chapter please make sure that your installation supports TTF fonts
if you intend to use them (See <a class="xref" href="ch03s02.html" title="Necessary system requirements for the library">Necessary system requirements for the library</a>). The rest of this chapter assumes that a working
installation with TTF fonts is available when needed.</p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>It is highly recommended to create a setup where TTF fonts work since the
visual quality is significantly better than for the built-in bitmap fonts. In
addition the bitmap fonts are restricted to only display plain 7-bit ASCII
characters which means that no accented characters can be displayed, for example
the Scandinavian characters "åäö".</p>
</div><p>
</p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>All files in the library are encoded in utf-8.</p>
</div><p>
</p>
<div class="sect1" title="Different types of fonts"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2496825"></a>Different types of fonts</h2></div></div></div>
<p>The library supports two fundamental types of fonts.</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p><span class="bold"><strong>Bitmap fonts</strong></span></p>
<p>There are three built in bitmap fonts. They are available as font
families <code class="code">FF_FONT0</code>, <code class="code">FF_FONT1</code> and
<code class="code">FF_FONT2</code>. The advantage with bitmap fonts is that they
are always available in all installations of GD. However, bitmap fonts
only supports 7-bit ASCII so if you need to display any character from
the extended character set it is not possible to use bitmap fonts. The
available sizes of the bitmap fonts are also limited, the three
available size corresponds to the three families where
<code class="code">FF_FONT0</code> is the smallest and <code class="code">FF_FONT2</code> the
largest available bitmap font.</p>
<p>Bitmap fonts also has a more "rugged" look since they do not use
anti-aliasing.</p>
<p><span class="bold"><strong>Example:</strong></span>
<span class="italic">The following script lines shows a typical use of bit
map font specified for the title of a graph</span></p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code"> = </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">Graph</span><span class="hl-brackets">(</span><span class="hl-code">....</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Adjust the title to use the largest built-in bitmap font in bold face</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">title</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetFont</span><span class="hl-brackets">(</span><span class="hl-identifier">FF_FONT2</span><span class="hl-code">,</span><span class="hl-identifier">FS_BOLD</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div><p>
</p>
<p>The remainder of this chapter will describe this in more
details.</p>
</li><li class="listitem">
<p><span class="bold"><strong>TTF Fonts (True Type Fonts)</strong></span></p>
<p>True Type Fonts (TTF) give a much better visual quality of the text.
They are available in all sizes and there are many more font family to
choose from. All font family specification apart from the three bitmap
fonts are TTF fonts. In order to use these fonts the installation must
be configured in the right way which is described in <a class="xref" href="ch03s02.html" title="Necessary system requirements for the library">Necessary system requirements for the library</a>. It is necessary to use TTF fonts in
order to display extended character sets (outside the traditional 7-bit
ASCII). TTF fonts must also be used when inserting unicode entities as
described in <a class="xref" href="ch08s07.html" title="Inserting Unicode entities">Inserting Unicode entities</a></p>
<p>In order to be able to use TTF fonts it is necessary to check if the
installations supports this. See <a class="xref" href="ch03s02.html" title="Necessary system requirements for the library">Necessary system requirements for the library</a></p>
<p><span class="bold"><strong>Example:</strong></span>
<span class="italic">The following script lines shows a typical use of the
Arial TTF fonts for the title of a graph</span></p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code"> = </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">Graph</span><span class="hl-brackets">(</span><span class="hl-code">....</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Adjust the title to use 14pt Arial bold face</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">title</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetFont</span><span class="hl-brackets">(</span><span class="hl-identifier">FF_ARIAL</span><span class="hl-code">,</span><span class="hl-identifier">FS_BOLD</span><span class="hl-code">,</span><span class="hl-number">14</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div><p>
</p>
</li></ol></div><p>
</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt02.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,113 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Font families and font styles</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch08.html" title="Chapter 8. Text and font handling"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Font families and font styles</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 8. Text and font handling</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Font families and font styles"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2496973"></a>Font families and font styles</h2></div></div></div>
<div class="sect2" title="Default TrueType Font"><div class="titlepage"><div><div><h3 class="title"><a name="id2496988"></a>Default TrueType Font</h3></div></div></div>
<p>Prior to ver. 3.5, bitmap fonts are used by default which can specified from <code class="code">FF_FONT0</code> to <code class="code">FF_FONT2</code>. From version 3.5, default fonts are now set to one of the open-source TrueType DejaVu font (<code class="code">FF_DV_SANSSERIF</code>, DejaVuSans.ttf). This TrueType font is included in JpGraph source code (src/fonts), and there is no need to specify font for this one.</p>
<p>You can change default font family by changing <code class="code">FF_DEFAULT</code> defined in <code class="filename">jpgraph_ttf.inc.php</code>. You have to prepare your own font file as well in order to use another font.</p>
<p>If Freetype library is not usable in your PHP configuration, original BITMAP font will be used for compatibility.</p>
<p>All graph objects that uses text allows you to specify the font to be used by
calling a <code class="code">SetFont()</code> method and specifying three parameters.</p>
</div>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>The font family. This could for example be "Arial", "Times roman" for
TTF fonts or "Bitmap font medium size" when using bit-mapped fonts. The
font family is specified by using a symbolic constant that starts with
the prefix "<code class="code">FF_</code>" (for <span class="bold"><strong>F</strong></span>ont <span class="bold"><strong>F</strong></span>amily). A list of all supported font
families are shown in <a class="xref" href="ch08s02.html#table.font-families" title="Table 8.2. Supported Latin Font family specifiers">Table 8.2. Supported Latin Font family specifiers</a>.</p>
</li><li class="listitem">
<p>The font style. This specifies if the font should be emphasized as
italic, bold, or bold-italic. By default all fonts are rendered with the
"normal" style. The fonts style is specified with a symbolic constant
that starts with the prefix "<code class="code">FS_</code>" (for <span class="bold"><strong>F</strong></span>ont <span class="bold"><strong>S</strong></span>tyle). The supported font styles are:</p>
<p>
</p><div class="table"><a name="id2497107"></a><p class="title"><b>Table 8.1. Supported Font Styles</b></p><div class="table-contents">
<table summary="Supported Font Styles" border="1"><colgroup><col class="c1"><col class="c2"></colgroup><thead><tr><th>Font style specifier</th><th>Description</th></tr></thead><tbody><tr><td>FS_NORMAL</td><td>Normal font style</td></tr><tr><td>FS_BOLD</td><td>Bold font style</td></tr><tr><td>FS_ITALIC</td><td>Italic font style</td></tr><tr><td>FS_BOLDITALIC</td><td>Bold + Italic style for font families that
support this</td></tr></tbody></table>
</div></div><p><br class="table-break">
</p>
<p>Please note that not all font families support all available styles.
</p>
</li><li class="listitem">
<p>The font size. This is specified as an integer and depicts the size of
the font given in typographic points (pt). </p>
</li></ol></div><p>
</p>
<p>
</p><div class="table"><a name="table.font-families"></a><p class="title"><b>Table 8.2. Supported Latin Font family specifiers</b></p><div class="table-contents">
<table summary="Supported Latin Font family specifiers" border="1"><colgroup><col class="c1"><col class="c2"><col class="c3"><col class="newCol4"><col class="newCol5"><col class="newCol6"></colgroup><thead><tr><th>Font family name</th><th>Type</th><th>Comment</th><th>Bold</th><th>Italic</th><th>BI</th></tr></thead><tbody><tr><td>FF_FONT0</td><td>Bitmap</td><td>A very small font</td><td> </td><td> </td><td> </td></tr><tr><td>FF_FONT1</td><td>Bitmap</td><td>A medium sized font</td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td></tr><tr><td>FF_FONT2</td><td>Bitmap</td><td>The largest bit mapped font</td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td></tr><tr><td>FF_ARIAL</td><td>TTF</td><td>Arial font</td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td></tr><tr><td>FF_VERDANA</td><td>TTF</td><td>Verdana font</td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td></tr><tr><td>FF_COURIER</td><td>TTF</td><td>Fixed pitched Courier new font</td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td></tr><tr><td>FF_BOOK</td><td>TTF</td><td>Bookman</td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td></tr><tr><td>FF_COMIC</td><td>TTF</td><td>Comic sans</td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td> </td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td></tr><tr><td>FF_TIMES</td><td>TTF</td><td>Times New Roman</td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td></tr><tr><td>FF_GEORGIA</td><td>TTF</td><td>Georgia</td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td></tr><tr><td>FF_TREBUCHE</td><td>TTF</td><td>Trebuche</td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td></tr><tr><td>FF_VERA</td><td>TTF</td><td>Gnome Vera font. All Vera family fonts are available from <code class="uri"><a class="uri" href="http://www.gnome.org/fonts/" target="_top">http://www.gnome.org/fonts/</a></code>
</td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td></tr><tr><td>FF_VERAMONO</td><td>TTF</td><td>Gnome Vera Mono font</td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td></tr><tr><td>FF_VERASERIF</td><td>TTF</td><td>Gnome Vera Serif font</td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td> </td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td></tr><tr><td>FF_DV_SANSSERIF</td><td>TTF</td><td>DejaVu Font family. The DejaVu fonts are modifications of the
Bitstream Vera fonts designed to extend this original for
greater coverage of Unicode, as well as providing more styles.
These fonts are available from <code class="uri"><a class="uri" href="http://dejavu-fonts.org/" target="_top">http://dejavu-fonts.org/</a></code>
</td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td></tr><tr><td>FF_DV_SANSSERIFMONO</td><td>TTF</td><td>DejaVu Font family. </td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td></tr><tr><td>FF_DV_SANSSERIFCOND</td><td>TTF</td><td>DejaVu Font family. </td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td></tr><tr><td>FF_DV_SERIF</td><td>TTF</td><td>DejaVu Font family. </td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td></tr><tr><td>FF_DV_SERIFCOND</td><td>TTF</td><td>DejaVu Font family. </td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td><td><span class="inlinemediaobject"><img src="checkmark-plain.gif"></span></td></tr><tr><td>FF_CHINESE, FF_BIG5</td><td>TTF</td><td>
<p><span class="bold"><strong><span class="italic">Chinese font</span></strong></span>
(both symbolic names can be used). </p>
<p>The actual font file name used for the Chinese font is
"<code class="filename">bkai00mp.ttf</code>". The name of this
file can be changed in the define
<code class="code">CHINESE_TTF_FONT</code> available in the library
file <code class="filename">jpgraph_ttf.inc.php</code>
</p>
</td><td> </td><td> </td><td> </td></tr><tr><td>FF_SIMSUN</td><td>TTF</td><td>
<p><span class="bold"><strong><span class="italic">Chinese font.
</span></strong></span></p>
<p>The actual font file name is
"<code class="filename">simsun.ttc</code>"</p>
</td><td> </td><td> </td><td> </td></tr><tr><td>FF_MINCHO</td><td>TTF</td><td>
<p><span class="bold"><strong><span class="italic">Japanese
font.</span></strong></span></p>
<p>The actual font file name is
"<code class="filename">ipam.ttf</code>"</p>
</td><td> </td><td> </td><td> </td></tr><tr><td>FF_PMINCHO</td><td>TTF</td><td>
<p><span class="bold"><strong><span class="italic">Japanese
font.</span></strong></span></p>
<p>The actual font file name is
"<code class="filename">ipamp.ttf</code>"</p>
</td><td> </td><td> </td><td> </td></tr><tr><td>FF_GOTHIC</td><td>TTF</td><td>
<p><span class="bold"><strong><span class="italic">Japanese
font.</span></strong></span></p>
<p>The actual font file name is
"<code class="filename">ipag.ttf</code>"</p>
</td><td> </td><td> </td><td> </td></tr><tr><td>FF_PGOTHIC</td><td>TTF</td><td>
<p><span class="bold"><strong><span class="italic">Japanese
font.</span></strong></span></p>
<p>The actual font file name is
"<code class="filename">ipagp.ttf</code>"</p>
</td><td> </td><td> </td><td> </td></tr><tr><td>FF_DAVID</td><td>TTF</td><td>
<p><span class="bold"><strong><span class="italic">Hebrew
font.</span></strong></span></p>
<p>The actual font file name is
"<code class="filename">DAVIDNEW.TTF</code>"</p>
</td><td> </td><td> </td><td> </td></tr><tr><td>FF_MIRIAM</td><td>TTF</td><td>
<p><span class="bold"><strong><span class="italic">Hebrew
font.</span></strong></span></p>
<p>The actual font file name is
"<code class="filename">MRIAMY.TTF</code>"</p>
</td><td> </td><td> </td><td> </td></tr><tr><td>FF_AHRON</td><td>TTF</td><td>
<p><span class="bold"><strong><span class="italic">Hebrew
font.</span></strong></span></p>
<p>The actual font file name is
"<code class="filename">ahronbd.ttf</code>"</p>
</td><td> </td><td> </td><td> </td></tr></tbody></table>
</div></div><p><br class="table-break">
</p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>Depending on what versions of the DejaVu fonts are installed on the system
there are two naming conventions for the font files in common practice. The
library will try both naming convention to see if it can find the font
files.</p>
</div><p>
</p>
<p>In <a class="xref" href="ch08s02.html#fig.listfontsex1" title="Figure 8.1. List of all latin TTF fonts. (listfontsex1.php)">Figure 8.1. List of all latin TTF fonts. <code class="uri"><a class="uri" href="example_src/listfontsex1.html" target="_top">(<code class="filename">listfontsex1.php</code>)</a></code> </a> all latin fonts are shown.</p>
<p>
</p><div class="figure"><a name="fig.listfontsex1"></a><p class="title"><b>Figure 8.1. List of all latin TTF fonts. <code class="uri"><a class="uri" href="example_src/listfontsex1.html" target="_top">(<code class="filename">listfontsex1.php</code>)</a></code> </b></p><div class="figure-contents"> <span class="inlinemediaobject"><img src="images/listfontsex1.png" alt="List of all latin TTF fonts. (listfontsex1.php)"></span> </div></div><p><br class="figure-break">
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch08.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,48 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Understanding text alignment and anchor point</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch08.html" title="Chapter 8. Text and font handling"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Understanding text alignment and anchor point</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 8. Text and font handling</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Understanding text alignment and anchor point"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2498561"></a>Understanding text alignment and anchor point</h2></div></div></div>
<p>When a text string position is specified that screen (or scale) position by
default gets aligned with the top left corner of the strings bounding box. We say
that the top left corner is the <span class="italic">anchor point</span> of the text string. The alignment of the
anchor point can be adjusted with a call to <code class="code">Text::SetAlignment($aHorAlign,
$vertAlign)</code>. The two arguments are given as text strings and the
admissible values for each argument are: </p>
<p>
</p><div class="variablelist"><dl><dt><span class="term">Horizontal alignment</span></dt><dd>
<p><code class="code">'left'</code>, <code class="code">'center'</code>,
<code class="code">'right'</code></p>
</dd><dt><span class="term">Vertical alignment</span></dt><dd>
<p><code class="code">'bottom'</code>, <code class="code">'center'</code> (or
<code class="code">'middle'</code>) , <code class="code">'top'</code></p>
</dd></dl></div><p>
</p>
<div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3>
<p>Even though from an API perspective both bitmap fonts and TTF fonts share the
same user API the implementation is vastly different. There are a number of
subtle differences in the way built-in bit-map fonts and TrueType fonts are
rendered to the screen. This means for example that the alignment of, say the
bottom of the text string, is not pixel-perfect between bitmap and TrueType
fonts However, JpGraph, abstracts away 99.9% of the differences so it will be,
for all practical uses of the library completely transparent to switch between
the different font types.</p>
</div>
<p>Manually setting the alignment for the anchor point is mostly useful when adding
Text object to the graph to get the wanted alignment. You can see an example of how
the anchor point changes depending on how the combination of alignments are used in <a class="xref" href="ch08s03.html#fig.textalignex1" title="Figure 8.2. Illustration of anchor point alignment (textalignex1.php)">Figure 8.2. Illustration of anchor point alignment <code class="uri"><a class="uri" href="example_src/textalignex1.html" target="_top">(<code class="filename">textalignex1.php</code>)</a></code> </a></p>
<p>
</p><div class="figure"><a name="fig.textalignex1"></a><p class="title"><b>Figure 8.2. Illustration of anchor point alignment <code class="uri"><a class="uri" href="example_src/textalignex1.html" target="_top">(<code class="filename">textalignex1.php</code>)</a></code> </b></p><div class="figure-contents"> <span class="inlinemediaobject"><img src="images/textalignex1.png" alt="Illustration of anchor point alignment (textalignex1.php)"></span> </div></div><p><br class="figure-break">
</p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>It might seem strange to have the method name
"<code class="code">SetAlignment()</code>" when it really should make more sense to use
the name "<code class="code">SetAnchor()</code>". We agree. This naming scheme is due to
historical reasons.</p>
</div><p>
</p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>The graph legend box also have an anchor point that is specified as the
3:rd and 4:th argument to Legend::SetPos()</p>
</div><p>
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch08.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,33 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Rotating text</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch08.html" title="Chapter 8. Text and font handling"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Rotating text</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 8. Text and font handling</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Rotating text"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2498734"></a>Rotating text</h2></div></div></div>
<p>Both bit map and TTF fonts supports rotating text to different extent. With bit
map fonts it is only possible to use horizontal or vertical text, i.e. 0 or 90
degree rotation. TTF fonts supports arbitrary angles. If you are using a bit map
font and specifies an angle other than 0 or 90 then an error will be
displayed.</p>
<p>The most common usage for rotating text is probably to adjust the labels on the
x-axis so they are at 45 degrees angle. To rotate the label of an axis the method
<code class="code">Axis::SetLabelAngle()</code> should be used. <a class="xref" href="ch08s04.html#fig.bargradex1" title="Figure 8.3. Example of how to use rotated labels (bargradex1.php)">Figure 8.3. Example of how to use rotated labels <code class="uri"><a class="uri" href="example_src/bargradex1.html" target="_top">(<code class="filename">bargradex1.php</code>)</a></code> </a> shows an example of this (click on the filename
to view the actual code).</p>
<p>
</p><div class="figure"><a name="fig.bargradex1"></a><p class="title"><b>Figure 8.3. Example of how to use rotated labels <code class="uri"><a class="uri" href="example_src/bargradex1.html" target="_top">(<code class="filename">bargradex1.php</code>)</a></code> </b></p><div class="figure-contents"> <span class="inlinemediaobject"><img src="images/bargradex1.png" alt="Example of how to use rotated labels (bargradex1.php)"></span> </div></div><p><br class="figure-break">
</p>
<p>In addition to axis label it is also possible to
rotate almost every other text object with the exception of graph titles which is
always horizontal. For text objects (the class <code class="code">Text</code>) that can be added
to arbitrary positions on the graph the method <code class="code">Text::SetAngle()</code> can be
used to specify the wanted text angle. Another common place where text labels are
rotated is when individual data points are marked with labels. This could be done
for most plot types and in <a class="xref" href="ch08s04.html#fig.example20.3" title="Figure 8.4. Example of using rotated data point values (example20.3.php)">Figure 8.4. Example of using rotated data point values <code class="uri"><a class="uri" href="example_src/example20.3.html" target="_top">(<code class="filename">example20.3.php</code>)</a></code> </a> we show an example of using this for adding
labels to a basic bar plot (click on the filename to view source).</p>
<p>
</p><div class="figure"><a name="fig.example20.3"></a><p class="title"><b>Figure 8.4. Example of using rotated data point values <code class="uri"><a class="uri" href="example_src/example20.3.html" target="_top">(<code class="filename">example20.3.php</code>)</a></code> </b></p><div class="figure-contents"> <span class="inlinemediaobject"><img src="images/example20.3.png" alt="Example of using rotated data point values (example20.3.php)"></span> </div></div><p><br class="figure-break">
</p>
<p>
</p><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3>
<p>When rotating text paragraph the alignment (within the paragraph) will
always be reset to "left". It is not possible to use "center" or "right"
paragraph alignment in rotated texts.</p>
</div><p>
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch08.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,50 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Formatting text paragraphs</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch08.html" title="Chapter 8. Text and font handling"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Formatting text paragraphs</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 8. Text and font handling</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Formatting text paragraphs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2498877"></a>Formatting text paragraphs</h2></div></div></div>
<p>The text rendering engine within the library offers some basic text paragraph
formatting.</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p>It is possible to use multi line text combined as a paragraph</p>
</li><li class="listitem">
<p>It is possible to adjust the text alignment within the paragraph to be
left, right or center adjusted. This works in the same way as you would
expect in a word-processor.</p>
</li><li class="listitem">
<p>If enabled the text rendering will support automatic line breaks at a
certain column. The line breaks are intelligent not to break words in
the middle.</p>
</li></ul></div><p>
</p>
<p>All text handling is centralized to the class <code class="code">Text</code> (defined in file
<code class="filename">jpgraph_text.inc.php</code>) which is used both to add arbitrary
text to the graph as well as internally within the library to manipulate text on
labels and titles. All such texts are an instance of the Text class.</p>
<p>The paragraph alignment is controlled by the method
<code class="code">Text::SetParagraphAlign($aAlignment)</code>. The argument is a text string
that should be one of <code class="code">'left'</code>, <code class="code">'right'</code> or
<code class="code">'center'</code>. </p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>Unfortunately the library does not support an "even" paragraph alignment
which in word processors adjust the kerning between individual characters to
make the text have even left and right sides. Implementing this would
require a much higher complexity than can be motivated for the type of text
needed in a graph library.</p>
</div><p>
</p>
<p>In the <a class="xref" href="ch08s05.html#fig.textpalignex1" title="Figure 8.5. The different types of paragraph alignments (textpalignex1.php)">Figure 8.5. The different types of paragraph alignments <code class="uri"><a class="uri" href="example_src/textpalignex1.html" target="_top">(<code class="filename">textpalignex1.php</code>)</a></code> </a> the same text paragraph is rendered with the
possible paragraph alignments.</p>
<p>
</p><div class="figure"><a name="fig.textpalignex1"></a><p class="title"><b>Figure 8.5. The different types of paragraph alignments <code class="uri"><a class="uri" href="example_src/textpalignex1.html" target="_top">(<code class="filename">textpalignex1.php</code>)</a></code> </b></p><div class="figure-contents"> <span class="inlinemediaobject"><img src="images/textpalignex1.png" alt="The different types of paragraph alignments (textpalignex1.php)"></span> </div></div><p><br class="figure-break">
</p>
<p>Inserting a newline character "\n" in text will cause the text line to break and
start on the next row. Note that the newline must be surrounded with double-quotes
and not single quotes.</p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>Bitmap fonts that are rotated, i.e. vertical, does not support automatic
line breaking. If line breaking is needed with vertical text then one of the
TTF fonts muts be used.</p>
</div><p>
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch08.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,41 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Adding custom TTF fonts</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch08.html" title="Chapter 8. Text and font handling"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Adding custom TTF fonts</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 8. Text and font handling</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Adding custom TTF fonts"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec.adding-custom-ttf-fonts"></a>Adding custom TTF fonts</h2></div></div></div>
<p>In addition to the predefined fonts it is possible to easily use up to three
custom fonts. This is done by first specifying the name of the font file that should
be used and then specifying the font family as either <code class="code">FF_USERFONT1</code>,
<code class="code">FF_USERFONT2</code> or <code class="code">FF_USERFONT3</code>. A new font is installed
by calling one or more of the methods</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">Graph::SetUserFont1($aNormal,$aBold,$aItalic,$aBoldIt)</code>
(or the synonym <code class="code">SetUserFont()</code> )</p>
</li><li class="listitem">
<p><code class="code">Graph::SetUserFont2($aNormal,$aBold,$aItalic,$aBoldIt)</code></p>
</li><li class="listitem">
<p><code class="code">Graph::SetUserFont3($aNormal,$aBold,$aItalic,$aBoldIt)</code></p>
</li></ul></div><p>
</p>
<p>The argument to these methods should be the full font file name (including full
path) for the normal, bold, italic and/or bolditalic variant of the font family. All
arguments apart from "<code class="code">$aNormal</code>" are optional. </p>
<p>An example on how this can be used to use a special font for the title of a graph
is shown in
<a class="xref" href="ch08s06.html#ex.user-font-ex1" title="Example 8.1. Specifying and installing a user specified font">Example 8.1. Specifying and installing a user specified font</a></p>
<div class="example"><a name="ex.user-font-ex1"></a><p class="title"><b>Example 8.1. Specifying and installing a user specified font</b></p><div class="example-contents">
<div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> ...</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetUserFont</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">/usr/share/fonts/ttf/digital.ttf</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">title</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetFont</span><span class="hl-brackets">(</span><span class="hl-identifier">FF_USERFONT</span><span class="hl-code">,</span><span class="hl-identifier">FS_NORMAL</span><span class="hl-code">,</span><span class="hl-number">12</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">title</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Set</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">Test title </span><span class="hl-quotes">'</span><span class="hl-code">.</span><span class="hl-var">$pi</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> ...</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div>
</div></div><br class="example-break">
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch08.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,101 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Inserting Unicode entities</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch08.html" title="Chapter 8. Text and font handling"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Inserting Unicode entities</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 8. Text and font handling</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Inserting Unicode entities"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec.inserting-unicode"></a>Inserting Unicode entities</h2></div></div></div>
<p>One reason for using TTF fonts is the possibility to inserting unicode
character/entities. With this we mean characters from the extended range that are
not normally available on West european keyboards. This could for example be
classical Greek characters often used in mathematics, for example the symbol for
"pi". In order to make these and other commonly used "special" characters more
accessible the library provides a utility class that makes it easy to use these
characters without having to look up the corresponding unicode entities every
time.</p>
<p>In order to specify characters not available on the keyboard the normal way is to
specify there unicode code and included it in the text string with the prefix
"&amp;#". For example the unicode for the character "pi" is "03C0" in hex so to
include this character in a text string you would have to write "This is pi
&amp;#0960;" note that the code should be given in decimal encoding in the string
and always use 4 digits (pre-padded with 0:s as necessary). Since it is very tedious
to lookup and encode special characters the library offers a simpler way. The
<code class="code">SymChar</code> class. </p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>This section can be skipped at first reading without loss of
continuity.</p>
</div><p>
</p>
<div class="sect2" title='The utility class "SymChar"'><div class="titlepage"><div><div><h3 class="title"><a name="id2499171"></a>The utility class "SymChar"</h3></div></div></div>
<p>As described above it is tedious to have to lookup all the character codes. To
simplify this the SymChar class allows you to find these characters with the
english common name of these symbols instead. For example to create a string
with the Greek character "pi" one would have to write the code as shown
in.</p>
<div class="example"><a name="ex.sym-char-ex1"></a><p class="title"><b>Example 8.2. Using the SymChar class to display the Greek letter "pi"</b></p><div class="example-contents">
<div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> ...</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$pi</span><span class="hl-code"> = </span><span class="hl-identifier">SymChar</span><span class="hl-code">::</span><span class="hl-identifier">Get</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">pi</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">title</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Set</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">Test is pi</span><span class="hl-quotes">'</span><span class="hl-code">.</span><span class="hl-var">$pi</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> ...</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div>
</div></div><br class="example-break">
<p>All supported entities with there symbolic names are listed in <a class="xref" href="ch08s07.html#tab.sym-char-list" title="Table 8.3. Supported character entities in class SymChar">Table 8.3. Supported character entities in class SymChar</a>. The first argument to the static method
<code class="code">SymChar::Get()</code> should be the name of the entity and if the
second optional argument is true then the capital version (if it exists) of the
symbol should be returned.</p>
<p>
</p><div class="table"><a name="tab.sym-char-list"></a><p class="title"><b>Table 8.3. Supported character entities in class SymChar</b></p><div class="table-contents">
<table summary="Supported character entities in class SymChar" border="1"><colgroup><col class="c1"><col class="c2"><col class="c3"><col class="c4"></colgroup><thead><tr><th>Name</th><th>Unicode </th><th>Unicode capital</th><th>Comment</th></tr></thead><tbody><tr><td>"alpha"</td><td>03B1</td><td>0391</td><td>Greek character</td></tr><tr><td>"beta"</td><td>03B2</td><td>0392</td><td>Greek character</td></tr><tr><td>"gamma"</td><td>03B3</td><td>0393</td><td>Greek character</td></tr><tr><td>"delta"</td><td>03B4</td><td>0394</td><td>Greek character</td></tr><tr><td>"epsilon"</td><td>03B5</td><td>0395</td><td>Greek character</td></tr><tr><td>"zeta"</td><td>03B6</td><td>0396</td><td>Greek character</td></tr><tr><td>"ny"</td><td>03B7</td><td>0397</td><td>Greek character</td></tr><tr><td>"eta"</td><td>03B8</td><td>0398</td><td>Greek character</td></tr><tr><td>"theta"</td><td>03B8</td><td>0398</td><td>Greek character</td></tr><tr><td>"iota"</td><td>03B9</td><td>0399</td><td>Greek character</td></tr><tr><td>"kappa"</td><td>03BA</td><td>039A</td><td>Greek character</td></tr><tr><td>"lambda"</td><td>03BB</td><td>039B</td><td>Greek character</td></tr><tr><td>"mu"</td><td>03BC</td><td>039C</td><td>Greek character</td></tr><tr><td>"nu"</td><td>03BD</td><td>039D</td><td>Greek character</td></tr><tr><td>"xi"</td><td>03BE</td><td>039E</td><td>Greek character</td></tr><tr><td>"omicron"</td><td>03BF</td><td>039F</td><td>Greek character</td></tr><tr><td>"pi"</td><td>03C0</td><td>03A0</td><td>Greek character</td></tr><tr><td>"rho"</td><td>03C1</td><td>03A1</td><td>Greek character</td></tr><tr><td>"sigma"</td><td>03C3</td><td>03A3</td><td>Greek character</td></tr><tr><td>"tau"</td><td>03C4</td><td>03A4</td><td>Greek character</td></tr><tr><td>"upsilon"</td><td>03C5</td><td>03A5</td><td>Greek character</td></tr><tr><td>"phi"</td><td>03C6</td><td>03A6</td><td>Greek character</td></tr><tr><td>"chi"</td><td>03C7</td><td>03A7</td><td>Greek character</td></tr><tr><td>"psi"</td><td>03C8</td><td>03A8</td><td>Greek character</td></tr><tr><td>"omega"</td><td>03C9</td><td>03A9</td><td>Greek character</td></tr><tr><td>"euro"</td><td>20AC</td><td> </td><td>Monetary symbol</td></tr><tr><td>"yen"</td><td>00A5</td><td> </td><td>Monetary symbol</td></tr><tr><td>"pound"</td><td>20A4</td><td> </td><td>Monetary symbol</td></tr><tr><td>"approx"</td><td>2248</td><td> </td><td>Mathematical</td></tr><tr><td>"neq"</td><td>2260</td><td> </td><td>Mathematical</td></tr><tr><td>"not"</td><td>2310</td><td> </td><td>Mathematical</td></tr><tr><td>"def"</td><td>2261</td><td> </td><td>Mathematical</td></tr><tr><td>"inf"</td><td>221E</td><td> </td><td>Mathematical</td></tr><tr><td>"sqrt"</td><td>221A</td><td> </td><td>Mathematical</td></tr><tr><td>"int"</td><td>222B</td><td> </td><td>Mathematical</td></tr><tr><td>"copy"</td><td>00A9</td><td> </td><td>Misc symbols</td></tr><tr><td>"para"</td><td>00A7</td><td> </td><td>Misc symbols</td></tr><tr><td>"tm"</td><td>2122</td><td> </td><td>Misc symbols</td></tr><tr><td>"rtm"</td><td>00AE</td><td> </td><td>Misc symbols</td></tr></tbody></table>
</div></div><p><br class="table-break">
</p>
<p><a class="xref" href="ch08s07.html#fig.sym-char-list" title="Figure 8.6. Rendered symbol characters corresponding to">Figure 8.6. Rendered symbol characters corresponding to
</a> and <a class="xref" href="ch08s07.html#fig.sym-char-capital-list" title="Figure 8.7. Rendered capital symbol characters corresponding to Table 8.3. Supported character entities in class SymChar.">Figure 8.7. Rendered capital symbol characters corresponding to Table 8.3. Supported character entities in class SymChar. </a> shows how these symbol look when
they are rendered with the TTF font <span class="italic">Times Roman 14pt</span>. The symbols are in the same order
as in the table above and are visually grouped by there category as specified in
the column "Comment" in the table above.</p>
<p>
</p><div class="figure"><a name="fig.sym-char-list"></a><p class="title"><b>Figure 8.6. Rendered symbol characters corresponding to
</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/sym-char-list.png" alt="Rendered symbol characters corresponding to"></div>
</div></div><p><br class="figure-break">
</p>
<p>
</p><div class="figure"><a name="fig.sym-char-capital-list"></a><p class="title"><b>Figure 8.7. Rendered capital symbol characters corresponding to <a class="xref" href="ch08s07.html#tab.sym-char-list" title="Table 8.3. Supported character entities in class SymChar">Table 8.3. Supported character entities in class SymChar</a>. </b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/sym-char-list-capital.png" alt="Rendered capital symbol characters corresponding to ."></div>
</div></div><p><br class="figure-break">
</p>
</div>
<div class="sect2" title="Graph example with Greek labels"><div class="titlepage"><div><div><h3 class="title"><a name="id2500148"></a>Graph example with Greek labels</h3></div></div></div>
<p>In <a class="xref" href="ch08s07.html#fig.manualtickex2" title="Figure 8.8. Specifying manual ticks as fraction of Pi. (manualtickex2.php)">Figure 8.8. Specifying manual ticks as fraction of Pi. <code class="uri"><a class="uri" href="example_src/manualtickex2.html" target="_top">(<code class="filename">manualtickex2.php</code>)</a></code> </a> we have used the previous discussed
<code class="code">SymChar</code> class to more readily insert "π" characters in the
X-axis label. We highlight some functionality that we haven't yet discussed in
detail</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>We use a utility class (<code class="code">FuncGenerator</code> available in
"<code class="filename">jpgraph_utils.inc.php</code>") to help create
plot values from a mathematical expression. This will help create a
set of (x,y) points that can later on be used as the base for a data
series.</p>
</li><li class="listitem">
<p>The x-axis labels and the position of the tick marks on the x-axis
are manually positioned and specified to be positioned at "even"
fractions of π.</p>
</li></ol></div><p>
</p>
<p>
</p><div class="figure"><a name="fig.manualtickex2"></a><p class="title"><b>Figure 8.8. Specifying manual ticks as fraction of Pi. <code class="uri"><a class="uri" href="example_src/manualtickex2.html" target="_top">(<code class="filename">manualtickex2.php</code>)</a></code> </b></p><div class="figure-contents"> <span class="inlinemediaobject"><img src="images/manualtickex2.png" alt="Specifying manual ticks as fraction of Pi. (manualtickex2.php)"></span> </div></div><p><br class="figure-break">
</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch08.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,127 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Character encoding</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch08.html" title="Chapter 8. Text and font handling"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Character encoding</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 8. Text and font handling</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Character encoding"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec1.character-encoding"></a>Character encoding</h2></div></div></div>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>If you are not using Japanese, Chinese, Cyrillic , Greek or Hebrew
languages then this section can be safely skipped.</p>
</div><p>The core problem for the library is that it has no way of knowing in what
input encoding the string given to the library is using. Hence it is necessary to,
sometime, tell the library what input encoding is being used in order for the
library to do necessary character encoding conversion to generate UTF-8 (or UTF-16)
as needed to properly render the TTF fonts. The specific encoding options for each
major supported locale are explained below.</p>
<p>By default all JpGraph library files and examples are encoded in UTF-8</p>
<p>All defines mentioned below can be found in the file
"<code class="filename">jpgraph_ttf.inc.php</code>" </p>
<div class="sect2" title="Japanese encoding options"><div class="titlepage"><div><div><h3 class="title"><a name="id2500277"></a>Japanese encoding options</h3></div></div></div>
<p>There is only one possible option that can be specified.</p>
<p>
</p><div class="table"><a name="id2500290"></a><p class="title"><b>Table 8.4. Japanese encoding options</b></p><div class="table-contents">
<table summary="Japanese encoding options" border="1"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><thead><tr><th>Symbolic define</th><th>Possible values </th><th>Description</th></tr></thead><tbody><tr><td><code class="code">ASSUME_EUCJP_ENCODING</code></td><td>true/false</td><td>Assumes that Japanese text have been entered in EUC-JP
encoding. If this define is true then conversion from EUC-JP
to UTF8 is done automatically in the library using the
<code class="code">mbstring</code> module in PHP. Note that the
multibyte extension in PHP is not normally enabled.</td></tr></tbody></table>
</div></div><p><br class="table-break">
</p>
<p>Otherwise it is assumed that the input characters are encoded in UTF-8.
Remember that to show the Japanese character sets (Kanji, Hiragana and Katakana)
one of the Japanese font families (<code class="code">FF_MINCHO</code>,
<code class="code">FF_PMINCHO</code>, <code class="code">FF_GOTHIC</code> or <code class="code">FF_PGOTHIC</code>)
must be specified. </p>
<p>An example of using Japanese locale together with Windrose plots can be seen
in <a class="xref" href="ch21s03.html#sec.windrose-locale-compass" title="Localizing the default names for the compass directions">Localizing the default names for the compass directions</a>.</p>
</div>
<div class="sect2" title="Chinese encoding options"><div class="titlepage"><div><div><h3 class="title"><a name="id2500408"></a>Chinese encoding options</h3></div></div></div>
<p>There are no specific settings that control the encoding. The following rules
are used depending on the font is specified. </p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>If the font is specified as <code class="code">FF_SIMSUN</code> the built-in
library conversion from GB2312 to UTF-8 will be used. This
translation table is stored in the file
<code class="filename">jpgraph_gb2312.inc.php</code>.</p>
</li><li class="listitem">
<p>If the font is specified as <code class="code">FF_CHINESE</code> then no
conversion is made since it is assumed that the input character
string is already in UTF-8 This only has the effect of changing the
font to the default Chinese font family.</p>
</li><li class="listitem">
<p>If the font is specified as <code class="code">FF_BIG5</code> then it is
assumed that the input character string is encoded in BIG5 and the
internal translation to UTF-8 is done by the <code class="code">iconv()</code>
function. This means that PHP must be built with
<code class="code">iconv()</code> support. By default this is not compiled
into PHP (needs the "<code class="code">--width-iconv</code>" when configured).
For more on building PHP with the right options see <a class="xref" href="api.html" title="Appendix I. Compiling PHP">Appendix I. <i>Compiling PHP</i></a>. If this method is not present
the library will generate the following an error message.</p>
</li></ol></div><p>
</p>
<p>An example of using Chinese encoding with Windrose plots can be seen in <a class="xref" href="ch21s03.html#fig.windrose_ex6.1" title="Figure 21.11. Using chinese fonts (windrose_ex6.1.php)">Figure 21.11. Using chinese fonts <code class="uri"><a class="uri" href="example_src/windrose_ex6.1.html" target="_top">(<code class="filename">windrose_ex6.1.php</code>)</a></code> </a>
</p>
</div>
<div class="sect2" title="Cyrillic encoding options"><div class="titlepage"><div><div><h3 class="title"><a name="id2500502"></a>Cyrillic encoding options</h3></div></div></div>
<p>In order to do proper translation to unicode from cyrillic the
<code class="code">LANGUAGE_CYRILLIC</code> define should be set to true. If you are
running the library in multiuser environment it might be necessary to also
adjust the <code class="code">LANGUGAE_CHARSET</code> define as described below.</p>
<p>
</p><div class="table"><a name="id2500523"></a><p class="title"><b>Table 8.5. Cyrillic encoding options</b></p><div class="table-contents">
<table summary="Cyrillic encoding options" border="1"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><thead><tr><th>Symbolic define</th><th>Possible values </th><th>Description</th></tr></thead><tbody><tr><td><code class="code">LANGUAGE_CYRILLIC</code></td><td>true/false</td><td>
<p>Special unicode cyrillic language support</p>
</td></tr><tr><td><code class="code">CYRILLIC_FROM_WINDOWS</code></td><td>true/false</td><td>
<p>If you are setting this config to true the conversion
will assume that the input text is encoded in windows
1251, if false it will assume koi8-r</p>
</td></tr><tr><td><code class="code">LANGUAGE_CHARSET</code></td><td>string</td><td>
<p>This constant is used to auto-detect whether cyrillic
conversion is really necessary if enabled. Just specify
the encoding used, e.g. 'windows-1251', with a variable
containing the input character encoding string of your
application calling JpGraph. </p>
<p>A typical such string would be 'UTF-8' or 'utf-8'. The
comparison is case-insensitive. If this charset is not a
'koi8-r' or 'windows-1251' derivate then no conversion
is done. This constant can be very important in
multi-user multi-language environments where a cyrillic
conversion could be needed for some cyrillic people and
resulting in just erroneous conversions for non cyrillic
language based people. </p>
<p>Example: In the free project management software
dotproject.net <code class="code">$locale_char_set</code> is
dynamically set by the language environment the user has
chosen. </p>
<p>Usage: <code class="code">define('LANGUAGE_CHARSET',
$locale_char_set);</code> where
<code class="code">$locale_char_set</code> is a GLOBAL (string)
variable from the application including JpGraph.</p>
</td></tr></tbody></table>
</div></div><p><br class="table-break">
</p>
</div>
<div class="sect2" title="Hebrew encoding options"><div class="titlepage"><div><div><h3 class="title"><a name="id2500687"></a>Hebrew encoding options</h3></div></div></div>
<p>There are no user adjustable settings. The conversion is made from iso to
unicode with the help of the PHP method "<code class="code">hebrev()</code>" which is used to
convert logical Hebrew text to visual text. This conversion is done
automatically when the font is one of <code class="code">FF_DAVID</code>,
<code class="code">FF_MIRIAM</code> or <code class="code">FF_AHRON</code></p>
</div>
<div class="sect2" title="Greek encoding options"><div class="titlepage"><div><div><h3 class="title"><a name="id2500718"></a>Greek encoding options</h3></div></div></div>
<p>In order to do proper translation to unicode from greek the
<code class="code">LANGUAGE_GREEK</code> define should be specified to true.</p>
<p>
</p><div class="table"><a name="id2500733"></a><p class="title"><b>Table 8.6. Greek encoding options</b></p><div class="table-contents">
<table summary="Greek encoding options" border="1"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><thead><tr><th>Symbolic define</th><th>Possible values </th><th>Description</th></tr></thead><tbody><tr><td><code class="code">LANGUAGE_GREEK</code></td><td>true/false</td><td>Special unicode greek language support</td></tr><tr><td><code class="code">GREEK_FROM_WINDOWS</code></td><td>true/false</td><td>If you are setting this define to true the conversion of
greek characters will assume that the input text is windows
1251</td></tr></tbody></table>
</div></div><p><br class="table-break">
</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch08.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,62 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 9. Using the JpGraph cache system</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt02.html" title="Part II. Basic graph creation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 9. Using the JpGraph cache system</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part II. Basic graph creation</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="chapter" title="Chapter 9. Using the JpGraph cache system"><div class="titlepage"><div><div><h2 class="title"><a name="chap.using-cache"></a>Chapter 9. Using the JpGraph cache system</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ch09.html#id2500903">9.1. Enabling the library cache system</a></span></dt><dt><span class="sect1"><a href="ch09s02.html">9.2. Permission settings for the cache files</a></span></dt><dt><span class="sect1"><a href="ch09s03.html">9.3. Using the cache in your script</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch09s03.html#id2535216">9.3.1. Manually controlling the cached image</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch09s04.html">9.4. Using the cache with Client Side Image Maps (CSIM)</a></span></dt></dl></div>
<p>To reduce load on the web server JpGraph implements an advanced caching system which
avoids the burden of always having to run the full image script. The library supports
two primary ways of significantly increase performance, using the built in cache system
described in this section and the use of a PHP accelerator described in <a class="xref" href="ch11.html" title="Chapter 11. NuSphere PHP accelerator">Chapter 11. <i>NuSphere PHP accelerator</i></a></p>
<p>Depending on the complexity of the image script, for example if it is doing several DB
lookups, the use of the library cache system (which will avoid running the graph scripts
completely if possible) can make a for very drastic performance increase.</p>
<p><a class="xref" href="ch09.html#fig.cache-overview" title="Figure 9.1. Library cache principle">Figure 9.1. Library cache principle</a>shows an overview of the cache system in the library.</p>
<p>
</p><div class="figure"><a name="fig.cache-overview"></a><p class="title"><b>Figure 9.1. Library cache principle</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/cache_principles.png" alt="Library cache principle"></div>
</div></div><p><br class="figure-break">
</p>
<p>The rationale behind this is the observation that very few graphs are really
real-time, i.e. needs to be updated absolutely every time the graphing script is called.
For many graphs in a WEB-environment one can often get good precision by restricting the
graphs to only be updated, say, a few times each day. Of course, if truly live data is
what is needed then the cache system can not be used since then, by the nature of live
data, the graph script must be called at each instance to get the latest available data,
most probably from a database.</p>
<div class="sect1" title="Enabling the library cache system"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2500903"></a>Enabling the library cache system</h2></div></div></div>
<p>The enabling and disabling of the cache system is controlled by three defines in
<code class="filename">jpg-config.php</code></p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p><code class="code">DEFINE("USE_CACHE",true)</code></p>
</li><li class="listitem">
<p><code class="code">DEFINE("READ_CACHE",true)</code></p>
</li><li class="listitem">
<p><code class="code">DEFINE("CACHE_DIR","/tmp/jpgraph_cache/")</code></p>
</li></ol></div><p>
</p>
<p>The first of these, <code class="code">USE_CACHE</code>, is the master-switch which must be set
to true to enable the caching system. </p>
<p>The second switch, <code class="code">READ_CACHE</code> very seldom needs to be changed. This
second switch basically tells whether or not JpGraph should ever look in the cache.
Setting this to false and the master-switch to true would then always generate a new
updated image file in the cache and this new image would be send back to the
browser. The main use for this (admittedly) strange setting is if you like to have
the side effect of the script that a fresh image is always stored in the cache
directory. </p>
<p>The third define is not really a switch but a directory specification that tells
the library what directory to use as the cache directory (where the cached images
are stored). </p>
<p>The cache directory (<code class="code">CACHE_DIR</code>) can be set to an arbitrary directory
but the important thing to keep in mind is that the cache directory must be read and
writable for the process running PHP. </p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>The directory name given should be an absolute directory path and <span class="bold"><strong>not</strong></span> a file path relative to the document
root.</p>
</div><p>
</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt02.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,25 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Permission settings for the cache files</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch09.html" title="Chapter 9. Using the JpGraph cache system"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Permission settings for the cache files</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 9. Using the JpGraph cache system</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Permission settings for the cache files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2500997"></a>Permission settings for the cache files</h2></div></div></div>
<p><span class="bold"><strong><span class="italic">Note: This section is only applicable to a Unix derivate
system which have the concepts of group and file
ownership.</span></strong></span></p>
<p>There are two additional settings that will allow the control of the group and
file permission settings</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p><code class="code">DEFINE('CACHE_FILE_GROUP','www')</code></p>
</li><li class="listitem">
<p><code class="code">DEFINE('CACHE_FILE_MOD',0664)</code></p>
</li></ol></div><p>
</p>
<p>The <code class="code">CACHE_FILE_GROUP</code> specifies what group should be set on the cached
image file. If this is left empty then the group will be the same as the process
running PHP.</p>
<p>The <code class="code">CACHE_FILE_MOD</code> specifies the file permissions for the image file.
If this is left empty the default permissions used by PHP will be set on the
file.</p>
<p>When PHP is run from the command line (using the PHP CLI version) then the file
permission and group will normally be set to the one of the suer running PHP. Keep
in mind that normally ordinary users are not allowed to change the group to
'<code class="code">www</code>' (the default Apache2 group).</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch09.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,188 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Using the cache in your script</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch09.html" title="Chapter 9. Using the JpGraph cache system"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Using the cache in your script</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 9. Using the JpGraph cache system</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Using the cache in your script"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2535042"></a>Using the cache in your script</h2></div></div></div>
<p>The principle of the library cache is as follows when it is enabled.</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>The first time the graph script is called everything will be as usual,
the script will run and in the end the script sends back the image to
the browser. However if the caching is enabled JpGraph will
automatically have stored a copy of the generated image in the cache
directory.</p>
</li><li class="listitem">
<p>When the graph script is executed the next time it checks to see if an
image corresponding to this graph script has already been generated and
is available in the cache directory.</p>
</li><li class="listitem">
<p>If the image is available in the cache directory the library check to
see how old the image is. If the images is older than a specified limit
than it assumes that the image is out dated and runs the graph script as
usual and makes sure the newly generated image is stored in the cache
directory. Hence replacing the outdated image.</p>
</li><li class="listitem">
<p>If the image in the cache directory was current (i.e. not too old) it
is read and send back to the clients (e.g. Web-browser) without the rest
of the graph script being executed.</p>
</li></ol></div><p>
</p>
<p>From the above description there are a couple of parameters that should be
specified, the name to use when the image is stored and the timeout value when the
image is considered too old, i.e. how long was it since the image was
generated.</p>
<p>The first parameter, the filename, can be either manually specified or the library
can create a filename based on the name of the graph script. </p>
<p>Both these parameters are specified in the initial <code class="code">Graph()</code> call where
a new graph instance is created. A basic example of this is shown in <a class="xref" href="ch09s03.html#example.auto-cache-filename" title="Example 9.1. Using an automatic cache filename and a 60min timeout of the cached images.">Example 9.1. Using an automatic cache filename and a 60min timeout of the cached
images.</a>.</p>
<p>
</p><div class="example"><a name="example.auto-cache-filename"></a><p class="title"><b>Example 9.1. Using an automatic cache filename and a 60min timeout of the cached
images.</b></p><div class="example-contents">
<div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> ... includes</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code"> = </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">Graph</span><span class="hl-brackets">(</span><span class="hl-var">$width</span><span class="hl-code">, </span><span class="hl-var">$height</span><span class="hl-code">, </span><span class="hl-quotes">'</span><span class="hl-string">auto</span><span class="hl-quotes">'</span><span class="hl-code">, </span><span class="hl-number">60</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> ... rest of the graph script</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Stroke</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div>
</div></div><p><br class="example-break">
</p>
<p>The code in <a class="xref" href="ch09s03.html#example.auto-cache-filename" title="Example 9.1. Using an automatic cache filename and a 60min timeout of the cached images.">Example 9.1. Using an automatic cache filename and a 60min timeout of the cached
images.</a>. will use an automatic filename for
the cached image and a make the image valid for 60 minutes. This means that if the
script is called again, within 60minutes, it will return the image just after the
initial <code class="code">Graph()</code> call and not execute any more lines of code in the
script.</p>
<p>For basic usage this is all that is necessary, enable the cache in the settings
and supply a filename and a timeout value. The rest of the logic is handled by the
library.</p>
<p>
</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
<p>If you want the timeout value to be "forever" then you can specify a
"<code class="code">0</code>" as the timeout value (or leave the parameter blank). To
regenerate the image you will have to manually remove the image files from
the cache. This removal could for example be handled by a nightly
cron-job.</p>
</div><p>
</p>
<p>There is however one caveat which must be understood when using the above
construction. The image/graph store in the cached file will be returned to the
browser as a side effect of the initial <code class="code">$graph = new Graph()</code>. This also
means that: </p>
<p><span class="bold"><strong>No lines after the initial Graph() call will be executed in the
image script in case the image exists in the cache directory.</strong></span></p>
<p>This is the expected behaviour since this means that no unnecessary code will be
executed in the graph script in case the image has been found in the image
cache.</p>
<p>However, for the case where some more control of exactly how a cached image is
sent back it is necessary to add some complexity by doing things less automatically.
This gives greater control but also is slightly more complex and is described in the
next section.</p>
<div class="sect2" title="Manually controlling the cached image"><div class="titlepage"><div><div><h3 class="title"><a name="id2535216"></a>Manually controlling the cached image</h3></div></div></div>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>These utility functions were added in <span class="bold"><strong>v3.0.5</strong></span> of the library. It is still possible
to do this in previous versions but then some more code is needed to
duplicate what these methods does. If this feature is wanted then it is
strongly advised to upgrade to this or later version.</p>
</div><p>
</p>
<p>There are two parts to doing this manually.</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Check if the cached image exists in the cache and is valid (i.e.
not too old)</p>
</li><li class="listitem">
<p>Stream the cached image file back to the browser in that
case</p>
</li></ol></div><p>
</p>
<p>If the cached image is not valid then we just need to construct the graph as
usual and it will be stored in the cache automatically.</p>
<p>The following code example shows how this is done in principle in a graph
script where we use automatic naming i.e. the cached file name will get a name
based on the script name. This is done with the library utility function
<code class="code">GenImgName()</code> which constructs a suitable image name from the
script name and with a proper image compression format (i.e png, jpg or
gif).</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-var">$width</span><span class="hl-code"> = ...;
</span><span class="hl-var">$height</span><span class="hl-code"> = ...;
</span><span class="hl-var">$cachefilename</span><span class="hl-code"> = </span><span class="hl-identifier">GenImgName</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$graph</span><span class="hl-code"> = </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">Graph</span><span class="hl-brackets">(</span><span class="hl-var">$width</span><span class="hl-code">,</span><span class="hl-var">$height</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Check if the cache file exists and is valid</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$valid</span><span class="hl-code"> = </span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">cache</span><span class="hl-code">-&gt;</span><span class="hl-identifier">IsValid</span><span class="hl-brackets">(</span><span class="hl-var">$cachefilename</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-reserved">if</span><span class="hl-brackets">(</span><span class="hl-code"> </span><span class="hl-var">$valid</span><span class="hl-code"> </span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> The cached file is valid and we can now do any necessary</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> processing and then send it back to the client</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-identifier">doSomeProcessingIfNecessary</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">cache</span><span class="hl-code">-&gt;</span><span class="hl-identifier">StreamImgFile</span><span class="hl-brackets">(</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">img</span><span class="hl-code">,</span><span class="hl-var">$cachefilename</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-brackets">}</span><span class="hl-code"> </span><span class="hl-reserved">else</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> The cache file is not valid or does not exists so we</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> must construct the graph as normal</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Tell the graph that we want to cache this image</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$timeout</span><span class="hl-code"> = ...;
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetupCache</span><span class="hl-brackets">(</span><span class="hl-var">$cachefilename</span><span class="hl-code">,</span><span class="hl-var">$timeout</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> The remainder of a normal graph script</span><span class="hl-comment"></span><span class="hl-code">
...
</span><span class="hl-comment">//</span><span class="hl-comment"> .. and send back the image as usual (this will also store</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> a copy of the image in the cache directory)</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Stroke</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-brackets">}</span></pre></td></tr></table></div><p>
</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch09.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,115 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Using the cache with Client Side Image Maps (CSIM)</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch09.html" title="Chapter 9. Using the JpGraph cache system"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Using the cache with Client Side Image Maps (CSIM)</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 9. Using the JpGraph cache system</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Using the cache with Client Side Image Maps (CSIM)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect1.cache-csim"></a>Using the cache with Client Side Image Maps (CSIM)</h2></div></div></div>
<p>(See <a class="xref" href="ch10.html" title="Chapter 10. Using CSIM (Client side image maps)">Chapter 10. <i>Using CSIM (Client side image maps)</i></a> for a full description on the usage of CSIM
together with the library)</p>
<p>You can also use the cache system for images that uses image maps (CSIM) as well.
The cache system interface is slightly different in this case since the cache needs
to store both the cached image and the cached image-map. It also needs to change due
to the added complexity with CSIM scripts not sending back an image but rather a
pre-formatted HTML page. The two major differences from the non-CSIM cache
is:</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>The cached version will <span class="bold"><strong>not</strong></span> be stored in the previous defined cache
directory. It uses a different cache directory.</p>
</li><li class="listitem">
<p>The script that want to make use of the cache system together with
CSIM must call an extra method, <code class="code">CheckCSIMCache()</code>, to check
the cache.</p>
</li></ol></div><p>
</p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>Please remember that when using CSIM you must end your script with a call
to <code class="code">Graph::StrokeCSIM()</code> method instead of the
<code class="code">Graph::Stroke()</code> used for non-CSIM. </p>
</div><p>
</p>
<p>To use the cache with CSIM you have to call the
<code class="code">Graph::CheckCSIMCache()</code>. As with the caching for non-CSIM you have
to supply a name to be used for the cached version (it can be manually or automatic)
as well as an optional timeout value. The default timeout value if nothing else is
specified is 60 minutes.</p>
<p>The name argument requires some more explanations. The file name must be specified
as a relative name. </p>
<p>For example "<code class="filename">myimage</code>" or perhaps
"<code class="filename">firstpage/image3</code>". </p>
<p>The reason for his is that a script that uses CSIM does not send back an image.
Instad it sends back a HTML page which includes the image map coordinates and has an
included "<span class="markup">&lt;img href=" ... "&gt;</span>" tag which references the image
script recursively in normal cases but if the image is found in the cache this
reference will be to a static image instead.</p>
<p>Depending on the installation of the library this will now end up in the directory
specified in the <code class="code">CSIMCACHE_DIR</code> define. This must also be a directory
accessible by the normal HTTP/PHP process. By default, if nothing else is specified,
a directory called "<code class="filename">csimcache</code>" will be created in the same
directory as the image script itself.</p>
<p>The default value has the drawback that the directory from where the script is
executed must also be writable by the process running PHP. Best practice here is to
keep the number of writable directory for PHP down to a minimum and re-use the same
directory as is used for the standard cache. </p>
<p>This however, requires that the PHP and HTTP setup is such that the cache
directory is also accessible by the HTTP server from the htdocs root.</p>
<p>The <code class="code">CheckCSIMCache()</code> method checks the cache for an existing cached
version and if found it returns it and halts execution of the script. So, this call
should be the first call after the creation of the core graph instance, i.e.
<code class="code">$graph = Graph($width,$height)</code> and before any heavy work is done to
create the image so that no unnecessary work is done in case a cached image + image
map is found.</p>
<p>The general structure of a script that uses CSIM and cache should follow the
template shown in </p>
<p>
</p><div class="example"><a name="id2535468"></a><p class="title"><b>Example 9.2. General structure for a CSIM script that uses CSIM</b></p><div class="example-contents">
<div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-reserved">require_once</span><span class="hl-brackets">(</span><span class="hl-code"> </span><span class="hl-quotes">'</span><span class="hl-string">jpgraph.php</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> ... any necessary includes</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$width</span><span class="hl-code"> = ...
</span><span class="hl-var">$height</span><span class="hl-code"> = ...
</span><span class="hl-var">$graph</span><span class="hl-code"> = </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">Graph</span><span class="hl-brackets">(</span><span class="hl-var">$width</span><span class="hl-code">,</span><span class="hl-var">$height</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Check cache and use a 10 min timeout</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">CheckCSIMCache</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">csim_image1</span><span class="hl-quotes">'</span><span class="hl-code">,</span><span class="hl-number">10</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> If a cached version exists, execution halts here</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> and the cached HTML image map is sent back</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> ... construct and format the graph</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> ... finally send back the image map HTML script</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">StrokeCSIM</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div>
</div></div><p><br class="example-break">
</p>
<p>Please note that it is not necessary to pass any argument to the final call of
StrokeCSIM()</p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>The CSIM caching works by storing two files in the cache directory. One
file being the image and the other file being the corresponding image map as
a pure HTML file. The HTML file will reference the static image.</p>
</div><p>
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch09.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,59 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 10. Using CSIM (Client side image maps)</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt02.html" title="Part II. Basic graph creation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 10. Using CSIM (Client side image maps)</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part II. Basic graph creation</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="chapter" title="Chapter 10. Using CSIM (Client side image maps)"><div class="titlepage"><div><div><h2 class="title"><a name="chap.using-csim"></a>Chapter 10. Using CSIM (Client side image maps)</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ch10.html#id2535547">10.1. The principles</a></span></dt><dt><span class="sect1"><a href="ch10s02.html">10.2. The basic structure of an image map script</a></span></dt><dt><span class="sect1"><a href="ch10s03.html">10.3. Specifying targets for image map plots</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch10s03.html#id2535974">10.3.1. Creating popup-windows as targets for CSIM</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch10s04.html">10.4. Using StrokeCSIM()</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch10s04.html#id2536113">10.4.1. Optional argument to StrokeCSIM()</a></span></dt><dt><span class="sect2"><a href="ch10s04.html#id2536192">10.4.2. How does StrokeCSIM() work?</a></span></dt><dt><span class="sect2"><a href="ch10s04.html#id2536305">10.4.3. Image maps and the cache system</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch10s05.html">10.5. Getting hold of the image map</a></span></dt><dt><span class="sect1"><a href="ch10s06.html">10.6. Mixing several CSIM images in an HTML page with text</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch10s06.html#sec2.adding-csim-in-html">10.6.1. Adding one CSIM graph in a HTML page</a></span></dt><dt><span class="sect2"><a href="ch10s06.html#id2536476">10.6.2. Adding multiple CSIM graphs in a HTML page</a></span></dt></dl></dd></dl></div>
<p>Image maps makes it possible to create images with "active" areas that will react for
a mouse-click. It is then up to the designer to decide what actions should be taken.
Image map is often used to create drill-down charts where it is possible to dynamically
zoom into an image. Image maps is part of the HTML standard.</p>
<p>There are actually two types of images maps, client and server-side. This refers to
where the actual processing of the image click happens. Without doubt the best (and most
commonly used) type is the client side. This is also what the library supports. In the
remainder of this manual this will be referred to as <span class="bold"><strong>CSIM</strong></span>, <span class="bold"><strong>C</strong></span>lient <span class="bold"><strong>S</strong></span>ide <span class="bold"><strong>I</strong></span>mage <span class="bold"><strong>M</strong></span>aps.</p>
<div class="sect1" title="The principles"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2535547"></a>The principles</h2></div></div></div>
<p>Image maps works so that each hotspot area in the graph that should be used must
have an associated URL. When the user clicks somewhere in that particular hotspot
area the browser will open the specified URL. Typical hotspot areas in the graphs
are</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Texts, for example titles</p>
</li><li class="listitem">
<p>Markers in line graphs</p>
</li><li class="listitem">
<p>Slices in pie graphs</p>
</li><li class="listitem">
<p>Legends</p>
</li><li class="listitem">
<p>Bars in barplots</p>
</li><li class="listitem">
<p>etc.</p>
</li></ol></div><p>
</p>
<p>The way the CSIM HTML standard works is that the HTML page must have a section
with coordinates that defines the various hotspots together with the associated URL
that should be called. Each section of coordinates are connected to a specific image
that is included with a standard <span class="markup">&lt;img&gt;</span> by a common id. This will
now add some complexity since the library must return an HTML page for the
coordinates and not image data as normal for the library. How this is done is the
topic of the next section.</p>
<p>A number of examples of CSIM graphs are included in the
<code class="filename">Examples/</code> directory. Some of the available examples are
listed in <a class="xref" href="ch10.html#tab.csim-examples-name" title="Table 10.1. CSIM Examples (in Examples/ directory)">Table 10.1. CSIM Examples (in Examples/ directory)</a></p>
<p>
</p><div class="table"><a name="tab.csim-examples-name"></a><p class="title"><b>Table 10.1. CSIM Examples (in Examples/ directory)</b></p><div class="table-contents">
<table summary="CSIM Examples (in Examples/ directory)" border="0"><colgroup><col class="c1"><col class="c2"></colgroup><thead><tr><th colspan="2">CSIM Examples (in Examples/ directory)</th></tr></thead><tbody><tr><td><code class="filename">bar_csimex1.php</code></td><td><code class="filename">bar_csimex2.php</code></td></tr><tr><td><code class="filename">bar_csimex3.php</code></td><td><code class="filename">barline_csimex1.php</code></td></tr><tr><td><code class="filename">barlinefreq_csimex1.php</code></td><td><code class="filename">boxstockcsimex1.php</code></td></tr><tr><td><code class="filename">ganttcsimex01.php</code></td><td><code class="filename">ganttcsimex02.php</code></td></tr><tr><td><code class="filename">imgmarkercsimex1.php</code></td><td><code class="filename">pie3d_csimex1.php</code></td></tr><tr><td><code class="filename">piec_csimex1.php</code></td><td><code class="filename">pie_csimex1.php</code></td></tr><tr><td><code class="filename">scatter_csimex1.php</code></td><td><code class="filename">titlecsimex01.php</code></td></tr></tbody></table>
</div></div><p><br class="table-break">
</p>
<p>In order to easily access all of these examples it is possible to call the
<code class="filename">testsuit.php</code> example with an additional argument
"<code class="code">t=2</code>". By following the link
"<code class="filename">testsuit.php?t=2</code>" a separate window will open with all the
possible CSIM examples.</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt02.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,39 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>The basic structure of an image map script</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch10.html" title="Chapter 10. Using CSIM (Client side image maps)"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">The basic structure of an image map script</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 10. Using CSIM (Client side image maps)</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="The basic structure of an image map script"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2535815"></a>The basic structure of an image map script</h2></div></div></div>
<p>The basic structure for a HTML page using client side image maps will have the
following layout</p>
<p>
</p><pre class="screen">// Image map specification with name "mapname"
&lt;MAP NAME=...&gt;
... specification ...
&lt;/MAP&gt;
// Image tag
&lt;img src="..." ISMAP USEMAP="mapname"&gt;
</pre><p>
</p>
<p>This poses an interesting question. Since we normally call the graphing script
directly in the <span class="markup">&lt;img&gt;</span> tag how do we get hold of the image map
(which is available only in the image script) in this "HTML wrapper" script?</p>
<p>In JpGraph there is actually two ways of solving this.</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Use the preferred "builtin" way using the modified
<code class="code">Stroke()</code> method <code class="code">StrokeCSIM()</code> instead of
the standard <code class="code">Graph::Stroke()</code> method.</p>
</li><li class="listitem">
<p>Directly use the <code class="code">Graph::GetHTMLImageMap()</code> which gives you
fine control at the expense of more complex coding. This is necessary if
several image map graphs are needed on the same page.</p>
</li></ol></div><p>
</p>
<p>The first (and preferred) way modifies the stroke method so that instead of
returning an image (like the standard <code class="code">Stroke()</code> method)
<code class="code">StrokeCSIM()</code> actually returns an HTML page containing both the
image map specification and the correct<code class="code"> &lt;IMG&gt;</code> tag.</p>
<p>This means that it is necessary to treat an image map returning image script
differently from a non-CSIM image script, for example it is not posible to use it
directly as the target for the "<code class="code">src</code>" attribute of the
<span class="markup">&lt;IMG&gt;</span> tag since it sends back a HTML page containing both an
image tag together with an image map.</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch10.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,37 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Specifying targets for image map plots</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch10.html" title="Chapter 10. Using CSIM (Client side image maps)"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Specifying targets for image map plots</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 10. Using CSIM (Client side image maps)</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Specifying targets for image map plots"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2535910"></a>Specifying targets for image map plots</h2></div></div></div>
<p>To turn a standard image script into a CSIM script the first thing needed to do is
to supply the appropriate URL targets for the hotspots in the image. What the
hotspots represent depends on the type of plot. CSIM is supported by all graph
types. </p>
<p>To specify a URI link for each hotspot the <code class="code">SetCSIMTargets()</code> method is
used on the graph object that should be given a hotspot.</p>
<p>There are two arguments to this method</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p><code class="code">$aTargets</code>, an array of valid URL targets. One URL per hot
spot, for example if you have a 10 values bar plot you need 10 URLs. If
the <code class="code">SetCSIMTarget()</code> is applied to, for example, a text then
only one URL target should be specified.</p>
</li><li class="listitem">
<p><code class="code">$aAlts</code>, an array of valid alt-texts. Many browsers (but
not all) will show this text string if the mouse hovers over a
hotspot.</p>
</li></ol></div><p>
</p>
<div class="sect2" title="Creating popup-windows as targets for CSIM"><div class="titlepage"><div><div><h3 class="title"><a name="id2535974"></a>Creating popup-windows as targets for CSIM</h3></div></div></div>
<p>URL targets specified will be opened by the browser as usual, i.e. it will
replace the current HTML page. Another common usage pattern is to opena popup
window, perhaps with a zoomed version of a graph. This can be done by adding
some javascript in the target URL. If the URL, for example, is specified
as</p>
<p>
</p><pre class="screen">$target = "...";
$targetURL = "javascript:window.open('$target?id=%d','_new','width=500,height=300');void(0)"</pre><p>
</p>
<p>clicking on a target will now open a separate window with the specified width
and height. The <code class="code">$target</code> variable must be set to the wanted
URL.</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch10.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,130 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Using StrokeCSIM()</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch10.html" title="Chapter 10. Using CSIM (Client side image maps)"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Using StrokeCSIM()</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 10. Using CSIM (Client side image maps)</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Using StrokeCSIM()"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2536011"></a>Using StrokeCSIM()</h2></div></div></div>
<p>The simplest way of creating a creating a CSIM image is with the
<code class="code">StrokeCSIM()</code> method. As mentioned before this method actually
returns a (small) HTML page containing both the image-tag as well as the image map
specification. Hence it is not possible to use a script that ends with this method
in a standard image-tags src property.</p>
<p>There are two ways to create CSIM (or get hold of) the image maps</p>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Use the CSIM image script as the target in a standard anchor reference,
for example </p>
<p>
</p><pre class="screen">&lt;a href="mycsimscript.html"&gt; </pre><p>
</p>
<p>This has the drawback that the image page will only contain the image and
nothing else.</p>
</li><li class="listitem">
<p>The other way will allow the image script to be included in an arbitrary
HTML page by just including the image script at the wanted place in the HTML
page using any of the standard "include" php statement. For example </p>
<p>
</p><pre class="screen">&lt;h2&gt; This is an CSIM image &lt;/h2&gt;
&lt;?php include "mycsimscript.php" ?&gt;</pre><p>
</p>
</li></ol></div>
<p>Note: If there are several CSIM images on the same page it is necessary to use
"include_once" in the scripts for the inclusion of
"<code class="filename">jpgraph.php</code>" and the other jpgraph library files since the
files will be included multiple times on the same page and one or more "<span class="italic">Already defined error</span>" will be displayed.</p>
<p>The process to replace <code class="code">Stroke()</code> with <code class="code">StrokeCSIM()</code> is
strait forward. Replace all existing calls to <code class="code">Stroke()</code> with the
equivalent calls to <code class="code">StrokeCSIM()</code>.</p>
<div class="sect2" title="Optional argument to StrokeCSIM()"><div class="titlepage"><div><div><h3 class="title"><a name="id2536113"></a>Optional argument to StrokeCSIM()</h3></div></div></div>
<p>Once difference compared with Stroke() is that if a filename is supplied to
the <code class="code">StrokeCSIM()</code> method it does not specify a file to write an
image to as is the case with Stroke(). The signature for the method is</p>
<p>
</p><pre class="screen">StrokeCSIM($aScriptName='auto', $aCSIMName='', $aBorder=0)</pre><p>
</p>
<p>The first (optional) argument is the name of the actual image script file
including the extension. So for example if the image script is called
"<code class="filename">mycsimscript.php</code>" the call should be </p>
<p>
</p><pre class="screen"> $graph -&gt; StrokeCSIM ( 'mycsimscript.php' ) </pre><p>
</p>
<p>By using the predefined name 'auto'. This will be done automatically.</p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>Why does the script name need to be used as the first parameter? The
reason is that in the creation of the HTML page which is sent back we
need to refer to the script in the image tag. In older versions of PHP
there where no 100% way of getting hold of the actual script name in all
circumstances and it was then necessary to specify it here. In PHP5 (and
newer version of PHP4) this is no longer a problem but this parameter is
still kept for backward compatibility.</p>
</div><p>
</p>
<p>The other arguments to <code class="code">StrokeCSIM()</code> are optional as well. The
second argument specifies the id that connect the map with the corresponding
image. Please note that if several CSIM images are used in the same HTML page it
is necessary to specify the image map name as the second parameter since all
image maps must be unique to properly match each image map against each image.
Please consult the class reference <code class="code">StrokeCSIM()</code> for more
details.</p>
<p>The final argument specifies whether the image should have border or
not.</p>
</div>
<div class="sect2" title="How does StrokeCSIM() work?"><div class="titlepage"><div><div><h3 class="title"><a name="id2536192"></a>How does StrokeCSIM() work?</h3></div></div></div>
<p>Knowledge of the exact technical details of the way <code class="code">StrokeCSIM()</code>
works is probably not needed by many people but for completeness we outline
those details in this short section.</p>
<p>The fundamental issue we have to solve is that we must be able to call the
image script in two modes. When the user includes the image script the
<code class="code">StrokeCSIM()</code> method should return the HTML page but when the
image script is later called directly in the image tag it must not return an
HTML page but rather the actual image.</p>
<p>The way this is solved is by using one <code class="code">GET</code> argument which is
passed on automatically when we use the image script name in the
<span class="markup">&lt;img&gt;</span>-tag.</p>
<p>A look at the generated HTML from StrokeCSIM() will make this clear. In <a class="xref" href="ch10s04.html#fig.generated-csim-html-code" title="Figure 10.1. Example of generated HTML code for StrokeCSIM()">Figure 10.1. Example of generated HTML code for StrokeCSIM()</a> the resulting HTML code after
running the example script <code class="filename">bar_csimex1.php</code> is shown. The
argument to the src-property of the image tag is not simply the script name but
the script name with a additional argument, <code class="code">?_jpg_csimd=1</code>. This
argument is passed on to the library which then will run the script again but
this time only generate the image and not the HTML. (In the JpGraph internal
code this pre-defined argument is checked for and if it exists the image is send
back and not the HTML page.)</p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>The actual string name of this parameter is defined by a
<code class="code">DEFINE</code> statement in JpGraph,
<code class="code">_CSIM_DISPLAY</code>.</p>
</div><p>
</p>
<p>
</p><div class="figure"><a name="fig.generated-csim-html-code"></a><p class="title"><b>Figure 10.1. Example of generated HTML code for StrokeCSIM()</b></p><div class="figure-contents">
<pre class="screen">&lt;map name="__mapname1828__" id="__mapname1828__" &gt;
&lt;area shape="poly" coords="74, 210, 74, 165, 92, 165, 92, 210" href="bar_clsmex1.php#1" title="val=12" alt="val=12" /&gt;
&lt;area shape="poly" coords="118, 210, 118, 112, 136, 112, 136, 210" href="bar_clsmex1.php#2" title="val=26" alt="val=26" /&gt;
&lt;area shape="poly" coords="162, 210, 162, 176, 180, 176, 180, 210" href="bar_clsmex1.php#3" title="val=9" alt="val=9" /&gt;
&lt;area shape="poly" coords="206, 210, 206, 146, 224, 146, 224, 210" href="bar_clsmex1.php#4" title="val=17" alt="val=17" /&gt;
&lt;area shape="poly" coords="250, 210, 250, 93, 268, 93, 268, 210" href="bar_clsmex1.php#5" title="val=31" alt="val=31" /&gt;
&lt;/map&gt;
&lt;img src="bar_csimex1.php?_jpg_csimd=1" ismap="ismap" usemap="#__mapname1828__" border="0" width="310" height="250" alt="" /&gt;
</pre>
</div></div><p><br class="figure-break">
</p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>As the astute reader has come to realize CSIM scripts has a
performance impact in that each script has to be run twice. Once to get
hold of all the coordinates and generate the image and a second time via
the &lt;img&gt; tag in generated HTML. The library is intelligent enough to
minimize the code to run so that it only runs what is absolutely
necessary. This means that roughly 75% has to be run which yields a
total overhead of around 1.75 times when generating a CSIM image.</p>
</div><p>
</p>
</div>
<div class="sect2" title="Image maps and the cache system"><div class="titlepage"><div><div><h3 class="title"><a name="id2536305"></a>Image maps and the cache system</h3></div></div></div>
<p>For version 1.9 and later the cache system has been extended to include the
CSIM maps as well. For each CSIM graph two files are stored in the cache, the
image file itself as well as the wrapper HTML with the actual image map. </p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch10.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,34 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Getting hold of the image map</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch10.html" title="Chapter 10. Using CSIM (Client side image maps)"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Getting hold of the image map</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 10. Using CSIM (Client side image maps)</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Getting hold of the image map"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2536328"></a>Getting hold of the image map</h2></div></div></div>
<p>There are at least two cases where the basic StrokeCSIM() method will not work.
Basically this is limited to only showing the graph in one HTML page and nothing
more. So the cases where this needs to be handled differently are</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>In the case where you want to store the image on disk and later use it
in an <span class="markup">img</span>-tag you need to get hold of the image map.
</p>
</li><li class="listitem">
<p>In order to include multiple CSIM images ona a WEB-page. (This is not
entirely true though, it is possible to include several CSIM graph
images with the use of the <span class="markup">&lt;iframe&gt;</span> tag. This in
effect creates it's own WEB page within the WEB page but we will not
discuss this further here.</p>
</li></ol></div><p>
</p>
<p>To get hold of the image map the function <code class="code">Graph::GetHTMLImageMap()</code>
should be used. This returns the coordinates for the hotsposts</p>
<p>An example of the use of this is shown below. With these lines the image will be
written to a file. The script then returns a HTML page which contains the Client
side image map and an img-tag which will retrieve the previously stored file.</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$graph -&gt; Stroke ( &quot;/usr/local/httpd/htdocs/img/image001.png&quot; );
echo $graph -&gt; GetHTMLImageMap ( &quot;myimagemap001&quot; );
echo &quot;&lt;img src=\&quot;img/image001.png\&quot; ISMAP USEMAP=\&quot;#myimagemap001\&quot; border=0&gt;&quot; ;</span></pre></td></tr></table></div><p>
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch10.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,575 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Mixing several CSIM images in an HTML page with text</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch10.html" title="Chapter 10. Using CSIM (Client side image maps)"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Mixing several CSIM images in an HTML page with text</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 10. Using CSIM (Client side image maps)</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Mixing several CSIM images in an HTML page with text"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2536399"></a>Mixing several CSIM images in an HTML page with text</h2></div></div></div>
<p>As was mentioned above using <code class="code">StrokeCSIM()</code> is very simple but it has
the drawback that it returns a single HTML page without any possibilities to add
additional text which makes its use fairly limited in real life situation where the
graph is part of a complex WEB-page. In this section we will discuss some best
practice to do this.</p>
<p>In principle there are two ways to do this</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Store both the image map and the image in files which are later read
back in the HTML page. This has the advantage of being simple but the
drawback that it increases the processing time since writing and reading
from a file takes time.</p>
</li><li class="listitem">
<p>Avoiding the use of temporary file by mimicking the way
<code class="code">StrokeCSIM()</code> works and od the steps
<code class="code">StrokeCSIM()</code> does internally but in the script
directly. In the remainder of this section we will show how this can be
setup. That part will also introduce the method
<code class="code">StrokeCSIMImage()</code> which is key to include CSIM graphs
in HTML pages.</p>
</li></ol></div><p>
</p>
<div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3>
<p>Some of the described methods in this section was added in version 2.5 of the
library. In earlier versions more of this has to be done manually.</p>
</div>
<div class="sect2" title="Adding one CSIM graph in a HTML page"><div class="titlepage"><div><div><h3 class="title"><a name="sec2.adding-csim-in-html"></a>Adding one CSIM graph in a HTML page</h3></div></div></div>
<p>The library has been designed to make this as painless as possible but due to
the way CSIM works there are some manual work that cannot be avoided. We will
start slowly and in detail walk through an example where we include one CSIM
graph in an arbitrary HTML page. There are a few things to keep in mind, the
rest will be taken care of automatically by the library</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>In the HTML page the CSIM map must be semi-manually included. (It
doesn't matter where)</p>
</li><li class="listitem">
<p>The <span class="markup">&lt;img&gt; </span>tag for rendering the image must be
semi-manually created</p>
</li><li class="listitem">
<p>The original graph script needs a minor augmentation since it
should no longer end by calling <code class="code">StrokeCSIM()</code></p>
</li><li class="listitem">
<p>Some care needs to be taken to specify what the URL:s to be called
should be</p>
</li></ol></div><p>
</p>
<p>The library provides suitable functions for step 1 &amp; 2 above so the only
thing that needs to be done in the HTML page is calling these functions at
suitable places. In principle the HTML page should have the structure shown in <a class="xref" href="ch10s06.html#ex.csim-html-ex1" title="Example 10.1. Principles of including CSIM graph in a HTML page">Example 10.1. Principles of including CSIM graph in a HTML page</a></p>
<p>
</p><div class="example"><a name="ex.csim-html-ex1"></a><p class="title"><b>Example 10.1. Principles of including CSIM graph in a HTML page</b></p><div class="example-contents">
<div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">&lt;html&gt;
&lt;body&gt;
</span><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> The name of the graph script file (change as needed!)</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$_graphfilename</span><span class="hl-code"> = </span><span class="hl-quotes">'</span><span class="hl-string">mycsimgraph.php</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> This is the filename of this HTML file</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">global</span><span class="hl-code"> </span><span class="hl-var">$_wrapperfilename</span><span class="hl-code">;
</span><span class="hl-var">$_wrapperfilename</span><span class="hl-code"> = </span><span class="hl-identifier">basename</span><span class="hl-code"> </span><span class="hl-brackets">(</span><span class="hl-reserved">__FILE__</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Create a random mapname used to connect the image map with the image</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$_mapname</span><span class="hl-code"> = </span><span class="hl-quotes">'</span><span class="hl-string">__mapname</span><span class="hl-quotes">'</span><span class="hl-code">.</span><span class="hl-identifier">rand</span><span class="hl-brackets">(</span><span class="hl-number">0</span><span class="hl-code">,</span><span class="hl-number">1000000</span><span class="hl-brackets">)</span><span class="hl-code">.</span><span class="hl-quotes">'</span><span class="hl-string">__</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> This is the actual graph script</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">require_once</span><span class="hl-code"> </span><span class="hl-brackets">(</span><span class="hl-var">$_graphfilename</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Get hold of the image map to include it in the HTML page</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$imgmap</span><span class="hl-code"> = </span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">GetHTMLImageMap</span><span class="hl-brackets">(</span><span class="hl-var">$_mapname</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-reserved">echo</span><span class="hl-code"> </span><span class="hl-var">$imgmap</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span><span class="hl-code">
&lt;p&gt;Some arbitrary HTML text .... &lt;/p&gt;
</span><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> We now create the &lt;img&gt; tag</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$imgtag</span><span class="hl-code"> = </span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">GetCSIMImgHTML</span><span class="hl-brackets">(</span><span class="hl-var">$_mapname</span><span class="hl-code">,</span><span class="hl-var">$_graphfilename</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-reserved">echo</span><span class="hl-code"> </span><span class="hl-var">$imgtag</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span><span class="hl-code">
&lt;/body&gt;
&lt;/html&gt;</span></pre></td></tr></table></div>
</div></div><p><br class="example-break">
</p>
<p>Before we discuss the HTML code in detail lets first show what augmentation is
needed in the graph script.</p>
<p>Normally the graph script will end with a call to either
<code class="code">Graph::Stroke()</code> or <code class="code">Graph::StrokeCSIM()</code>. However,
with CSIM style graph the complication is that we need to call the script twice.
Once to get the image map and once (in the final &lt;img&gt; tag) to actually
generate the image. In order to separate these two cases we make use of a URL
argument which will be used as a flag so that we know how to behave in the graph
script. In conjunction with HTML skeleton shown in <a class="xref" href="ch10s06.html#ex.csim-html-ex1" title="Example 10.1. Principles of including CSIM graph in a HTML page">Example 10.1. Principles of including CSIM graph in a HTML page</a> we need to change the graph script so that
it instead uses the method <code class="code">Graph::StrokeCSIMImage()</code> so that the
last line will be changed to</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">...
$graph-&gt;StrokeCSIMImage();
?&gt;</span></pre></td></tr></table></div><p>
</p>
<p>This method will only stroke the image when the "secret" flag is passed as a
URL argument (which will be added automatically when the &lt;img&gt; tag is
constructed in the call to <code class="code">GetCSIMImgHTML()</code> . This means that the
first time this function gets called when we do the initial
<code class="code">require_once()</code> in the top of the HTML page this method will do
nothing, which is exactly what we want since we only want to include the graph
script in order to be able to do the call to <code class="code">GetHTMLImageMap()</code>
later down in the script.</p>
<p>We are now in position to discuss the HTML script above.</p>
<p>
</p><div class="variablelist"><dl><dt><span class="term">Line 1-2</span></dt><dd>
<p>This is the standard HTML opening tags (by choice we keep this
very simple and sloppy in these example.)</p>
</dd><dt><span class="term">Line 3-20</span></dt><dd>
<p>This is where we include the graph script. In addition we must
also create a map name that will be used to connect an image map
with the <span class="markup">&lt;img&gt;</span> tag. We have chosen to create
a random name since the actual name is not significant. The only
criteria is that the name must be unique if there are multiple
maps in the same HTML page.</p>
<p>In addition we also record the name of the actual HTML page in
the variable "<code class="code">$wrapperfilename</code>". This is so we can
potentially use it as a target in the image script. We could
then have targets that redisplays the same page but with
potential additional or changed URL argument.</p>
</dd><dt><span class="term">Line 21-22</span></dt><dd>
<p>This is just an illustration that it is possible to add
arbitrary HTML markups and text on the page.</p>
</dd><dt><span class="term">Line 23-27</span></dt><dd>
<p>This is where we generate the needed &lt;img&gt; tag that should
be included in the page. It is illustrative to view how the
&lt;img&gt; tag actually looks.</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">&lt;img src=&quot;mycsimgraph.php?_jpg_csimd=1&quot; ismap=&quot;ismap&quot;
usemap=&quot;#__mapname987066__&quot; border=&quot;0&quot; width=&quot;400&quot; height=&quot;250&quot; alt=&quot;&quot; /&gt;</span></pre></td></tr></table></div><p>
</p>
<p>The name of the image is the specified graph name (which was
given as the second argument). As can bee seen a URL argument
"<code class="code">flag _jpg_csimd=2</code>" has been added. This is the
"secret" flag that instructs <code class="code">StrokeCSIMImage()</code> to
actually send back the image. The second thing to notice is the
map name. This is the random name we constructed that is used to
connect to the map we wanted to use with this image.</p>
</dd><dt><span class="term">Line 28-30</span></dt><dd>
<p>The closing HTML tags</p>
</dd></dl></div><p>
</p>
<p>What remains is to discuss how the actual CSIM targets in the graph script
should be constructed. Again there are some choices to be made on what should
happen when a user clicks on the gaph.</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Clicking on a graph should open a "popup" window</p>
</li><li class="listitem">
<p>Clicking on a graph should open the same HTML page but with some
additional URL arguments</p>
</li><li class="listitem">
<p>Clicking on a graph should open a fresh page in the browser</p>
</li><li class="listitem">
<p>Clicking on the graph should open in an existing browser
window</p>
</li></ol></div><p>
</p>
<p>Earlier in this chapter we have shown how to handle case 1 so in the following
we will concentrate on cases 2-4. Before we start we need to discuss the third,
not yet mentioned, argument to the method <code class="code">SetCSIMTargets()</code>. To
remind ourself this method is used on the various objects in a graph that can
act as hotspots. The full signature for this method is</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">SetCSIMTargets($aURLTargets,$aAltTexts,$aWinTargets);</span></pre></td></tr></table></div><p>
</p>
<p>The first argument specifies the URLs. Depending on the actual object this is
either a string or an array of strings.</p>
<p>The second argument specified the HTML "alt" texts. In most browser this is
shown as a popup text if the mouse pointer hovers over a hotspot area.</p>
<p>The final argument specifies the URL target window (where the link should
open). Most browser recognizes a few special targets here</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p>"_blank" . This will open the URL in a new browser window</p>
</li><li class="listitem">
<p>"_top". Will break out of a frameset and display the target window
at top </p>
</li><li class="listitem">
<p>"" (empty). Will open the target in the current window</p>
</li><li class="listitem">
<p>"namedWindow". Will open the target in the named window</p>
</li></ul></div>
<p>In the discussions below we will assume that the graph is a basic barplot so
the URLs we specify are connected to each individual bar in the plot and are
specified with a call similar to</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$bplot-&gt;SetCSIMTargets($targets,$altnames,$wintargets)</span></pre></td></tr></table></div><p>
</p>
<p></p>
<p><span class="bold"><strong>Case 2: Opening the same page but with some different URL
arguments.</strong></span></p>
<p>To do this we make use of the name of the HTML wrapper file we stored in
<code class="code">$_wrapperfilename</code> . We can then construct the targets as shown
in <a class="xref" href="ch10s06.html#ex.csim-targ-same-window" title="Example 10.2. Creating CSIM URL targets to open in same browser window">Example 10.2. Creating CSIM URL targets to open in same browser window</a></p>
<p>
</p><div class="example"><a name="ex.csim-targ-same-window"></a><p class="title"><b>Example 10.2. Creating CSIM URL targets to open in same browser window</b></p><div class="example-contents">
<div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
...
</span><span class="hl-reserved">global</span><span class="hl-code"> </span><span class="hl-var">$_wrapperfilename</span><span class="hl-code">;
</span><span class="hl-var">$n</span><span class="hl-code"> = .. ; </span><span class="hl-comment">//</span><span class="hl-comment"> Number of bars</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$targ</span><span class="hl-code"> = </span><span class="hl-reserved">array</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">, </span><span class="hl-var">$alt</span><span class="hl-code"> = </span><span class="hl-reserved">array</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">; </span><span class="hl-var">$wtarg</span><span class="hl-code"> = </span><span class="hl-reserved">array</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-reserved">for</span><span class="hl-brackets">(</span><span class="hl-code"> </span><span class="hl-var">$i</span><span class="hl-code">=</span><span class="hl-number">0</span><span class="hl-code">; </span><span class="hl-var">$i</span><span class="hl-code"> &lt; </span><span class="hl-var">$n</span><span class="hl-code">; ++</span><span class="hl-var">$i</span><span class="hl-code"> </span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-var">$urlarg</span><span class="hl-code"> = </span><span class="hl-identifier">urlencode</span><span class="hl-brackets">(</span><span class="hl-code"> ... </span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$targ</span><span class="hl-brackets">[</span><span class="hl-brackets">]</span><span class="hl-code"> = </span><span class="hl-var">$_wrapperfilename</span><span class="hl-code">.</span><span class="hl-quotes">'</span><span class="hl-string">?</span><span class="hl-quotes">'</span><span class="hl-code">.</span><span class="hl-var">$urlarg</span><span class="hl-code">;
</span><span class="hl-var">$alt</span><span class="hl-brackets">[</span><span class="hl-brackets">]</span><span class="hl-code"> = </span><span class="hl-quotes">'</span><span class="hl-string">val=%d</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-var">$wtarg</span><span class="hl-brackets">[</span><span class="hl-brackets">]</span><span class="hl-code"> = </span><span class="hl-quotes">'</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-brackets">}</span><span class="hl-code">
</span><span class="hl-var">$bplot</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetCSIMTargets</span><span class="hl-brackets">(</span><span class="hl-var">$targ</span><span class="hl-code">,</span><span class="hl-var">$alt</span><span class="hl-code">,</span><span class="hl-var">$wtarg</span><span class="hl-brackets">)</span><span class="hl-code">;
...
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div>
</div></div><p><br class="example-break">
</p>
<p>
</p><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3>
<p>Remember to not include the "&amp;" or the "=" used when constructing
the URL argument in the call to <code class="code">urlencode()</code>. Otherwise they
will become part of the data and not separators in the URL argument
string.</p>
</div><p>
</p>
<p><span class="bold"><strong>Case 3: Open a fresh page in the browser</strong></span></p>
<p>The following example opens the plain browser script in a fresh window. In
order to get hold of the script name we use the predefined PHP constant
<code class="code">__FILE__</code> . The target can of course be changed to any
URL.</p>
<p>
</p><div class="example"><a name="ex.csim-targ-fresh-window"></a><p class="title"><b>Example 10.3. Creating CSIM URL targets to open in a fresh window</b></p><div class="example-contents">
<div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
...
</span><span class="hl-var">$n</span><span class="hl-code"> = .. ; </span><span class="hl-comment">//</span><span class="hl-comment"> Number of bars</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$targ</span><span class="hl-code"> = </span><span class="hl-reserved">array</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">, </span><span class="hl-var">$alt</span><span class="hl-code"> = </span><span class="hl-reserved">array</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">; </span><span class="hl-var">$wtarg</span><span class="hl-code"> = </span><span class="hl-reserved">array</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-reserved">for</span><span class="hl-brackets">(</span><span class="hl-code"> </span><span class="hl-var">$i</span><span class="hl-code">=</span><span class="hl-number">0</span><span class="hl-code">; </span><span class="hl-var">$i</span><span class="hl-code"> &lt; </span><span class="hl-var">$n</span><span class="hl-code">; ++</span><span class="hl-var">$i</span><span class="hl-code"> </span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-var">$urlarg</span><span class="hl-code"> = </span><span class="hl-identifier">urlencode</span><span class="hl-brackets">(</span><span class="hl-code"> ... </span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$targ</span><span class="hl-brackets">[</span><span class="hl-brackets">]</span><span class="hl-code"> = </span><span class="hl-reserved">__FILE__</span><span class="hl-code">.</span><span class="hl-quotes">'</span><span class="hl-string">?</span><span class="hl-quotes">'</span><span class="hl-code">.</span><span class="hl-var">$urlarg</span><span class="hl-code">;
</span><span class="hl-var">$alt</span><span class="hl-brackets">[</span><span class="hl-brackets">]</span><span class="hl-code"> = </span><span class="hl-quotes">'</span><span class="hl-string">val=%d</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-var">$wtarg</span><span class="hl-brackets">[</span><span class="hl-brackets">]</span><span class="hl-code"> = </span><span class="hl-quotes">'</span><span class="hl-string">_blank</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-brackets">}</span><span class="hl-code">
</span><span class="hl-var">$bplot</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetCSIMTargets</span><span class="hl-brackets">(</span><span class="hl-var">$targ</span><span class="hl-code">,</span><span class="hl-var">$alt</span><span class="hl-code">,</span><span class="hl-var">$wtarg</span><span class="hl-brackets">)</span><span class="hl-code">;
...
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div>
</div></div><p><br class="example-break">
</p>
<p><span class="bold"><strong>Case 4: Open in an existing window/frame</strong></span></p>
<p>By modifying the <code class="code">$wtarg[]</code> line in the example above to </p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-var">$wtarg</span><span class="hl-brackets">[</span><span class="hl-brackets">]</span><span class="hl-code"> = </span><span class="hl-quotes">'</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div><p>
</p>
<p>The target will open in the existing window.</p>
<p>In the "<code class="filename">Example/</code>" directory you can find the above a
fully working script as "<code class="filename">csim_in_html_ex1.php</code>" (HTML
script) and "<code class="filename">csim_in_html_graph_ex1.php</code>" (Graph
script).</p>
</div>
<div class="sect2" title="Adding multiple CSIM graphs in a HTML page"><div class="titlepage"><div><div><h3 class="title"><a name="id2536476"></a>Adding multiple CSIM graphs in a HTML page</h3></div></div></div>
<p>Having laid the foundation for inclusion of CSIM graphs in <a class="xref" href="ch10s06.html#sec2.adding-csim-in-html" title="Adding one CSIM graph in a HTML page">Adding one CSIM graph in a HTML page</a> it is now a simple exercise to
extend this to include multiple CSIM graphs in the same HTML page. The only
modifications we have to do is to make sure that:</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Each image map has a unique name</p>
</li><li class="listitem">
<p>The graph scripts must create unique instances of the main Graph
class, i.e. they cannot both have an instance called
"<code class="code">$graph</code>"</p>
</li><li class="listitem">
<p>Include each graph script in turn and get the corresponding HTML
map</p>
</li><li class="listitem">
<p>Get the proper image tag for each graph</p>
</li></ol></div><p>
</p>
<p>In <a class="xref" href="ch10s06.html#ex.csim-html-two-graphs" title='Example 10.4. Example of HTML page that includes two Graph CSIM scripts ("Examples/csim_in_html_ex2.html")'>Example 10.4. Example of HTML page that includes two Graph CSIM scripts
("<code class="filename">Examples/csim_in_html_ex2.html</code>")</a> we show a complete HTML script that
includes two graphs, one bar (the same as in the previous example) and one Pie
graph. For illustrative purposes we use class <code class="code">PieGraphC</code> variant
which is a Pie graph with a circular middle. The result of calling this HTML
page is shown in ??</p>
<p>
</p><div class="example"><a name="ex.csim-html-two-graphs"></a><p class="title"><b>Example 10.4. Example of HTML page that includes two Graph CSIM scripts
("<code class="filename">Examples/csim_in_html_ex2.html</code>")</b></p><div class="example-contents">
<div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">&lt;html&gt;
&lt;body&gt;
</span><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> The names of the graph scripts</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$_graphfilename1</span><span class="hl-code"> = </span><span class="hl-quotes">'</span><span class="hl-string">csim_in_html_graph_ex1.php</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-var">$_graphfilename2</span><span class="hl-code"> = </span><span class="hl-quotes">'</span><span class="hl-string">csim_in_html_graph_ex2.php</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> This is the filename of this HTML file</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">global</span><span class="hl-code"> </span><span class="hl-var">$_wrapperfilename</span><span class="hl-code">;
</span><span class="hl-var">$_wrapperfilename</span><span class="hl-code"> = </span><span class="hl-identifier">basename</span><span class="hl-code"> </span><span class="hl-brackets">(</span><span class="hl-reserved">__FILE__</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Create a random mapname used to connect the image map with the image</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$_mapname1</span><span class="hl-code"> = </span><span class="hl-quotes">'</span><span class="hl-string">__mapname</span><span class="hl-quotes">'</span><span class="hl-code">.</span><span class="hl-identifier">rand</span><span class="hl-brackets">(</span><span class="hl-number">0</span><span class="hl-code">,</span><span class="hl-number">1000000</span><span class="hl-brackets">)</span><span class="hl-code">.</span><span class="hl-quotes">'</span><span class="hl-string">__</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-var">$_mapname2</span><span class="hl-code"> = </span><span class="hl-quotes">'</span><span class="hl-string">__mapname</span><span class="hl-quotes">'</span><span class="hl-code">.</span><span class="hl-identifier">rand</span><span class="hl-brackets">(</span><span class="hl-number">0</span><span class="hl-code">,</span><span class="hl-number">1000000</span><span class="hl-brackets">)</span><span class="hl-code">.</span><span class="hl-quotes">'</span><span class="hl-string">__</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Get the graph scripts</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">require_once</span><span class="hl-code"> </span><span class="hl-brackets">(</span><span class="hl-var">$_graphfilename1</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-reserved">require_once</span><span class="hl-code"> </span><span class="hl-brackets">(</span><span class="hl-var">$_graphfilename2</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> This line gets the image map and inserts it on the page</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$imgmap1</span><span class="hl-code"> = </span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">GetHTMLImageMap</span><span class="hl-brackets">(</span><span class="hl-var">$_mapname1</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$imgmap2</span><span class="hl-code"> = </span><span class="hl-var">$piegraph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">GetHTMLImageMap</span><span class="hl-brackets">(</span><span class="hl-var">$_mapname2</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-reserved">echo</span><span class="hl-code"> </span><span class="hl-var">$imgmap1</span><span class="hl-code">;
</span><span class="hl-reserved">echo</span><span class="hl-code"> </span><span class="hl-var">$imgmap2</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span><span class="hl-code">
&lt;h2&gt;This is an example page with CSIM graphs with arbitrary HTML text&lt;/h2&gt;
</span><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-reserved">if</span><span class="hl-brackets">(</span><span class="hl-code"> </span><span class="hl-reserved">empty</span><span class="hl-brackets">(</span><span class="hl-var">$_GET</span><span class="hl-brackets">[</span><span class="hl-quotes">'</span><span class="hl-string">clickedon</span><span class="hl-quotes">'</span><span class="hl-brackets">]</span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-reserved">echo</span><span class="hl-code"> </span><span class="hl-quotes">'</span><span class="hl-string">&lt;b style=&quot;color:darkred;&quot;&gt;Clicked on bar: &amp;lt;none&gt;&lt;/b&gt;</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-brackets">}</span><span class="hl-code">
</span><span class="hl-reserved">else</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-reserved">echo</span><span class="hl-code"> </span><span class="hl-quotes">'</span><span class="hl-string">&lt;b style=&quot;color:darkred;&quot;&gt;Clicked on bar: </span><span class="hl-quotes">'</span><span class="hl-code">.</span><span class="hl-var">$_GET</span><span class="hl-brackets">[</span><span class="hl-quotes">'</span><span class="hl-string">clickedon</span><span class="hl-quotes">'</span><span class="hl-brackets">]</span><span class="hl-code">.</span><span class="hl-quotes">'</span><span class="hl-string">&lt;/b&gt;</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-brackets">}</span><span class="hl-code">
</span><span class="hl-reserved">echo</span><span class="hl-code"> </span><span class="hl-quotes">'</span><span class="hl-string">&lt;p /&gt;</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-reserved">if</span><span class="hl-brackets">(</span><span class="hl-code"> </span><span class="hl-reserved">empty</span><span class="hl-brackets">(</span><span class="hl-var">$_GET</span><span class="hl-brackets">[</span><span class="hl-quotes">'</span><span class="hl-string">pie_clickedon</span><span class="hl-quotes">'</span><span class="hl-brackets">]</span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-reserved">echo</span><span class="hl-code"> </span><span class="hl-quotes">'</span><span class="hl-string">&lt;b style=&quot;color:darkred;&quot;&gt;Clicked on pie slice: &amp;lt;none&gt;&lt;/b&gt;</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-brackets">}</span><span class="hl-code">
</span><span class="hl-reserved">else</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-reserved">echo</span><span class="hl-code"> </span><span class="hl-quotes">'</span><span class="hl-string">&lt;b style=&quot;color:darkred;&quot;&gt;Clicked on pie slice: </span><span class="hl-quotes">'</span><span class="hl-code">.</span><span class="hl-var">$_GET</span><span class="hl-brackets">[</span><span class="hl-quotes">'</span><span class="hl-string">pie_clickedon</span><span class="hl-quotes">'</span><span class="hl-brackets">]</span><span class="hl-code">.</span><span class="hl-quotes">'</span><span class="hl-string">&lt;/b&gt;</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-brackets">}</span><span class="hl-code">
</span><span class="hl-reserved">echo</span><span class="hl-code"> </span><span class="hl-quotes">'</span><span class="hl-string">&lt;p /&gt;</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span><span class="hl-code">
&lt;p&gt;First we need to get hold of the image maps and include them in the HTML
page.&lt;/p&gt;
&lt;p&gt;For these graphs the maps are:&lt;/p&gt;
</span><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> The we display the image map as well</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">echo</span><span class="hl-code"> </span><span class="hl-quotes">'</span><span class="hl-string">&lt;small&gt;&lt;pre&gt;</span><span class="hl-quotes">'</span><span class="hl-code">.</span><span class="hl-identifier">htmlentities</span><span class="hl-brackets">(</span><span class="hl-var">$imgmap1</span><span class="hl-brackets">)</span><span class="hl-code">.</span><span class="hl-quotes">'</span><span class="hl-string">&lt;/pre&gt;&lt;/small&gt;</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span><span class="hl-code">
&lt;p&gt;
and
&lt;/p&gt;
</span><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> The we display the image map as well</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">echo</span><span class="hl-code"> </span><span class="hl-quotes">'</span><span class="hl-string">&lt;small&gt;&lt;pre&gt;</span><span class="hl-quotes">'</span><span class="hl-code">.</span><span class="hl-identifier">htmlentities</span><span class="hl-brackets">(</span><span class="hl-var">$imgmap2</span><span class="hl-brackets">)</span><span class="hl-code">.</span><span class="hl-quotes">'</span><span class="hl-string">&lt;/pre&gt;&lt;/small&gt;</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span><span class="hl-code">
</span><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Construct the &lt;img&gt; tags for Figure 1 &amp;amp; 2 and rebuild the URL arguments</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$imgtag1</span><span class="hl-code"> = </span><span class="hl-var">$graph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">GetCSIMImgHTML</span><span class="hl-brackets">(</span><span class="hl-var">$_mapname1</span><span class="hl-code">,</span><span class="hl-var">$_graphfilename1</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$imgtag2</span><span class="hl-code"> = </span><span class="hl-var">$piegraph</span><span class="hl-code">-&gt;</span><span class="hl-identifier">GetCSIMImgHTML</span><span class="hl-brackets">(</span><span class="hl-var">$_mapname2</span><span class="hl-code">,</span><span class="hl-var">$_graphfilename2</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span><span class="hl-code">
&lt;p&gt;The graphs are then displayed as shown in figure 1 &amp;amp; 2. With the following
created &amp;lt;img&gt; tags:&lt;/p&gt;
&lt;small&gt;&lt;pre&gt;
</span><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-reserved">echo</span><span class="hl-code"> </span><span class="hl-identifier">htmlentities</span><span class="hl-brackets">(</span><span class="hl-var">$imgtag1</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-reserved">echo</span><span class="hl-code"> </span><span class="hl-identifier">htmlentities</span><span class="hl-brackets">(</span><span class="hl-var">$imgtag2</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span><span class="hl-code">
&lt;/pre&gt;&lt;/small&gt;
&lt;p&gt;
Note: For the Pie the center is counted as the first slice.
&lt;/p&gt;
&lt;p&gt;
&lt;table border=0&gt;
&lt;tr&gt;&lt;td valign=&quot;bottom&quot;&gt;
</span><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-reserved">echo</span><span class="hl-code"> </span><span class="hl-var">$imgtag1</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span><span class="hl-code">
&lt;br&gt;&lt;b&gt;Figure 1. &lt;/b&gt;The included Bar CSIM graph.
&lt;/p&gt;
&lt;/td&gt;
&lt;td valign=&quot;bottom&quot;&gt;
</span><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-reserved">echo</span><span class="hl-code"> </span><span class="hl-var">$imgtag2</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span><span class="hl-code">
&lt;br&gt;&lt;b&gt;Figure 2. &lt;/b&gt;The included Pie CSIM graph.
&lt;/p&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/table&gt;
&lt;/body&gt;
&lt;/html&gt;</span></pre></td></tr></table></div>
</div></div><p><br class="example-break">
</p>
<p>
</p><div class="figure"><a name="id2537145"></a><p class="title"><b>Figure 10.2. Browser window after calling HTML page in <a class="xref" href="ch10s06.html#ex.csim-html-two-graphs" title='Example 10.4. Example of HTML page that includes two Graph CSIM scripts ("Examples/csim_in_html_ex2.html")'>Example 10.4. Example of HTML page that includes two Graph CSIM scripts
("<code class="filename">Examples/csim_in_html_ex2.html</code>")</a> (Note: The image has been
scaled down to better fit this manual.)</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/csim-html-example-page.png" alt="Browser window after calling HTML page in (Note: The image has been scaled down to better fit this manual.)"></div>
</div></div><p><br class="figure-break">
</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch10.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,26 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 11. NuSphere PHP accelerator</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt02.html" title="Part II. Basic graph creation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 11. NuSphere PHP accelerator</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part II. Basic graph creation</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="chapter" title="Chapter 11. NuSphere PHP accelerator"><div class="titlepage"><div><div><h2 class="title"><a name="chap.php-accelerator"></a>Chapter 11. NuSphere PHP accelerator</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ch11.html#id2537194">11.1. Introduction and purpose</a></span></dt><dt><span class="sect1"><a href="ch11s02.html">11.2. Installing PhpExpress</a></span></dt></dl></div>
<p>
</p><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3>
<p>The NuSphere encoded variant of the library is only included in the JpGraph
pro version.</p>
</div><p>
</p>
<div class="sect1" title="Introduction and purpose"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2537194"></a>Introduction and purpose</h2></div></div></div>
<p>One of the best way to increase the performance of large and complex PHP scripts
is to install one of the available PHP accelerators. JpGraph supports <span class="italic">NuSphere PhpExpress</span> accelerator. In order to take
advantage of this accelerator you must install the version of the library that is
encoded for use with the accelerator. This version is included in the Pro-version of
the library under the directory <code class="filename">src-encoded/</code>.</p>
<p>If you have the Pro-version of the library there is really no good reason not to
use the accelerated version of the library. It will reduce the load on your server
as well as significantly decrease the run time for graph scripts. In addition it
will also reduce some of the memory requirements needed since the parsing process
(translating PHP to bytecode) for the library can be avoided. Furthermore <span class="italic">NuSphere PhPExpress</span> also implements a caching mechanism
which means that often executed scripts will be kept in memory to avoid re-reading
them from disk each time they are needed. This applies to both encoded and
non-encoded script files.</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt02.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,31 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Installing PhpExpress</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch11.html" title="Chapter 11. NuSphere PHP accelerator"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Installing PhpExpress</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 11. NuSphere PHP accelerator</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Installing PhpExpress"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2537228"></a>Installing PhpExpress</h2></div></div></div>
<p>NuSphere PhpExpress is a regular PHP extension, which makes it easy to install and
deploy. You can download PhpExpress freely from </p>
<p><code class="uri"><a class="uri" href="http://www.nusphere.com/products/phpexpress.htm" target="_top">http://www.nusphere.com/products/phpexpress.htm</a></code></p>
<p>To install <span class="italic">NuSphere PhpExpress</span> do the following: </p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Open your <code class="filename">php.ini</code> file for editing</p>
</li><li class="listitem">
<p>Add line
<code class="code">zend_extension_ts=c:\full\path\to\phpexpress-php-x.x.dll</code>
if you are deploying on Windows, or
<code class="code">zend_extension=/full/path/to/phpexpress-php-x.x</code>.so if
you are deploying on Unix, Linux or Mac OS operating systems</p>
</li><li class="listitem">
<p>Copy <code class="filename">phpexpress-php-x.x.dll</code> or
<code class="filename">phpexpress-php-x.x</code>.so in the PHP extensions
directory specified in <code class="filename">php.ini</code> file.</p>
</li><li class="listitem">
<p>Stop and Start Apache if you are running PHP as Apache module.</p>
</li><li class="listitem">
<p>[Optional] Execute call to <code class="code">phpinfo()</code> function and make
sure that PhpExpress is properly installed Once PhpExpress is installed
on the server, you can execute PHP Scripts encoded with Nu-Coder as well
as regular, not encoded PHP scripts. In both cases you will gain an
improved performance in the execution of the scripts.</p>
</li></ol></div><p>
</p>
<p> </p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch11.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,105 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 12. Commonalities for all graphs</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt03.html" title="Part III. Common features"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 12. Commonalities for all graphs</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part III. Common features</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="chapter" title="Chapter 12. Commonalities for all graphs"><div class="titlepage"><div><div><h2 class="title"><a name="id2537365"></a>Chapter 12. Commonalities for all graphs</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ch12.html#id2537384">12.1. Common objects for cartesian graphs (x-, y-graphs)</a></span></dt><dt><span class="sect1"><a href="ch12s02.html">12.2. Common object for Pie Graphs</a></span></dt></dl></div>
<p>All graph scripts follow, to some extent, the same structure. All scripts must start
by creating an instance of the Graph class. The Graph class represent the entire graph
and can have one or more plots build up from the data series. Almost all methods that
are used to control the appearance of the graph are methods of this class.</p>
<p>In order to give a feel for common objects we show examples of two of the most
commonly used graph types, cartesian graphs and pie graphs in the following two
sections.</p>
<div class="sect1" title="Common objects for cartesian graphs (x-, y-graphs)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2537384"></a>Common objects for cartesian graphs (x-, y-graphs)</h2></div></div></div>
<p>In all documentation of the library the convention is that the instance of the
Graph class will be stored in a variable named "<code class="code">$graph</code>". Most of the
parts that make up a graph are available as instance variables of the Graph class.
In order to illustrate some of the commonly used instance variables <a class="xref" href="ch12.html#fig.common-objects" title="Figure 12.1. Commonly used objects in a graph (common-obj-graph.php)">Figure 12.1. Commonly used objects in a graph (<code class="uri"><a class="uri" href="example_src/common-obj-graph.html" target="_top">common-obj-graph.php</a></code>)</a> shows a basic graph with a number of the
objects that can be manipulated in the graph scripts.</p>
<p>
</p><div class="figure"><a name="fig.common-objects"></a><p class="title"><b>Figure 12.1. Commonly used objects in a graph (<code class="uri"><a class="uri" href="example_src/common-obj-graph.html" target="_top">common-obj-graph.php</a></code>)</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/graph-obj-overview.png" alt="Commonly used objects in a graph (common-obj-graph.php)"></div>
</div></div><p><br class="figure-break">
</p>
<p>We note a few things in <a class="xref" href="ch12.html#fig.common-objects" title="Figure 12.1. Commonly used objects in a graph (common-obj-graph.php)">Figure 12.1. Commonly used objects in a graph (<code class="uri"><a class="uri" href="example_src/common-obj-graph.html" target="_top">common-obj-graph.php</a></code>)</a>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p>All graphs will start by including the necessary library files via one
or more "require_once" PHP statements</p>
</li><li class="listitem">
<p>All graph scripts (for 2D linear type graphs) will have the following
two method calls</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$graph = new Graph($width, $height);
$graph-&gt;SetScale('...');</span></pre></td></tr></table></div><p>
</p>
<p>These two calls create the necessary instance of the core Graph class
that represents the entire graph and specifies what scale should be used
for the y- and x-axis. In <a class="xref" href="ch12.html#fig.common-objects" title="Figure 12.1. Commonly used objects in a graph (common-obj-graph.php)">Figure 12.1. Commonly used objects in a graph (<code class="uri"><a class="uri" href="example_src/common-obj-graph.html" target="_top">common-obj-graph.php</a></code>)</a> we
are also using a second -axis so in this case the script will also
contain a call to</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$graph-&gt;SetY2Scale('...');</span></pre></td></tr></table></div><p>
</p>
</li><li class="listitem">
<p>Most graphs will also adjust the left, right, top and bottom margin.
In <a class="xref" href="ch12.html#fig.common-objects" title="Figure 12.1. Commonly used objects in a graph (common-obj-graph.php)">Figure 12.1. Commonly used objects in a graph (<code class="uri"><a class="uri" href="example_src/common-obj-graph.html" target="_top">common-obj-graph.php</a></code>)</a> the margins are shown with
red arrows. The margins are specified with the method</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$graph-&gt;SetMargin($left,$right,$top,$bottom);</span></pre></td></tr></table></div><p>
</p>
</li><li class="listitem">
<p>All text objects (e.g. graph and axis titles) are instances of the
common Text class. This means that the text, font, color are specified
in the same way. For example the code to set the title and subtitle in
the graph above is</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$graph-&gt;title-&gt;SetFont(FF_ARIAL, FS_BOLD, 14);
$graph-&gt;title-&gt;Set(&quot;Using JpGraph Library&quot;);
$graph-&gt;title-&gt;SetMargin(10);
$graph-&gt;subtitle-&gt;SetFont(FF_ARIAL, FS_BOLD, 10);
$graph-&gt;subtitle-&gt;Set('(common objects)');</span></pre></td></tr></table></div><p>
</p>
<p>In a similar way the code to set the titles of the axis are</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$graph-&gt;xaxis-&gt;title-&gt;SetFont(FF_ARIAL, FS_BOLD, 10);
$graph-&gt;xaxis-&gt;title-&gt;Set(&quot;X-title&quot;);
$graph-&gt;yaxis-&gt;title-&gt;SetFont(FF_ARIAL, FS_BOLD, 10);
$graph-&gt;yaxis-&gt;title-&gt;Set(&quot;Y-title&quot;);</span></pre></td></tr></table></div><p>
</p>
</li><li class="listitem">
<p>The graph uses a legend in two rows to name each data series. The
position of the legend is controlled by the script and in <a class="xref" href="ch12.html#fig.common-objects" title="Figure 12.1. Commonly used objects in a graph (common-obj-graph.php)">Figure 12.1. Commonly used objects in a graph (<code class="uri"><a class="uri" href="example_src/common-obj-graph.html" target="_top">common-obj-graph.php</a></code>)</a> we placed it on the right side.
It is also possible to in detail to adjust the layout of the names in
the data series. For example we could change the layout of the legend to
position all the names of the data series in one row as opposed to one
column which is the default. The number of columns and/or rows is user
settable.</p>
</li><li class="listitem">
<p>Finally all graphs will end with a call to <code class="code">Stroke()</code> or
one of its variants (<code class="code">StrokeCSIM()</code>,
<code class="code">StrokeCSIMIMage()</code>). As was described in Part II this
will send back the constructed image to the client, usually a
browser.</p>
</li></ul></div>
<p>For other types of graphs (for example Gantt charts) some of the above standards
still apply but since they have a very different usage and layout the instance
variables will be different.</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt03.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,60 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Common object for Pie Graphs</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch12.html" title="Chapter 12. Commonalities for all graphs"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Common object for Pie Graphs</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 12. Commonalities for all graphs</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Common object for Pie Graphs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2537606"></a>Common object for Pie Graphs</h2></div></div></div>
<p>For pie plots there are no concepts of axis or scales. Instead Pieplots have a
size and position within the graph. <a class="xref" href="ch12s02.html#fig.common-pie-objects" title="Figure 12.2. Commonly used objects in Piegraphs ( common-obj-piegraph.php)">Figure 12.2. Commonly used objects in Piegraphs (<code class="uri"><a class="uri" href="example_src/common-obj-piegraph.html" target="_top">
common-obj-piegraph.php</a></code>)</a>
shows the common objects for a typical Pie graph</p>
<p>
</p><div class="figure"><a name="fig.common-pie-objects"></a><p class="title"><b>Figure 12.2. Commonly used objects in Piegraphs (<code class="uri"><a class="uri" href="example_src/common-obj-piegraph.html" target="_top">
common-obj-piegraph.php</a></code>)</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/piegraph-obj-overview.png" alt="Commonly used objects in Piegraphs ( common-obj-piegraph.php)"></div>
</div></div><p><br class="figure-break">
</p>
<p>The following should be noted.</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p>Instead of an instance of <code class="code">class Graph</code> and instance of
<code class="code">class PieGraph</code> must be used</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$graph = new PieGraph($width,$height);</span></pre></td></tr></table></div><p>
</p>
</li><li class="listitem">
<p>The title and subtitle has the same semantics as for cartesian
graphs</p>
</li><li class="listitem">
<p>The pieplot is an instance of the <code class="code">class PiePlot</code> which is
given the data to be used in the pieplot as first and only
argument</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$pieplot = new PiePlot($data);</span></pre></td></tr></table></div><p>
</p>
</li><li class="listitem">
<p>The size of the pieplot radius is given as fractions of the minimum of
the width and height of the graph</p>
</li><li class="listitem">
<p>The position of the center of the pieplot is given as factions (width,
height) of the graph</p>
</li><li class="listitem">
<p>The legend is controlled in the same way as for cartesian graphs by
accessing the instance variable "<code class="code">legend</code>". In the Piegraph
in <a class="xref" href="ch12s02.html#fig.common-pie-objects" title="Figure 12.2. Commonly used objects in Piegraphs ( common-obj-piegraph.php)">Figure 12.2. Commonly used objects in Piegraphs (<code class="uri"><a class="uri" href="example_src/common-obj-piegraph.html" target="_top">
common-obj-piegraph.php</a></code>)</a> we have changed the
layout of the legend by the two lines</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$graph-&gt;legend-&gt;SetPos(0.5,0.97,'center','bottom');
$graph-&gt;legend-&gt;SetColumns(3);</span></pre></td></tr></table></div><p>
</p>
<p>These two method calls adjust the position and the internal layout of
the legend. The first line instructs the library to place the legend at
a point (defined in fractions of width and height) (0.5, 0.97) and align
that point with the (center, bottom) anchor point in the graph box. The
second lines specifies the number of columns to use int the
legend.</p>
</li></ul></div><p>
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch12.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,50 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 13. Getting hold of the data to be displayed</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt03.html" title="Part III. Common features"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 13. Getting hold of the data to be displayed</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part III. Common features</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="chapter" title="Chapter 13. Getting hold of the data to be displayed"><div class="titlepage"><div><div><h2 class="title"><a name="id2537773"></a>Chapter 13. Getting hold of the data to be displayed</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ch13.html#id2537845">13.1. Static data</a></span></dt><dt><span class="sect1"><a href="ch13s02.html">13.2. Reading data from a file</a></span></dt><dt><span class="sect1"><a href="ch13s03.html">13.3. Sending data to a graph script with URI arguments (GET and POST)</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch13s03.html#id2538350">13.3.1. Using GET arguments</a></span></dt><dt><span class="sect2"><a href="ch13s03.html#id2538499">13.3.2. Using a POST request</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch13s04.html">13.4. Reading data from a database</a></span></dt><dt><span class="sect1"><a href="ch13s05.html">13.5. Reading binary data from a file</a></span></dt><dt><span class="sect1"><a href="ch13s06.html">13.6. Different types of NULL data handling</a></span></dt><dt><span class="sect1"><a href="ch13s07.html">13.7. Troubleshooting input data</a></span></dt></dl></div>
<p>The initial obstacle that must be negotiated is to get hold of the data to be
displayed since the library itself is completely agnostic to where the data comes from.
The library will use data supplied in one or more arrays and it is up to the user of the
library to get hold of the data to populate these arrays with proper data. In principle
the data can come from one of the following places</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Hard-coded data in the script. This is the least flexible and can only
really be recommended for examples and really static data.</p>
</li><li class="listitem">
<p>Data stored in plain text files.</p>
</li><li class="listitem">
<p>Data stored in binary format in flat files. </p>
</li><li class="listitem">
<p>Data stored in a database</p>
</li><li class="listitem">
<p>Data sent to the script via URI parameter passing (either GET or POST HTTP
constructs can be used).</p>
</li></ol></div><p>
</p>
<p>In the following sections we will shortly discuss each of these methods.</p>
<p>
</p><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3>
<p>The library assumes that the data available in an array that starts with index
0</p>
</div><p>
</p>
<div class="sect1" title="Static data"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2537845"></a>Static data</h2></div></div></div>
<p>This is the simplest way and consists of only specifying the data in one or
several usual PHP arrays directly in the graph script. For example to specify data
for a Pieplot one could use the following constructions</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$data = array(1,8,5,4,12,18);
$pieplot = new PiePlot ($data);</span></pre></td></tr></table></div><p>
</p>
<p>This is the method used for all examples under the "<code class="filename">Example/</code>"
directory.</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt03.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,164 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Reading data from a file</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch13.html" title="Chapter 13. Getting hold of the data to be displayed"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Reading data from a file</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 13. Getting hold of the data to be displayed</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Reading data from a file"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2537882"></a>Reading data from a file</h2></div></div></div>
<p>The second method in order of complexity is to read the data from plain text
files. An example on how to use this was shown in <a class="xref" href="ch04s02.html#sec.preparing-sunspots-data" title="Preparing the data">Preparing the data</a>. The library contains utility
methods to ease reading of plain textual data in one of the following
formats:</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>One column</p>
</li><li class="listitem">
<p>Two columns</p>
</li><li class="listitem">
<p>Comma separated values, CSV</p>
</li></ol></div><p>
</p>
<p>The utility class to handle this is called <code class="code">Class ReadFileData</code> and
contains three utility methods corresponding to the list above, they are
<code class="code">ReadFileData::From1Col()</code>, <code class="code">ReadFileData::From2Col()</code>,
<code class="code">ReadFileData::FromCSV()</code> and
<code class="code">ReadFileData::FromCSV2()</code>.</p>
<p>These methods are described shortly below</p>
<p>
</p><div class="variablelist"><dl><dt><span class="term"><code class="code">ReadFileData::From1Col($aFileName, $aCol1)</code></span></dt><dd>
<p>Reads data from a text file with one column of data and stores in
the supplied <code class="code">$aCol1</code> vector.</p>
<p>Typical data looks like</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">123
14.5
19.2</span></pre></td></tr></table></div><p>
</p>
<p>which would result in </p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$aCol == array(123, 14.5, 19,2)</span></pre></td></tr></table></div><p>
</p>
</dd><dt><span class="term"><code class="code">ReadFileData::From2Col($aFile, $aCol1, $aCol2, $aSepChar='
')</code></span></dt><dd>
<p>Reads data from a text file with two columns separated by the
specified character.</p>
<p>Typical data looks like</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">12,15
13,34
14,27</span></pre></td></tr></table></div><p>
</p>
<p>which would result in</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$aCol1 == array(12,13,14);
$aCol2 == array(15,34,27);</span></pre></td></tr></table></div><p>
</p>
</dd><dt><span class="term">ReadFileData::FromCSV($aFile,&amp;$aData,$aSepChar=',',$aMaxLineLength=1024)</span></dt><dd>
<p>This method reads comma separated values from a specified file.
The values are all separeted by the specified character. This method
can be seen as a generalization of From1Col() method.</p>
<p>Typical data looks like</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">12,34,56,18,19.7,55</span></pre></td></tr></table></div><p>
</p>
<p>which would result in</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$aData == array(12,34,56,18,19,7,55)</span></pre></td></tr></table></div><p>
</p>
</dd><dt><span class="term">ReadFileData::FromCSV2($aFile, &amp;$aData, $aOptions =
array())</span></dt><dd>
<p>This method also reads comma separated values from a file but with
more advanced options to control how the data is read. This can be
seen as a generalization of From2Col() method.</p>
<p>The possible options and there default values for this method
are</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p>'separator' =&gt; ','</p>
</li><li class="listitem">
<p>'enclosure' =&gt; '"'</p>
</li><li class="listitem">
<p>'readlength' =&gt; 1024</p>
</li><li class="listitem">
<p>'ignore_first' =&gt; false</p>
</li><li class="listitem">
<p>'first_as_key' =&gt; false</p>
</li></ul></div><p>
</p>
<p>Typical data (using the default values)</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">10,55
12,78
15,98</span></pre></td></tr></table></div><p>
</p>
<p>would result in</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$aData = array(
0 =&gt; array(10,12,15),
1 =&gt; array(55,78,98)
);</span></pre></td></tr></table></div><p>
</p>
<p>If 'first_as_key'=&gt;true and the data looks looks like</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">&quot;key&quot;,&quot;value&quot;
10,55
12,78
15,98</span></pre></td></tr></table></div><p>
</p>
<p>the data would instead be read as</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$aData = array(
&quot;key&quot; =&gt; array(10,12,15),
&quot;value&quot; =&gt; array(55,78,98)
);</span></pre></td></tr></table></div><p>
</p>
</dd><dt><span class="term">ReadFileData::FromMatrix($aFile,$aSepChar=' ')</span></dt><dd>
<p>This method is especially suited o read matrix data from a file
for use with the Matrix visualization (described in <a class="xref" href="ch22.html" title="Chapter 22. Matrix graphs">Chapter 22. <i>Matrix graphs</i></a>). Each line in the file
corresponds to one row in the matrix.</p>
<p>Typical data can look like</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">13,87,12
15,99,33
19,86,61</span></pre></td></tr></table></div><p>
</p>
<p>Which wold return a matrix looking like</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">array(
array(13,87,12),
array(15,99,33),
array(19,86,61)
);</span></pre></td></tr></table></div><p>
</p>
</dd></dl></div><p>
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch13.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,371 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Sending data to a graph script with URI arguments (GET and POST)</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch13.html" title="Chapter 13. Getting hold of the data to be displayed"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Sending data to a graph script with URI arguments (GET and POST)</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 13. Getting hold of the data to be displayed</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Sending data to a graph script with URI arguments (GET and POST)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2538267"></a>Sending data to a graph script with URI arguments (GET and POST)</h2></div></div></div>
<p>In order to send data between different HTML pages (or to a specific page) there
are two ways to do this. Either by including the parameters in the URI directly,
(e.g. <code class="code">http://localhost/mygraph.php?d1=12</code>) or by creating a POST request
and send to a page. The details of these two methods are discussed below.</p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>There might be some confusion when to use the <code class="code">'&amp;'</code> and
when to use <code class="code">'&amp;amp;'</code> to separate variables in GET or POST
requests.</p>
<p>When writing URL in HTML the string should always be written with a full
entity encoding since the <code class="code">'&amp;'</code> is a special character
indicating the start of an entity that ends with an <code class="code">';'</code>. So for
example writing a URI in a HTML page should look like.</p>
<p><code class="filename">&lt;a
href="myscript.php?idx=1&amp;amp;start=2009&amp;amp;end=2010"&gt;</code></p>
<p>the browser will then correctly convert the URI to single
<code class="code">'&amp;'</code> which is what should be sent to the server. When
typing URI directly in the browser (or in any plain text file) one should of
course always just use a single <code class="code">'&amp;'</code>
</p>
</div><p>
</p>
<p>
</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
<p>Use the method <code class="code">http_build_query()</code> to build http queries from
an array with keys and values.</p>
</div><p>
</p>
<div class="sect2" title="Using GET arguments"><div class="titlepage"><div><div><h3 class="title"><a name="id2538350"></a>Using GET arguments</h3></div></div></div>
<p>GET arguments are the arguments that can be added as part of the URI. For
example as</p>
<p>
</p><pre class="screen">http://localhost/mygraph.php?id=12&amp;start=20081223&amp;end=20090115</pre><p>
</p>
<p>PHP automatically places all given arguments in the "super global" array
variable <code class="code">$_GET</code> as an associative array.</p>
<p>There are a couple of things to note here</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p>The values in the argument string in the URI must be URL encoded,
this can easily be done with the PHP function
<code class="code">urlencode()</code> (<code class="uri"><a class="uri" href="http://php.net/manual/en/function.urlencode.php" target="_top">See
PHP Manual</a></code>)</p>
</li><li class="listitem">
<p>When the arguments are read from $_GET the must be un-quoted with
a call to <code class="code">urldecode()</code></p>
</li><li class="listitem">
<p>Some browsers restrict the length of the URI that they will read
(typically &lt; 2048bytes) which means that there is a limit on how
much data can be send as URI arguments</p>
</li><li class="listitem">
<p>Some browsers will allow the syntax
<code class="code">"a[0]=10&amp;a[1]=11&amp;a[2]=12"</code> i order to send
the array <code class="code">(10,11,12)</code></p>
</li></ul></div><p>
</p>
<p>This way of specifying the argument string is mostly useful when</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p>The arguments are short</p>
</li><li class="listitem">
<p>When the user should be able to bookmark an URI</p>
</li><li class="listitem">
<p>When the data is not sensitive (since it can be seen in the
URI)</p>
</li><li class="listitem">
<p>When the graph should be viewable by clicking on a link (more on
this when we compare the GET method with the POST method
below)</p>
</li></ul></div><p>
</p>
<p>The "best practice" of using this method is to send a short key (or id) to the
graph script and the graph script itself will use this id to extract the real
data from a DB (or a plain text file). This way the same core graph script can
be used in various context to display wanted data.</p>
</div>
<div class="sect2" title="Using a POST request"><div class="titlepage"><div><div><h3 class="title"><a name="id2538499"></a>Using a POST request</h3></div></div></div>
<p>
</p><div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3>
<p>This is a fairly advanced topic and it is recommended to use the other
methods of sending data to a script unless the specifications explicitly
demands that a POST request is constructed. Furthermore this requires a
very good understanding of HTTP request headers and the difference
between server side and browser side so if you are not sure that you
have the necessary background we strongly recommend to stay away from
this method.</p>
</div><p>
</p>
<p>Two of the obvious restrictions with the GET method is that <span class="bold"><strong>a)</strong></span> the length of the data is restricted and <span class="bold"><strong>b)</strong></span> the data is visible directly in the URI. The other
way to send data as part of the HTTP request is to use the POST method. </p>
<p>Unfortunately this is not as easy as just doing some magic and then we get the
same functionality as with the GET method. Even some authors get this wrong in
some very prominent PHP text books. Unfortunately it will take us too far to
discuss all the details of HTTP request headers (as described in <code class="uri"><a class="uri" href="http://www.w3.org/Protocols/rfc2616/rfc2616.html" target="_top">RFC2616</a></code>)
but we will explain the very basics.</p>
<p>First. let's state what an HTTP request is</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p>A POST HTTP request is used to send data to a specified URI from a
client. A client is normally a WEB-browser but can also (as we will
use it) be a script that sends the request to the same or to another
server. The data is URL encoded and passed in the body of the
request. There is no theoretically limit on the length of the
data.</p>
</li></ul></div><p>
</p>
<p>A further common misunderstanding is that it is possible to use the PHP method
<code class="code">header()</code> in order to create a POST request. This is even given
as an example in the notes to the <code class="code">header()</code> method in the PHP manual
(See <code class="uri"><a class="uri" href="http://php.net/manual/en/function.header.php" target="_top">PHP
Manual</a></code>). This is <span class="bold"><strong>wrong</strong></span>. It is
<span class="bold"><strong>not</strong></span> possible to use the
<code class="code">header()</code> method to send a POST header. Trying to do this
reveals a basic misunderstanding of the role of a server and client.</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p>The <code class="code">header()</code> method is used to send one or more
headers from the server <span class="bold"><strong>to the
client</strong></span> (i.e. WEB-browser)</p>
</li><li class="listitem">
<p>The HTTP POST request goes from the client (i.e. WEB-browser)
<span class="bold"><strong>to the server</strong></span></p>
</li></ul></div><p>
</p>
<div class="figure"><a name="id2538657"></a><p class="title"><b>Figure 13.1. Post vs. header() data direction</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/post_vs_header.png" alt="Post vs. header() data direction"><div class="caption">
<p>Note that the image is greatly simplified to help illustrate the
vital point on data direction. For example the post request shown to
originate from a browser could originate from any client, for
example another script taking the role of a client.</p>
</div></div>
</div></div><br class="figure-break">
<p>Hence it is never possible to "simulate" a POST call with the use of the
<code class="code">header()</code> function. There are basically three (correct) ways to
simulate a POST request as described below.</p>
<p>Before we continue lets first recapitulate the most common use of a POST
request, i.e. in a HTML form submission. When data is entered in a form on a
HTML page and the user presses the "Submit" button the data from the form is
packed as a POST request which is sent to the server at the specified URI (the
action URI). The server will the reply back to the POST request (with the data
sent back from the target of the post request) and the browser will show the
reply in the window in place of the original HTML form page.</p>
<p>However there is a crucial difference when we do this manually from a script
(running on the server) compared with the original form post data from the
browser to the server. After issuing a POST request (originating from a HTML
form) the browser automatically replaces the current page with the reply from
the POST request as a "new" page (by default using the same target window as the
request was made from).</p>
<p>This is not possible to do when sending a "fake" post request to a page since
we are not the browser. Instead what we will see in the browser is the page
<span class="italic">sending the POST request</span>, and not the
target of the post request. The best we can accomplish is to show the reply
inline in the calling page which are then shown in the browser.</p>
<p>This means that it is not possible to create a POST request and then somehow
directly show the reply as the resulting image. Instead what we can do is to
send the data to a image script (via a POST header) and then the graph script
can write the image to a file that is accessible from the server.</p>
<p>So to summarize. What we can do with a post request is to send the data to a
script <code class="filename">b.php</code> from a script <code class="filename">a.php</code>. The
<code class="filename">b.php</code> can then execute some statements, for example
creating a graph and store it on the server. This stored image can later be read
by the <code class="filename">a.php</code> script, for example via a <code class="sgmltag-element">&lt;img&gt;</code>
tag.</p>
<p><span class="bold"><strong>How to create a POST request</strong></span></p>
<p>There are in principle three ways of constructing a POST request to send data
to a specified URI as shown below. </p>
<p>After we have made the request (with any of the three methods shown below) the
server will reply back with the response created by the URI. This response is
any output sent by the script we are sending our request to. Normally this
should just be a return code indicating if the request was successful or
not.</p>
<p>Remember that these are calls made from the script <code class="filename">a.php</code>
running on server <span class="bold"><strong>A</strong></span> to a script
<code class="filename">b.php</code> running on server <span class="bold"><strong>B</strong></span>. There are no browser involved in these calls apart from the
initial request to run <code class="filename">a.php</code>. The figure below illustrates
the first phase when the request is sent to the B side</p>
<p>
</p><div class="figure"><a name="id2538810"></a><p class="title"><b>Figure 13.2. The request phase of a POST header</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/post_request_phase1.png" alt="The request phase of a POST header"><div class="caption">
<p>1. The request is initially made by calling the a.php script,
e.g. http://localhost/a.php in the browser</p>
<p>2. When the a.php script is executed it will create the POST
header and call script b.php o the server B (could possibly be
the same server). Since the browser is displaying script a.php
we can never change that directly but we can display the reply
from b.php in the page displayed by a.php</p>
</div></div>
</div></div><p><br class="figure-break">
</p>
<div class="figure"><a name="id2538834"></a><p class="title"><b>Figure 13.3. The reply phase of a POST request</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/post_request_phase2.png" alt="The reply phase of a POST request"><div class="caption">
<p>3. The b.php returns a reply by fir example echoing back a reply
code</p>
<p>4. The script running the browser receives its final data (which
is the reply from the b.php script) and then finish the original
request started in step 1.</p>
</div></div>
</div></div><br class="figure-break">
<p><span class="bold"><strong>Note:</strong></span> All the <code class="code">sendPostData_vX()</code>
methods below assumes that the data is already urlencoded.</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p><span class="bold"><strong>Create a stream request.</strong></span></p>
<p>The advantage with this method is that it is available by default
in PHP &gt;= 4.3 and of course in PHP5,6 without the need to install
additional libraries.</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-reserved">function</span><span class="hl-code"> </span><span class="hl-identifier">sendPostData_v1</span><span class="hl-brackets">(</span><span class="hl-var">$url</span><span class="hl-code">, </span><span class="hl-var">$data</span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-var">$opts</span><span class="hl-code"> = </span><span class="hl-reserved">array</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string">http</span><span class="hl-quotes">'</span><span class="hl-code"> =&gt; </span><span class="hl-reserved">array</span><span class="hl-brackets">(</span><span class="hl-code">
</span><span class="hl-quotes">'</span><span class="hl-string">method</span><span class="hl-quotes">'</span><span class="hl-code"> =&gt; </span><span class="hl-quotes">'</span><span class="hl-string">POST</span><span class="hl-quotes">'</span><span class="hl-code">,
</span><span class="hl-quotes">'</span><span class="hl-string">header</span><span class="hl-quotes">'</span><span class="hl-code"> =&gt;
</span><span class="hl-quotes">&quot;</span><span class="hl-string">Content-type: application/x-www-form-urlencoded</span><span class="hl-special">\r</span><span class="hl-special">\n</span><span class="hl-quotes">&quot;</span><span class="hl-code">.
</span><span class="hl-quotes">&quot;</span><span class="hl-string">Content-Length: </span><span class="hl-quotes">&quot;</span><span class="hl-code">.</span><span class="hl-identifier">strlen</span><span class="hl-brackets">(</span><span class="hl-var">$data</span><span class="hl-brackets">)</span><span class="hl-code">.</span><span class="hl-quotes">&quot;</span><span class="hl-special">\r</span><span class="hl-special">\n</span><span class="hl-quotes">&quot;</span><span class="hl-code">.
</span><span class="hl-quotes">'</span><span class="hl-string">content</span><span class="hl-quotes">'</span><span class="hl-code"> =&gt; </span><span class="hl-var">$data</span><span class="hl-code">,
</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$stream</span><span class="hl-code"> = </span><span class="hl-identifier">stream_context_create</span><span class="hl-brackets">(</span><span class="hl-var">$opts</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$fp</span><span class="hl-code"> = </span><span class="hl-identifier">fopen</span><span class="hl-brackets">(</span><span class="hl-var">$url</span><span class="hl-code">, </span><span class="hl-quotes">'</span><span class="hl-string">rb</span><span class="hl-quotes">'</span><span class="hl-code">, </span><span class="hl-reserved">false</span><span class="hl-code">, </span><span class="hl-var">$stream</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-reserved">if</span><span class="hl-code"> </span><span class="hl-brackets">(</span><span class="hl-code">!</span><span class="hl-var">$fp</span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code"> </span><span class="hl-comment">//</span><span class="hl-comment"> Some error handling } </span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Find out what the page returns as its body </span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$reply</span><span class="hl-code"> = </span><span class="hl-identifier">stream_get_contents</span><span class="hl-brackets">(</span><span class="hl-var">$fp</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-reserved">if</span><span class="hl-code"> </span><span class="hl-brackets">(</span><span class="hl-var">$reply</span><span class="hl-code"> === </span><span class="hl-reserved">false</span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code"> </span><span class="hl-comment">//</span><span class="hl-comment"> Some error handling } </span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">return</span><span class="hl-code"> </span><span class="hl-var">$reply</span><span class="hl-code">;
</span><span class="hl-brackets">}</span><span class="hl-code">
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div><p>
</p>
</li><li class="listitem">
<p><span class="bold"><strong>Open a socket directly and write to it
</strong></span></p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-reserved">function</span><span class="hl-code"> </span><span class="hl-identifier">sendPostData_v2</span><span class="hl-brackets">(</span><span class="hl-var">$url</span><span class="hl-code">,</span><span class="hl-var">$data</span><span class="hl-code">,</span><span class="hl-var">$port</span><span class="hl-code">=</span><span class="hl-number">80</span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-var">$errno</span><span class="hl-code">=-</span><span class="hl-number">1</span><span class="hl-code">;
</span><span class="hl-var">$errstr</span><span class="hl-code">=</span><span class="hl-quotes">'</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-var">$fs</span><span class="hl-code"> = </span><span class="hl-identifier">fsockopen</span><span class="hl-brackets">(</span><span class="hl-var">$url</span><span class="hl-code">,</span><span class="hl-var">$port</span><span class="hl-code">,</span><span class="hl-var">$errno</span><span class="hl-code">,</span><span class="hl-var">$errstr</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-reserved">if</span><span class="hl-brackets">(</span><span class="hl-code"> </span><span class="hl-var">$fs</span><span class="hl-code"> === </span><span class="hl-reserved">false</span><span class="hl-code"> </span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code"> </span><span class="hl-comment">//</span><span class="hl-comment"> Some error handling } </span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$header</span><span class="hl-code"> = </span><span class="hl-quotes">&quot;</span><span class="hl-string">POST </span><span class="hl-var">$url</span><span class="hl-string"> HTTP/1.0</span><span class="hl-special">\r</span><span class="hl-special">\n</span><span class="hl-quotes">&quot;</span><span class="hl-code">;
</span><span class="hl-var">$header</span><span class="hl-code"> .= </span><span class="hl-quotes">&quot;</span><span class="hl-string">Content-Type: application/x-www-form-urlencoded</span><span class="hl-special">\r</span><span class="hl-special">\n</span><span class="hl-quotes">&quot;</span><span class="hl-code">;
</span><span class="hl-var">$header</span><span class="hl-code"> .= </span><span class="hl-quotes">&quot;</span><span class="hl-string">Content-Length: </span><span class="hl-quotes">&quot;</span><span class="hl-code"> . </span><span class="hl-identifier">strlen</span><span class="hl-brackets">(</span><span class="hl-var">$data</span><span class="hl-brackets">)</span><span class="hl-code"> . </span><span class="hl-quotes">&quot;</span><span class="hl-special">\r</span><span class="hl-special">\n</span><span class="hl-special">\r</span><span class="hl-special">\n</span><span class="hl-quotes">&quot;</span><span class="hl-code">;
</span><span class="hl-identifier">fputs</span><span class="hl-brackets">(</span><span class="hl-var">$fs</span><span class="hl-code">, </span><span class="hl-var">$header</span><span class="hl-code"> . </span><span class="hl-var">$data</span><span class="hl-code"> </span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Find out what the page returns as its body </span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$reply</span><span class="hl-code"> = </span><span class="hl-quotes">'</span><span class="hl-quotes">'</span><span class="hl-code">;
</span><span class="hl-reserved">while</span><span class="hl-brackets">(</span><span class="hl-code"> !</span><span class="hl-identifier">feof</span><span class="hl-brackets">(</span><span class="hl-var">$fs</span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-var">$reply</span><span class="hl-code"> .= </span><span class="hl-identifier">fgets</span><span class="hl-brackets">(</span><span class="hl-var">$fp</span><span class="hl-code">,</span><span class="hl-number">8192</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-brackets">}</span><span class="hl-code">
</span><span class="hl-reserved">return</span><span class="hl-code"> </span><span class="hl-var">$reply</span><span class="hl-code">;
</span><span class="hl-brackets">}</span><span class="hl-code">
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div><p>
</p>
</li><li class="listitem">
<p><span class="bold"><strong> Use CURL to handle all the necessary
details</strong></span></p>
<p><span class="bold"><strong>Note 1:</strong></span> This requires that curl
libraries are installed and that curl is enabled in the PHP
installations. </p>
<p><span class="bold"><strong>Note 2:</strong></span> Depending on the
application there might be many more options that needs to be
tweaked. The one used below are just the bare necessities.</p>
<p><span class="bold"><strong>Note 3:</strong></span> Using CURL is the most
general way to handle POST requests and simplifies the additional
complexity if we want to add encryption (i.e. HTTPS) in the
connection handling.</p>
<div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-reserved">function</span><span class="hl-code"> </span><span class="hl-identifier">sendPostData_v3</span><span class="hl-brackets">(</span><span class="hl-var">$url</span><span class="hl-code">,</span><span class="hl-var">$data</span><span class="hl-brackets">)</span><span class="hl-code">
</span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Initialize and get the curl handle</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$ch</span><span class="hl-code"> = </span><span class="hl-identifier">curl_init</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Include possible headers in the reply from the server as well</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-identifier">curl_setopt</span><span class="hl-brackets">(</span><span class="hl-code"> </span><span class="hl-var">$ch</span><span class="hl-code">, </span><span class="hl-identifier">CURLOPT_HEADER</span><span class="hl-code">, </span><span class="hl-reserved">true</span><span class="hl-code"> </span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Return the reply as a string from curl_exec() instead of directly to stdout</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-identifier">curl_setopt</span><span class="hl-brackets">(</span><span class="hl-code"> </span><span class="hl-var">$ch</span><span class="hl-code">, </span><span class="hl-identifier">CURLOPT_RETURNTRANSFER</span><span class="hl-code">, </span><span class="hl-reserved">true</span><span class="hl-code"> </span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> The URI we want to send the post data to</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-identifier">curl_setopt</span><span class="hl-brackets">(</span><span class="hl-var">$ch</span><span class="hl-code">, </span><span class="hl-identifier">CURLOPT_URL</span><span class="hl-code">, </span><span class="hl-var">$url</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> Use the POST method</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-identifier">curl_setopt</span><span class="hl-brackets">(</span><span class="hl-var">$ch</span><span class="hl-code">, </span><span class="hl-identifier">CURLOPT_POST</span><span class="hl-code">, </span><span class="hl-reserved">true</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> All the data to be sent</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-identifier">curl_setopt</span><span class="hl-brackets">(</span><span class="hl-var">$ch</span><span class="hl-code">, </span><span class="hl-identifier">CURLOPT_POSTFIELDS</span><span class="hl-code">,</span><span class="hl-var">$data</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$reply</span><span class="hl-code"> = </span><span class="hl-identifier">curl_exec</span><span class="hl-code"> </span><span class="hl-brackets">(</span><span class="hl-var">$ch</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-identifier">curl_close</span><span class="hl-brackets">(</span><span class="hl-var">$ch</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-reserved">return</span><span class="hl-code"> </span><span class="hl-var">$reply</span><span class="hl-code">;
</span><span class="hl-brackets">}</span><span class="hl-code">
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div>
</li></ol></div><p>
</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch13.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

View File

@ -0,0 +1,35 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Reading data from a database</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch13.html" title="Chapter 13. Getting hold of the data to be displayed"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Reading data from a database</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 13. Getting hold of the data to be displayed</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Reading data from a database"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2538964"></a>Reading data from a database</h2></div></div></div>
<p>Since there are so many databases and so many ways to organize data in tables it
is impossible to give generic examples. Instead we point out some common pitfalls
when gathering data from a database.</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p>Make sure the data is valid numeric data. It is a common mistake to
read <code class="code">NULL</code> (or empty strings "") values and try to plot
them. Beware that the PHP function <code class="code">empty()</code> also will return
true for 0 and "0" values so it is not enough to just test with
<code class="code">empty()</code> since this will also remove all values that
happens to be valid 0 values. To avoid this use the following modified
empty method.</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">function empty0($aValue){
if ( !is_numeric(trim($aValue)) )
return empty($aValue);
return false;
}</span></pre></td></tr></table></div><p>
</p>
</li><li class="listitem">
<p>Some databases (e.g. MySQL) returns a column with decimal type values
as string in a SELECT statement which normally is handled by automatic
conversion in PHP but since PHP has different interpretation of "0.00"
and 0.00 in respect to what is interpreted as empty or not this needs to
be carefully handled.</p>
</li></ul></div><p>
</p>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch13.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

Some files were not shown because too many files have changed in this diff Show More