===================================================================================================================================
PHPHelp - A simple class to facilitate context sensitive help for websites.
Version 1.0.0
Author: Mark Cole
Copyright 2014 Mark Cole.
Requires: PHP Version 5.1.2 or later.
Released under the GNU General Public Licence http://www.gnu.org/licences/gpl.html
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
The complete distribution package for PHPHelp consists of the following files.
phphelp.class.php ... The PHPHelp class itself.
helpdocs.php ........ Example script that displays the documentation.
phphelp.hxt ......... PHPHelp documentation pn PHPHelp file form to be viewed using helpdocs.php
snippets.txt ........ Example "snippets" file also used by helpdocs.php
phphelp.txt ......... Plain text version of the documentation.
All of the above are Copyright Mark Cole, 2014 and are released under the same GNU licence as phphelp.class.php and should be
included in any modified package that you distribute.
Also in the complete package is LICENCE.TXT, the GNU General Public Licence and this too must be included in any modified
distribution.
Note: PHPHelp and its examples and documentation were written on a Windows XP box (developed with
php 5.4.15/Apache 2.4.4) I apologise for any file encoding problems that may occur for users of other
OS's. PHPHelp has been tested with Linux (PHP 5.3.28/Apache 2.3).
===================================================================================================================================
PHPHelp Documentation - Page 1
==============================
Introduction
------------
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.
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.
I hope that someone else will find it useful.
The best way to view the documentation for PHPHelp is to put the included phphelp.class.php, helpdocs.php, phphelp.hxt and
snippets.txt in a directory on your server and browse to helpdocs.php. That way you not only get to see the documentation but
PHPHelp in action.
Failing that this is a text version of the same documentation.
Index
Basic PHPHelp Usage .... 2
Help file Format ....... 3
Topic Links ............ 4
Macros ................. 5
User Defined Macros .... 6
The $snippet Macro ..... 7
Variable Substitution .. 8
Escape Sequences ....... 9
PHPHelp Methods ........ 10
PHPHelp Variables ...... 11
PHPHelp Constants ...... 12
To Do................... 13
PHPHelp Documentation - Page 2
==============================
Basic Usage
-----------
First, create your help files. See page 3 for information on the Format of Help Files
---------------------------------- Help File Example-----------------------------------------------
#Example help file help.txt
:topic1 This is Topic One
<p>
Here is some help for something\b
What to say, umm, nope, cant't think of any more\b
</p>
:topic2 This is Topic Two
<p>
Completely out of ideas for example text for this.\b
Probably have to resort to Lorem ipsum for later examples!
</p>
---------------------------------------------------------------------------------------------------
Once you have a help file to play with you can retrieve topics from it very simply, as in the following example script.
--------------------------------- PHP Script Example ----------------------------------------------
<?php
require_once 'phphelp.class.php';
$help=new phphelp('/pathto/myhelp.txt');
$topic=$help->help('topic1');
if ($topic)
{
echo "<h1>$topic[0]</h1>";
echo $topic[1];
}
else
{
echo "Help topic not found<br>";
if ($help->error) echo "Error=".$help->errorInfo;
}
----------------------------------------------------------------------------------------------------
Of course you might want to dress up the output a bit!
PHPHelp Documentation - Page 3
==============================
Help file Format
----------------
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 :mytopic 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.
:mytopic This is My Topic
or, for those who like their examples to be more traditional...
:foo bar
Topic names are case sensitive so:
:MyTopic
and
:mytopic
are two different topics.
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).
In addition to text topic blocks can contain links to other topics, Macros, built in and those which you can define
yourself (see pages 5,6), variables (see page 8) and escape sequences. You can also embed text snippets (blocks of often
used text) in a topic using the $snippet macro (see page 7).
Here is an example of a simple help file with two topics
------------------------------------- Help File Example--------------------------------------------
# Example of a simple help file
# Lines starting with a hash are comments except when inside a topic block
:topic1 This is Topic One
Here is some help about topic one
If there was more to say about it I'd say it!
:
:topic2 This is the Second Topic
<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.
<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 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.
------------------------------------- Help File Example--------------------------------------------
:submit *This will not appear in the list returned by phphelp->topics()
The Submit button sends the contents of a form back to the Website for processing.\bClick the
Submit button when you are satisfied that you have completed the form.\b\b
See also Cancel
-----------------------------------------------------------------------------------------------------
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.
Including Files
---------------
You don't have to have all your topics in one help file, you can use the "include" and "includerole" keywords to include
other files. The include and includerole keywords are always lowercase.
include other.txt
This will tell PHPHelp include the named file (other.txt in the example) when searching for topics. The include 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.
The second form of include is includerole <role> <file>. includerole will include a file only if the current users
role as set by you when you instantiated the help object, matches that specified in the includerole option.
Examples:
includerole administrator /help2/adminhelp.txt
includerole guest /help/guesthelp.txt
includerole 200 /help/privs200.txt
and if phphelp was instantiated with $help=new phphelp("help.txt","guest") 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.
PHPHelp Documentation - Page 4
==============================
Topic Linking
-------------
In any help system you are likely to want links between topics. Of course you can put these in the usual way eg.
<a href="morayball.org/help?topic=atopic">See here for details<a>
but this is hard work so PHP provides a short form for you
@{topic:Title}.
So the link to the next topic in this help can be written as
@{macros:Macros} which saves quite a bit of typing...
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:
"my.domain.com/help.php?topic="
PHPHelp Documentation - Page 5
==============================
Text Macros
-----------
PHPHelp Text 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.
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.
For example, the following are all valid calls to the @date macro..
@date("d/m/Y H:i") = 01/05/2014 20:46
@date() = May 1, 2014 (the date macro assumes an empty string as argument means "use the defaults"
@date = May 1, 2014
while these are not valid.
@date('d/m/Y H:i') (wrong sort of quotes)
@date(
"d/m/Y H:i"
) (Spans more than one line)
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.
@date
-----
@date[(string format)]
Inserts the current date. Optionally a format string can be specified. Date formats are as used
for the PHP date() function (see PHP Manual - Date Function)
If "format" is not given the date is is formatted as: May 1, 2014. With the appropriate format
string @date will of course also give you the time but there is also a @time macro (see below)
@snippet
--------
@snippet([string name]|[string file,string name])
@snippet inserts a block of text (or "snippet") from a file into the current topic.
@snippet has its own topic on page 6
@time
-----
@time[(string format)]
Inserts the current time. Mainly here as a short-form since @date can provide both date and time.
Optional format string is as used for the PHP date() function (see PHP Manual - Date Function)
If "format" is not given the time is is formatted as: 20:46:33. With the appropriate format string
@time will of course also give you the date!
The other built in macros are:
@hostname
---------
Inserts your host name (from _SERVER[SERVER_NAME]) eg: morayball.org
@clienthost
-----------
Gives the host name of the client.
clientip
--------
Gives the IP address of the client: 84.92.57.136
You can also add you own "user-defined" macros by writing a PHP function to return a value and registering it with PHPHelp.
User-defined Macros are dealt with in the next section.
See also: Variable Substitution
Macro Errors
------------
Assuming that the variable phphelp->ignoreErrors is set false (the default) then when an error occurs while PHPHelp is
interpreting a macro (and here I mean a syntax error in the macros arguments) you will see an error message displayed
in place of the help topic you were expecting. The error message will tell you the nature of the error and the file and
line where it occurred. It is important to note that macros in a line are interpreted right to left so that if you have
more than one error you will see what you would expect to be the last one first. The syntax errors detected by PHPHelp
for user-defined macros are limited to such things as missing quotes, commas or closing brackets.
@macro(bad arg") will produce this error: Expected "," or closing ")"
whereas
@macro(badarg") will be accepted as one argument, the string badarg"
This is because the first example is seen as one argument - "bad" and PHPHelp will expect that it will be followed either
by a comma and another argument OR by a closing bracket.
The simplistic method of parsing used by PHPHelp can lead to odd errors if you ask too much of it.
The best bet is simply to wrap all arguments in quotes.
PHPHelp Documentation - Page 6
==============================
User-Defined Macros
-------------------
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 PHPHelp->registerCallbackMacro() 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.
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.
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).
If your function requires NO arguments there is no need to put empty brackets after its name when you call it. @mymacro is fine
instead of @mymacro(). Note also that empty brackets are treated as one argument consisting of an empty string so mymacro()
translates as mymacro("").
Example:
----------------------------------- User-Defined Macro Example - PHP Code--------------------------
<?php
require_once("phphelp.class.php");
function username()
{
return $_SESSION['username'];
}
$help=new phphelp('help.txt');
$help->registerCallbackMacro('username');
---------------------------------------------------------------------------------------------------
and now you can write topics that include @username as part of the text.
:contents Help Contents
<p>Hello @username, the following are the main help topics.</p>
...and so on
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.
One example of the use of user-defined macros appears on every page of this help that you are reading. The links at the top of
each page Back to Index and at the bottom of each page Next Topic and Back to Index are generated by a user-defined macro.
This is the help file entry for the topic you are currently reading...
:macros Text Macros
@indexlink("")
<p>
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)...
...and so on...
</p>
@indexlink("@{snippet:The @Snippet Macro}")
and in the helpdocs.php script..
function indexlink($s)
{
if ($s) return '<div style="float:right">@{phphelp:Back to Index}</div><div>Next Topic: '.$s.'</div>';
else return '<p style="text-align: right;">@{phphelp:Back to Index}</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:
$help->registerMacro('substr');
:example Example Topic
This uses the substr function to say <strong>@substr("Hello World",0,5)</strong>
Will produce the following:
This uses the substr function to say Hello
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.
PHPHelp Documentation - Page 7
==============================
The @snippet Macro
------------------
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 PHPHelp->snippetFile.
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 infinite
loops (eg. snippet one includes snippet two which includes snippet one). Granted that is not a likely scenario but it is
possible.
To include a snippet in a topic call @snippet with the name of the snippet and, optionally the file that contains it.
@snippet([name]|[path,name])
EG:
Include my snippet @snippet("mysnippet") here
and another @snippet("/help/mysnippets.txt","mysnippet") here.
Examples.
Using the default snippet file:
---------------------------------- Example snippet.txt file ----------------------------------
:copyright
<p style="position: relative; text-align:center; font-weight: bold: font-size: 8pt">
All content Copyright 2014 the foo organisation.
</p>
----------------------------------------------------------------------------------------------
-------------------------------------- Example help file -------------------------------------
:foo Yes, this is an Example
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
@snippet("copyright")
:bar Another Topic
More stuff
-----------------------------------------------------------------------------------------------
Click here to see the result.
Specifying a snippet file:
--------------------------
----------------------------------------- Example help file -----------------------------------
:bar The Snippet Macro
This here is an example that shows how to use snippets. Today we will be
taking our snippet from a named file. @snippet("/help/mysnippets.txt","copyright")
:foobar Another Topic
More stuff
-----------------------------------------------------------------------------------------------
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:
--------------------------------------------- PHP Example -------------------------------------
<?php
require_once 'phphelp.class.php';
$helpfile='/pathto/myhelp.txt';
$help=new phphelp($helpfile);
$help->snippetFile=$helpfile; //use the same file for help topics and snippets
-----------------------------------------------------------------------------------------------
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.
PHPHelp Documentation - Page 8
==============================
Variable Substitution
---------------------
Variable Substitution works in much the same way as it does in PHP Strings but is not as sophisticated.
In order to use a PHP Variable in your help text you must first register it with PHPHelp using registerVar
registerVar(string name,mixed $Var)
----------------------- PHP example ----------------------------
$example = "This is an example of variable substitution.";
$help=new phphelp($helpfile);
$help->registerVar('example',$example);
----------------------------------------------------------------
Then you can use the variable in help files in the normal way:
-------------------------------------- Example help file -------------------------------------
:varsubexample Example Variable Substitution
\t<strong>The variable \$example says: $example</strong>
----------------------------------------------------------------------------------------------
Things to remember when using variable substitution:
1) The parsing for variable substitution is very simplistic and easily confused!.
2) Use curly-brackets around variable names if the variable name is embedded in a word otherwise it will not be
matched.
EG: "this is an embedded $varname" will not work with a variable named $var
"this is an embedded {$var}name will"
I don't know when that would be useful but there it is...
3) Variables can be used as arguments to macros
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}}
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 registerVar()). There is no need to escape dollar signs otherwise (though it
would be a good practice to do so).
6) The name you pass to registerVar() 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.
$help->registerVar('foo',$bar);
...
:topic Some Topic
Here is the value of $foo (displays value of $bar).
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.
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:
-------------------------- Example help file ---------------------------
:atopic
This is a variable from $GLOBALS ... @$somevar
------------------------------------------------------------------------
PHPHelp Documentation - Page 9
==============================
Escape Sequences
----------------
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.
With the exception of \" these escape sequences are NOT interpreted when used in macro arguments.
\@ Escapes the @ (macro prefix) character.
@ must be escaped if it is not followed by a space or a number otherwise PHPHelp will
think it is a macro name.
\: Escapes the : (topic prefix) character.
The colon only needs to be escaped if it occurs as the first (first non-space)
character on a line.
\" Escapes a double quote in macro arguments eg @macro("Say "hello" world")
\\ Escapes the escape character.
\$ Escapes the $ (variable prefix) dollar sign.
Some escapes useful in HTML
\t TAB Translates to four non-breaking spaces ( )
Provides a quick and dirty way of indenting text. Don't expect it to behave
in HTML like a proper TAB, its only really useful to indent the start of
a line.
\b Translates to HTML line break (<b />). Saves a bit of typing..
\< Escapes the less-than sign for HTML (outputs <)
\> Escapes the greater-than sign for HTML (ouputs >)
Miscellaneous Escapes
\r Carriage Return
\n Line Feed
These two are included for completeness but since help files are
usually HTML they are seldom likely to be much use!
PHPHelp Documentation - Page 10
===============================
Public Methods
--------------
PHPHelp has four public Methods including the constructor.
__construct(string $helpfilePath[,string $role=""])
Initialize the object.
$helpfilePath
path of help file. If help file has INCLUDE (or INCLUDEROLE) files they are assumed
to be in the same directory as given in $helpfilePath
$role
Current users (clients) "role". This is a crude "access control" facility to
allow appropriate topics to be displayed depending on the users role on the
site. $role can be anything appropriate to your site - a string or a number
as long as it can be used to match the argument used for INCLUDEROLE instructions
in a help file. For more details and examples see Help file Format
function help(string $topic)
Returns an array containing the specified topic, if it is found in the help file.
The returned array has this format:
array[0] contains the topic title.
array[1] contains the topic text.
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: if (!$topic=$help->topic('topic)).
Thus you can code as follows:
<?php
require_once 'phphelp.class.php';
$help=new phphelp('/pathto/myhelp.txt');
$topic=$help->help('index');
if ($topic)
{
echo "<h1>$topic[0]</h1>";
echo $topic[1];
}
else
{
echo "Help topic not found<br>";
if ($help->error) echo "Error=".$help->errorInfo;
}
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 NOT be set. Therefore:
Empty return array + phphelp->error == true means a file error
Empty return array with !phphelp->error == false means topic not found.
Note that although errors may occur in macro calls these are considered non-fatal and (unless 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:
PHPHelp: Callback function for macro "indexlink" was not found. (File: /help/help.txt, line: 440)
or
PHPHelp: Macro syntax - expecting "," or closing ")". (File: /help/help.txt, line: 529)
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.
function topics([boolean $sort=true])
Returns a multi-dimensional indexed array containing a list of all (see note 1 below) topics in the current
help file.
If sort is TRUE (which is the default) the array is sorted by Topic Title.
If FALSE then topics appear in the array is in the order they were found.
The text of topics is not included.
The array has the following format:
array[][topic][title][link]
Thus:
array[0][topic] contains the name of the first topic
array[0][title] contains the title of the first topic
array[0][link] contains a ready to use link to the topic
array[1][topic] contains the name of the second topic
array[1][title] contains the title of the second topic
(..)
and so on..
Using this you can easily produce an index or table of contents by simply displaying
all of the [link]'s in a foreach loop (or build your own links using [topic] and [title].
1) Topics with no title are, by default, excluded from the list. If you want them included set $includeUntitled=true.
Topics where the title begins with a start (*) will always be excluded from the list.
2) If $sort is TRUE then duplicate topics will be removed but if $sort is false then any duplicates will remain.
function registerCallbackMacro(string $macroname)
Registers a user-defined macro (see User Defined Macros for details).
Returns: void
EG:
$help->registerCallbackMacro("mymacro");
function registerVar(string name, mixed $var)
Registers a variable (by reference) for use in variable substitution (see Variable Substitution for details).
"name" is the name by which you will refer to the variable in help files.
"$var" is the actual PHP variable which name references.
The name 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....
$help->registerVar('$myvar',$myvar);
and
$help->registerVar('myvar',$myvar);
are equivalent (unless, of course, you were using double-quotes around the name!).
Returns: void
PHPHelp Documentation - Page 11
===============================
Public Variables
----------------
boolean $error
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"
string $errorInfo
Reason for error
string $snippetFile
Default file used for $snippet() macro if no path is given in the arguments.
boolean $ignoreErrors
Ignore non-fatal errors (macro errors mostly). If set then no error message will be displayed and parsing
the help topic continues.
Default setting: FALSE
string $linkURI
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.
It will look something like "mydomain.com/script.php?topic="
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.
You should set it to a valid URI complete with a query name and "=" sign. EG:
$help->linkURI="my.domain.com/help.php?topic=";
$linkURI does not include the request method (eg. "http://") but you can add it if you wish.
boolean $includeUntitled
Include untitled topics in the list returned by topics() As untitled topics are generally snippets this is
FALSE by default.
PHPHelp Documentation Page 12
=============================
PHPHelp Constants
-----------------
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.
const HELP_COMMENT_CHAR = '#'
Character used to prefix comment lines in help files.
const HELP_MACRO_CHAR = '@'
Character used to prefix text macro names in help files.
const HELP_TOPIC_CHAR = ':'
Character used to prefix a help topic.
const HELP_QUERY_TOPIC = 'topic'
Query String variable name used when generating links.
PHPHelp Documentation Page 13
=============================
Things to do in Version Two
---------------------------
Indexed help files:
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.
Macro handling could be improved, especially more intelligent handling of parameters.
.
|
Download
