######################################################################
# PHPHelp Documentation as a PHPHelp help file. #
######################################################################
# #
# Put this file, along with helpdocs.php, snippets.txt and #
# phphelp.class.php somewhere executable on your server and then #
# point your browser at helpdocs.php #
######################################################################
# #
# This file and the others in the PHPHelp package are copyright #
# Mark Cole 2014 and are distributed under the terms of the GNU #
# General Public Licence (http://www.gnu.org/licences/gpl.html) #
######################################################################
# Notes: #
# #
# Key words are ":topic <title>" which starts a topic #
# include <filename> Includes named file #
# includerole <role> <filename> includes named file of users role #
# matches (see docs for details) #
# #
# Keywords are case sensitive and must be lower case #
# Topic names are case sensitive. #
# #
# Example includes just for illustration #
# include glossary.txt #
# includerole manager helpinc.txt #
# #
# PS: Help files can have any file type extension, this only uses #
# so that my editor does syntax highlighting. #
######################################################################
######################################################################
# PHPHelp topics #
######################################################################
include extra.txt
includerole mark mark.txt
:phphelp Introduction
<p>
PHPHelp is a simple but hopefully effective class for implementing basic context sensitive help on
a website. It was born of a need I had to provide comprehensive help for a community website I was
building.</p>
<p>
This is a complete rewrite of that original script with what I hope are useful additions such as Macros and Variable Substitutions,
automatic linking (well, semi-automatic) and some other bits. PHPHelp does not display help, that's up to you. What it does do is
provide a comprehensive set of help file features to facilitate the creation of attractive and even, in a small way, dynamic help
topics, find and format those topics as needed and return the topic you want ready to be displayed.
</p>
The script that you are using to view this documentation is a very simple example of how you can use PHPHelp
in your own code.
</p>
<p class="cent">
<h2>Index</h2>
</p>
<ul>
<li>@{usage:Basic PHPHelp Usage}</li>
<li>@{helpfiles:Help file Format}</li>
<li>@{links:Topic Links}</li>
<li>@{macros:Macros}</li>
<li style="margin-left:0.5cm;">@{macros:PHPHelp Macros}
<li style="margin-left:0.5cm;">@{usermacros:User Defined Macros}
<li style="margin-left:0.5cm;">@{snippet:The \@snippet Macro}
<li>@{varsubs:Variable Substitution}
<li>@{escapes:Escape Sequences}
<li>@{methods:PHPHelp Methods}
<li>@{variables:PHPHelp Variables}
<li>@{constants:PHPHelp Constants}
</ul>
<p class="cent">Appendix</p>
<ul><li>@{macroerrors:Macro Errors}</li>
</ul>
:
#############################################################################################################
:usage Basic Usage
@indexlink()
<p>
First, create your help files. Click @{helpfiles:This Link} for information on the @{helpfiles:Format of Help Files}
</p>
<div class="code">
#Example help file help.txt
\b
\:topic1 This is Topic One\b
Here is some help for something\\b\b
What to say, umm, nope, cant't think of any more\\b\b
\b
\:topic2 This is Topic Two\b
Completely out of ideas for example text for this.\\b\b
Probably have to resort to Lorem ipsum for later examples!\b
</div>
<p>
Once you have a help file to play with you can retrieve topics from it very simply, as in the following
example script.
</p>
<div class="code">
<?php\b\b
require_once 'phphelp.class.php';\b\b
$help=new phphelp('/pathto/myhelp.txt');<br>
$topic=$help->help('topic1');<br>
if ($topic) \b
{<br>
\techo "<h1>$topic[0]</h1>";<br>
\techo $topic[1];<br>
\b
}<br>
else \b
{<br>
\techo "Help topic not found<br>";<br>
\tif ($help->error) echo "Error=".$help->errorInfo;<br>
}<br>
</div>
\bOf course you might want to dress up the output a bit!
</p>
@indexlink("@{helpfiles:Help Files}")
:
###########################################################################################################
:helpfiles Help file Format
@indexlink("")
<p>
PHPHelp help files are plain text files containing topic blocks written as HTML. Each Topic starts with a
topic name and, optionally, a title. The topic name is identified by a preceding colon like so
<strong>:mytopic</strong> and ends at the first whitespace character (ie. a space or a newline). The title
if given is separated from the topic by one or more spaces and continues to the end of the line.\b\b
\t<strong>\:mytopic This is My Topic</strong>\b\b
or, for those who like their examples to be more traditional...\b\b
\t<strong>\:foo bar</strong>\b\b
Topic names are case sensitive so:\b\b
\t<strong>\:MyTopic</strong>\b\b
and\b\b
\t<strong>\:mytopic</strong>\b\b
are two different topics.\b
\b
Next comes the text of the topic which ends at the next topic or the end of the file. There is no size limit on
topics (apart memory of course).
</p><p>In addition to text topic blocks can contain links to other topics, @{macros:Text Macros} (which you
can define yourself), @{varsubs:variables} and @{escapes:escape sequences}. You can also embed text snippets
(blocks of often used text) in a topic using the @{macros:\@snippet macro}.
</p>
<p>
Here is an example of a simple help file with two topics\b
</p>
<p>
<div class="code">
# Example of a simple help file\b
# Lines starting with a hash are comments except when inside a topic block\b
\b
\:topic1 This is Topic One\b
Here is some help about topic one\b
If there was more to say about it I'd say it!\b
\:\b
\:topic2 This is the Second Topic\b
<p>
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore
dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip
ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt
mollit anim id est laborum.\b
<p>
</div>
</p>
<p>
One little trick - if you begin a topic title with a star "*" then that topic will be excluded from the list
produced by the topics() method (see @{methods:Public Methods}). This can be of use if, for example, you are
including a glossary in your help file and don't want glossary topics to show up in a list of all topics.
</p>
<div class="code">
\:submit *This will not appear in the list returned by phphelp->topics()\b
The <b>Submit</b> button sends the contents of a form back to the Website for processing.\\b
Click the <b>Submit</b> button when you are satisfied that you have completed the form.\\b\\b\b
See also <b>Cancel</b>
</div>
<p>
Note that although the colon ":" is a special character used to identify a topic name you can also, as
in the example above, use it simply to separate topics and make your help file more readable. Of course
you can also include as many blank lines as you like since this is HTML output.
</p>
<p>
<strong>Including Files</strong>\b\b
You don't have to have all your topics in one help file, you can use the <strong>include</strong> and
<strong>includerole</strong> keywords to include other files. These keywords are always lower case.\b\b
<strong>\tinclude other.txt</strong>\b\b
This will tell PHPHelp include the named file (other.txt in the example) when searching for topics.
The <strong>include</strong> keyword is only valid outside of a topic block but other than that can appear
anywhere in a file. If you include a full path for the include file then that is used. If you only specify a
file name then it is assumed that the file resides in the same directory as the main help file.\b\b
The second form of <strong>include</strong> is <strong>includerole <role> <file>
</strong>. <strong>includerole</strong> will include a file <strong>only</strong> if the current users
<strong>role</strong> as set by you when you created the help object, matches that specified in the
includerole option.\b\b
<strong>\tincluderole administrator /help2/adminhelp.txt\b
\tincluderole guest /help/guesthelp.txt</strong>
\b\b
and if phphelp was instantiated with <strong>$help=new phphelp("help.txt","guest")</strong> then the guest help will
be included. Part of the usefulness of this is that you can have one help file containing general help and
then include specific files that expand on options that might be available only to certain users. Note also that
if you have two topics with the same name then only the first will be found which means that it is possible to
use this "conditional" include to override a later topic for certain users.\b\b
Using <strong>includerole</strong> to control what topics are available to different users you might end up with
a main help file that looks lile this:\b\b
<div class="code">
# This is main.hxt\b
includerole guest guest.hxt\b
includerole normal normal.hxt\b
includerole admin admin.hxt\b
include general.hxt\b
</div>
<p>
PS: I only use .hxt as a file type because my editor recognises it and does syntax highlighting.
</p>
@indexlink("@{links:Topic Linking}")
:
###########################################################################################################
:links Topic Linking
@indexlink()
<p>
In any help system you are likely to want links between topics. Of course you can put these in the usual
way eg.\b\b\t<b><a href="@hostname/help?topic=atopic">See here for details<a></b>\b\b
but this is hard work so PHP provides a short form for you\b\b\t<strong>\@{topic:Title}</strong>.\b\b
So the link to the next topic in this help can be written as\b\b\t<strong>\@{macros:Macros}</strong>
which saves quite a bit of typing...
</p>
<p>
The URI used for links is created at instantiation by taking _SERVER['SCRIPT_URL'] or _SERVER['REQUEST_URI']
(if SCRIPT_URL is not there) and adding the constant HELP_QUERY_TOPIC (which defaults to 'topic'). If this method
does not produce the URI that you need you can set phphelp->linkURI to what you need. You should set it to a valid
URI complete with a query name and "=" sign. EG:\b\b
\t"my.domain.com/help.php?topic="
</p>
@indexlink("@{macros:Macros}")
:
###########################################################################################################
:macros Macros
@indexlink("")
<p>
PHPHelp Macros are simple macros that insert dynamic text into your topic. Macros are referenced by name
and macro names are case sensitive. All macro names are prefixed by a \@ sign (like variables in PHP) If a
macro accepts arguments then these are enclosed in brackets. String arguments should be quoted with double
quotes ("like so") although a one word string (ie. with no spaces can be unquoted. Numeric arguments can be
quoted or not. Where a Macro takes no arguments or arguments are optional (for example the \@date macro) you
can either add empty brackets or not as you like. However you should note that if arguments are optional then
empty brackets are treated as an empty string.
\b\b
A macro and its arguments must all be on the same line. You cannot, as you can with a function call in PHP, get
away with splitting a macro call over more than one line.
\b\b
For example, the following are all valid calls to the <strong>\@date</strong> macro..\b\b
\t<strong>\@date("d/m/Y H:i")</strong> = @date("d/m/Y H:i")\b
\t<strong>\@date()</strong> = @date() (the date macro assumes an empty string as argument means "use the defaults"\b
\t<strong>\@date</strong> = @date\b\b
while these are not valid.\b\b
\t<strong>\@date('d/m/Y H:i')</strong> (wrong sort of quotes)\b
\t<strong>\@date(\b
\t"d/m/Y H:i"\b
\t)</strong> (Spans more than one line)\b
\b
A few simple macros are built into PHPHelp but, with a few exceptions, they are pretty pointless and serve only as
demonstrations should you wish to extend the class.
\b\b
<strong>\@date</strong>
<p class="indent">
<strong>\@date[(string format)]</strong>\b
Inserts the current date. Optionally a format string can be specified. Date formats are as used for the PHP
<strong>date()</strong> function (see <a href="http://php.net/manual/en/function.date.php">PHP Manual - Date Function)</a>\b
\b
If "format" is not given the date is is formatted as: @date. With the appropriate format string \@date will of
course also give you the time but there is also a <strong>\@time</strong> macro (see below)\b\b
</p>
<strong>\@snippet</strong>
</p>
<p class="indent">
<strong>\@snippet([string name]|[string file,string name])</strong>\b\b
\@snippet inserts a block of text (or "snippet") from a file into the current topic.\b
@{snippet:\@snippet has its own topic here}.
</p>
<strong>\@time</strong>
<p class="indent">
<strong>\@time[(string format)]</strong>\b\b
Inserts the current time. Mainly here as a short-form since <strong>\@date</strong> can provide both date and time.\b\b
Optional format string is as used for the PHP <strong>date()</strong> function
(see <a href="http://php.net/manual/en/function.date.php">PHP Manual - Date Function)</a>\b
\b
If "format" is not given the time is is formatted as: @time. With the appropriate format string \@time will of
course also give you the date!\b\b
</p>
<p>
The other built in macros are:\b\b
<strong>\@hostname</strong> inserts your host name (from _SERVER[SERVER_NAME]) eg: <strong>@hostname</strong>\b
<strong>\@clienthost</strong> gives the host name of the client: <strong>@clienthost</strong>\b
and <strong>\@clientip</strong> gives the IP address of the client: <strong>@clientip</strong>\b
</p>
<p>You can also add you own "user-defined" macros by writing a PHP function to return a value and registering it
with PHPHelp.\b@{usermacros:User-defined Macros} are dealt with in the next section.
</p>
<p><strong>See also:</strong> @{varsubs:Variable Substitution}</p>
<p>
\b
<strong>Macro Errors</strong>\b\b
</p>
@snippet("macroerrors")
@indexlink("@{usermacros:User Defined Macros}")
:
###########################################################################################################
:usermacros User-Defined Macros
@indexlink()
<p>
You do not have to extend the class just to add macros, all you need to do is write a callable function in
your own script that returns a string value, call <strong>PHPHelp->registerCallbackMacro()</strong> with
the name of the function and thereafter whenever you use that function name as a macro in a help topic PHPHelp
will call your function and insert the string it gets into the text.\b\b
PHPHelp checks for user-defined macros before checking for its own built in macros so a user defined macro can override a
built in one.\b\b
You function can accept any number of arguments but be aware that the syntax check in PHPHelp is limited to
spotting malformed arguments (such as missing a quote) so it's up to you to make sure that you pass the right
number of arguments when you call a macro (the usual warnings will appear in PHP's error log).\b\b
If your function requires NO arguments there is no need to put empty brackets after its name when you call it.
<strong>\@mymacro</strong> is fine instead of <strong>\@mymacro()</strong>. Note also that empty brackets are
treated as one argument consisting of an empty string so <strong>\@mymacro()</strong> translates
as <strong>@mymacro("")</strong>!
\b\b
Example:
</p>
<div class="code">
<?php\b
require_once("phphelp.class.php");\b\b
function username()\b
{\b
\treturn $_SESSION['username'];\b
}\b
\b
$help=new phphelp('help.txt');\b
$help->registerCallbackMacro('username');\b
</div>
<p>
and now you can write topics that include \@username as part of the text.
</p>
<div class="code">
\:contents Help Contents\b
Hello \@username, the following are the main help topics.\b
...and so on
</div>
<p>Macro arguments can themselves contain macro calls so that the result of one macro can be the argument to
another but note that the text your function returns cannot itself contain macro references (well, it can but
they will not have any effect) but it CAN contain the link "macro" \@{link:title} which WILL be converted
to a proper link.
</p>
<p>One example of the use of user-defined macros appears on every page of <strong>this</strong> help that you
are reading. The links at the top of each page <b>Back to Index</b> and at the bottom of each page <b>Next Topic</b>
and <b>Back to Index</b> are generated by a user-defined macro.
\b
\b
This is the help file entry for the topic you are currently reading...
</p>
<div class="code">
\:macros Text Macros\b
<strong>\@indexlink("")</strong>\b
<p>\b
PHPHelp Text Macros are simple macros that insert dynamic text into your topic. Macros are referenced by
name. All macro names are prefixed by a \@ sign (like variables in PHP)...\b
...and so on...\b
</p>\b
<strong>\@indexlink("\@{snippet:The \@Snippet Macro}")</strong>\b
</div>
<p>and in the PHP script..\b
<div class="code">
function <strong>indexlink($s)</strong>\b
{\b
\tif ($s) return '<div style="float:right">\@{phphelp:Back to Index}</div><div>Next Topic: '.$s.'</div>';\b
\t\telse return '<p style="text-align: right;">\@{phphelp:Back to Index}</p>';\b
}
</div>
<p>It is worth noting that the User Defined Macro mechanism also works for PHP built in functions. If you
register the name of a PHP function with PHPHelp you can then use it from within a help topic. For example:\b\b
<div class="code">
$help->registerMacro('substr');\b
</div>
\b
<div class="code">
\:example Example Topic\b
This uses the substr function to say <strong>\@substr("Hello World",0,5)</strong>\b
</div>
<p>
Will produce the following:\b\b
This uses the substr function to say <strong>@substr("Hello World",0,5)</strong>
\b\b
The use of PHP functions as macros in this way has not been extensively tested and indeed I'm not sure
how useful it is, but it can be done.
</p>
@indexlink("@{snippet:The \@Snippet Macro} <- See the above example of macros in use!")
:
#############################################################################################################
:snippet The @snippet Macro
@indexlink("")
<p>
This macro will insert a block of text (or "snippet") from help file into a topic. It is used to insert
snippets of text that appear regularly. By default snippets are taken from a file called "snippets.txt"
which is expected to reside in the same direcory as your help file, However, you can change that by
specifying a different file when you call the \@snippet macro or by setting your desired file path in
<strong>PHPHelp->snippetFile</strong>.\b\b
Snippets are blocks of text that have the same format as help topics (and, indeed the \@snippet macro will
happily insert a complete topic (without title) if you ask it to since the same method that reads topics is
used to read snippets. Because of this snippets can themselves include macros and, therefore, other snippets.
If you use nested snippets beware of <b>infinite loops</b> (eg. snippet one includes snippet two which includes
snippet one). Granted that is not a likely scenario but it is possible.
</p><p>
To include a snippet in a topic call \@snippet with the name of the snippet and, optionally the file that
contains it.
<p>
<p class="indent">
<strong>\@snippet([name]|[path,name])</strong>\b\b
</p>
<div class="code">
Include my snippet <strong>\@snippet("mysnippet")</strong> here\b
and another <strong>\@snippet("/help/mysnippets.txt","mysnippet")</strong> here.\b
</div>
<p>
<strong>Examples.</strong>\b\b
Using the default snippet file:
<div class="code">
# Example snippet.txt file\b
\:copyright\b
<p style="position: relative; text-align:center; font-weight: bold: font-size: 8pt">\b
All content Copyright 2014 the foo organisation.\b
</p>\b
</div>
\b
<div class="code">
# Example help file\b
\:foo Yes, this is an Example\b
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore\b
dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip\b
\@snippet("copyright")\b\b
\:bar Another Topic\b
More stuff\b
</div>
<p class="cent">@{example1:See the result here}</p>
<p>
Specifying a snippet file:
</p>
<div class="code">
# Example help file\b
\:bar The Snippet Macro\b
This here is an example that shows how to use snippets. Today we will be\b
taking our snippet from a named file.
\@snippet("/help/mysnippets.txt","copyright")\b\b
\:foobar Another Topic\b
More stuff\b
</div>
<p>
There is nothing to stop you keeping your snippets in the same file as your help topics and, for convenience,
setting the default snippet file to the same as the help file:
<p>
<div class="code">
<?php\b\b
require_once 'phphelp.class.php';\b\b
$helpfile='/pathto/myhelp.txt';\b
$help=new phphelp($helpfile);\b
$help->snippetFile=$helpfile;\t\t//use the same file for help topics and snippets\b
\b
</div>
<p>
However, if your main help file is large it's probably better to use a separate snippets file simply to
save PHPHelp searching through so much text each time a snippet is referenced.
</p>
@indexlink("@{varsubs:Variable Substitution}")
:
###########################################################################################################
:varsubs Variable Substitution
@indexlink()
<p>
Variable Substitution works in much the same way as it does in PHP Strings but is not as sophisticated.\b\b
In order to use a PHP Variable in your help text you must first register it with PHPHelp using @{methods:registerVar}
</p>
<p class="indent"><strong>registerVar(string name,mixed $Var)</strong></p>
<p>
<div class="code">
<p>
\$example = "This is an example of variable substitution.";\b
$help=new phphelp($helpfile);\b
$help->registerVar('example',\$example);\b
</p>
</div>
<p>Then you can use the variable in help files in the normal way:</p>
<div class="code">
<p>
\:varsubexample Example Variable Substitution\b
\\t\<strong\>The variable \\$example says: \$example\</strong\>\b
<p>
</div>
<p>
The above example actually exists in the snippets.txt file, here it is inserted into this topic\b\b
@snippet("varsubexample")
</p>
<p>
Things to remember when using variable substitution:
</p>
<p class="indent">
1) The parsing for variable substitution is very simplistic and easily confused!.\b\b
2) Use curly-brackets around variable names if the variable name is embedded in a word otherwise it will not be matched.\b\b
\tEG: "this is an embedded $varname" will not work with a variable named $var\b
\t"this is an embedded {$var}name will"\b\b
I don't know when that would be useful but there it is...\b\b
3) Variables can be used as arguments to macros\b\b
4) If you use a variable as an argument to the @{link} macro you need to double the closing curly bracket because
the brainless parser will eat it (told you it was easily confused). Use \@{topic:$var}}\b\b
5) Use \\$ to escape the dollar sign if you don't want to substitute it. But that only matters if the
variable exists (ie. has be registered with <strong>registerVar()</strong>). There is no need to escape
dollar signs otherwise (though it would be a good practice to do so).\b\b
6) The name you pass to <strong>registerVar()</strong> does not have to be the same as the name of the
variable that you are registering, it can be anything you like as long as you always refer to the variable
by that name in your help files.\b\b
</p>
<div class="code">
<p>
$help->registerVar('foo',$bar);\b
...\b
\:topic Some Topic\b
Here is the value of $foo (displays value of $bar).\b
</p>
</div>
<p>
There is a second way to do variable substitution. It only works for global variables, and only for simple
variables not arrays, but it does not require you to register the variable through registerVars(). This is
a method that was left over from an earlier version of PHPHelp before "proper" variable substitution was
added.\b\b
Simply prefix the name of a GLOBAL variable with the macro prefix (@) and (if it exists in $GLOBALS) the
value of the variable will be substituted:
</p><div class="code">
\:atopic\b
This is a variable from $GLOBALS ... \@$somevar
</div>
<p>
In this script (helpdocs.php) $helpfile is a global so \@$helpfile should display the name of this helpfile
like so:<strong> $helpfile=@$helpfile</strong>.
</p>
@indexlink("@{escapes:Escape Sequences}")
:
###########################################################################################################
:escapes Escape Sequences
@indexlink()
<p>
PHPHelp recognises a few escape sequences which it will interpret when parsing a help file. These escape sequences
are also interpreted when used in the values returned by user-defined macros.\b\b
With the exception of \\" these escape sequences are NOT interpreted when used in macro arguments.
</p>
<p class="indent">
<strong>\\@</strong> Escapes the \@ (macro prefix) character.\b\b
\t\@ must be escaped if it is not followed by a space or a number otherwise PHPHelp will\b
\tthink it is a macro name.\b\b
<strong>\\:</strong> Escapes the \: (topic prefix) character.\b\b
\tThe colon only needs to be escaped if it occurs as the first (first non-space)\b
\tcharacter on a line.\b\b
<strong>\\"</strong> Escapes a double quote in macro arguments eg \@macro("Say \"hello\" world")\b\b
<strong>\\\</strong> Escapes the escape character.\b\b
<strong>\\$</strong> Escapes the \$ (variable prefix) dollar sign.\b\b\b
<strong>Some escapes useful in HTML</strong>\b\b
<strong>\\t</strong> TAB
\tTranslates to four non-breaking spaces (&nbsp)\b\b
\tProvides a quick and dirty way of indenting text. Don't expect it to behave\b
\tin HTML like a proper TAB, its only really useful to indent the start of\b
\ta line (as is done here).\b\b
<strong>\\b</strong> Translates to HTML line break (<b />). Saves a bit of typing..\b\b
<strong>\\<</strong> Escapes the less-than sign for HTML (outputs &lt;)\b\b
<strong>\\></strong> Escapes the greater-than sign for HTML (ouputs &gt;)\b\b
<strong>Miscellaneous Escapes</strong>\b\b
<strong>\\r</strong> Carriage Return\b
<strong>\\n</strong> Line Feed\b\b
\tThese two are included for completeness but since help files are\b
\tusually HTML they are seldom likely to be much use!
</p>
@indexlink("@{methods:Public Methods}")
:
###########################################################################################################
:methods Public Methods
@indexlink("")
<p>
PHPHelp has four public Methods including the constructor.\b\b
<strong> __construct(string $helpfilePath[,string \@role=""])</strong>
</p>
<p class="indent">
Initialize the object.\b\b
$helpfilePath\b\b
\tpath of help file. If help file has INCLUDE (or INCLUDEROLE) files they are assumed\b
\tto be in the same directory as given in $helpfilePath\b\b
\b
$role\b
\tCurrent users (clients) "role". This is a crude "access control" facility to\b
\tallow appropriate topics to be displayed depending on the users role on the\b
\tsite. $role can be anything appropriate to your site - a string or a number\b
\tas long as it can be used to match the argument used for INCLUDEROLE instructions\b
\tin a help file. For more details and examples see @{helpfiles:Help file Format}\b\b
</p>
<p>
<strong>function help(string $topic)</strong>\b\b
</p>
<p class="indent">
Returns an array containing the specified topic, if it is found in the help file.\b\b
The returned array has this format:\b\b
\tarray[0] contains the topic title.\b
\tarray[1] contains the topic text.\b\b
If the topic is not found or a fatal error occurs (typically "Help file not found") then an empty array is
returned which you can trap with: <i><b>if (!\$topic=$help->topic('topic))</code></b></i>\b\b
Thus you can code as follows:\b\b
</p>
<div class="codei">
<?php\b\b
require_once 'phphelp.class.php';\b\b
$help=new phphelp('/pathto/myhelp.txt');<br>
$topic=$help->help('index');<br>
if ($topic) \b
{<br>
\techo "<h1>$topic[0]</h1>";<br>
\techo $topic[1];<br>
\b
}<br>
else \b
{<br>
\techo "Help topic not found<br>";<br>
\tif ($help->error) echo "Error=".$help->errorInfo;<br>
}<br>
</div>
<p class=indent">
In the event of a fatal error (such as "Help file not found") the variable phphelp->error will be TRUE and
phphelp->errorInfo will be set to the reason. If the error is simply "Topic not found" then phphelp->error
will <strong>not</strong> be set. Therefore:
</p>
<p class=indent>
Empty return array + phphelp->error == true means a file error\b
Empty return array with !phphelp->error == false means topic not found.
</p><p>
Note that although errors may occur in macro calls these are generally considered non-fatal
and (unless @{variables:phphelp->ignoreErrors} is set true) an error message will be
returned as the topic text (instead of the actual content of the requested topic).
EG:
</p>
<div class="code">
PHPHelp: Callback function for macro "indexlink" was not found. (File: /help/help.txt, line: 440)\b
PHPHelp: Macro syntax - expecting "," or closing ")". (File: /help/help.txt, line: 529)
</div><p>
This should aid debugging of help files. It is probably better to set \$ignoreErrors
to TRUE for production sites so that users will at least see the help topic, albeit
perhaps with some bits missing. When \$ingnoreErrors is TRUE the macro that caused the error is seen just
as it appears in the raw text of the topic and no error is displayed.
</p>
<p>
<strong>function topics([boolean $sort=true])</strong>
</p>
<p class="indent">
Returns a multi-dimensional indexed array containing a list of all topics<sup>1</sup> in the current help file.\b
If $sort is TRUE (which is the default) the array is sorted by Topic Title.\b
If FALSE then topics appear in the array is in the order they were found.\b\b
The text of topics is not included.\b\b
The array has the following format:\b\b
\tarray[][topic][title][link]\b\b
\tThus:\b\b
\t\tarray[0][topic] contains the name of the first topic\b
\t\tarray[0][title] contains the title of the first topic\b
\t\tarray[0][link] contains a ready to use link to the topic\b
\t\tarray[1][topic] contains the name of the second topic\b
\t\tarray[1][title] contains the title of the second topic\b
\t\t(..)\b\t\tand so on..\b\b
Using this you can easily produce an index or table of contents by simply displaying\b
all of the [link]'s in a foreach loop (or build your own links using [topic] and [title].\b\b
1)Topics with no title are, by default, excluded from the list. If you want them included set @{variables:phphelp->includeUntitled=true}.
Topics where the title begins with a start (*) will always be excluded from the list.\b\b
2) If \$sort is TRUE then duplicate topics will be removed but if \$sort is false then any duplicates will remain.
</p>
<p>
<strong>function registerCallbackMacro(string \@macroname)</strong>
</p>
<p class="indent">
Registers a user-defined macro (see @{usermacros:User Defined Macros} for details).\b\b
Returns: void
</p>
<p>
<strong>function registerVar(string name, mixed $var)</strong>
</p>
<p class="indent">
Registers a variable (by reference) for use in variable substitution (see @{varsubs:Variable Substitution} for details).\b\b
<strong>name</strong> is the name by which you will refer to the variable in help files.\b\b
<strong>\$var</strong> is the actual PHP variable which <strong>name</strong> references.\b\b
The <strong>name</strong> you pass as parameter one does not have to be the same as the name of the variable
passed as parameter two as long as it IS the name used to refer to the variable in help files. You can include
a leading \$ or not as you wish....\b\b
\t<strong>$help->registerVar('$myvar',$myvar)</strong>\b\b
\tand\b\b
\t<strong>$help->registerVar('myvar',$myvar)</strong>\b\b
are equivalent (unless, of course, you were using double-quotes around the name!).\b\b
Returns: void
</p>
@indexlink("@{variables:Public Variables}")
:
############################################################################################################
:variables Public Variables
@indexlink("")
boolean <strong>$error</strong>\b
<p class="indent">Set TRUE if an error occurs. The error message will be in $errorInfo. This is only really
of use for fatal errors the only one of which is "Unable to read help file"</p>
string <strong>$errorInfo</strong>
<p class="indent">Reason for error</p>
string <strong>$snippetFile</strong>\b
<p class="indent">Default file used for \@snippet() macro if no path is given in the arguments.</p>
boolean <strong>$ignoreErrors</strong>\b
<p class="indent">Ignore non-fatal errors (macro errors mostly). If set then no error message will be displayed and parsing
the help topic continues.\b\bDefault setting: FALSE</p>
string <strong>$linkURI</strong>
<p class="indent">Default link uri formed from current URI using $_SERVER[SCRIPT_URL] or $_SERVER['REQUEST_URI'] with a query variable
name appended (using the constant phphelp::HELP_QUERY_TOPIC) + an "=" sign ready to append a topic name when
a link is needed.\b\bIt will look something like "mydomain.com/script.php?topic="\b\b
The _SERVER variables available to PHP depend on server configuration and cannot be guaranteed so if PHPHelp is not producing appropriate
links when you use \@{topic:Title} to make a link you can set this to something that works for your system.\b\bYou should set it to a valid
URI complete with a query name and "=" sign. EG: \b\b$help->linkURI="my.domain.com/help.php?topic=";\b\b
$linkURI does not include the request method (eg. "http://") but you can add it if you wish.
</p>
boolean <strong>$includeUntitled</strong>
<p class="indent">Include untitled topics in the list returned by topics() As untitled topics are generally snippets
this is FALSE by default.</p>
@indexlink("@{constants:PHPHelp Constants}")
:
############################################################################################################
:constants PHPHelp Constants
@indexlink()
<p>
These constants can be changed if you really need to but be aware when changing HELP_MACRO_CHAR or HELP_TOPIC_CHAR
there maybe ramifications when changing to or from a PCRE meta character. There are notes in the code.
</p>
const <strong>HELP_COMMENT_CHAR = '#'</strong>
<p class="indent">Character used to prefix comment lines in help files.</p>
const <strong>HELP_MACRO_CHAR = '@'</strong>
<p class="indent">Character used to prefix text macro names in help files.</p>
const <strong>HELP_TOPIC_CHAR = ':'</strong>
<p class="indent">Character used to prefix a help topic.</p>
const <strong>HELP_QUERY_TOPIC = 'topic'</strong>
<p class="indent">.</p>
@indexlink()
:
############################################################################################################
:macroerrors Macro Errors
@snippet("macroerrors")
@indexlink("")
:
############################################################################################################
:todo Things to do in version two
@indexlink("")
<p>
Indexed help files:
</p><p class="indent">
PHPHelp is not really aimed at massive sites with thousands of visitors so the fact that it searches through
the whole help file to find a topic is not especially problematical, still it would be nice if it could
build and use an index.
</p>
<p>
Macro handling could be improved, especially more intelligent handling of parameters.
</p>
@indexlink("")
:
############################################################################################################
# Live examples
############################################################################################################
:example1 Example of a Topic which includes a snippet
<p>
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore
dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip
</p>
@snippet("/website/phpballsource/phphelp/snippets.txt","copyright")
:
############################################################################################################
|
Download
