Skip to content
Snippets Groups Projects
Commit c266542e authored by Gisle Hannemyr's avatar Gisle Hannemyr
Browse files

Issue #2832269 by gisle: Added display of README along with HTML

parent 50986e7c
No related branches found
No related tags found
No related merge requests found
Showing
with 337 additions and 393 deletions
---
# Define an alias for screendumps.
aliases:
hide: TRUE
title: ALIASES
block:
- &screendumps
type: asset
approved: allowed license
license: CC0
rights: https://creativecommons.org/publicdomain/zero/1.0/
source: Gisle Hannemyr
help.png:
title: help.png
type: asset
approved: allowed license
license: CC0
rights: https://creativecommons.org/publicdomain/zero/1.0/
source: unknown origin
hide: TRUE
help/ahelp_tab.png:
title: ahelp_tab.png
hide: TRUE
a: *screendumps
help/click_icon.png:
title: click_icon.png
hide: TRUE
a: *screendumps
...@@ -6,6 +6,7 @@ CONTENTS OF THIS FILE ...@@ -6,6 +6,7 @@ CONTENTS OF THIS FILE
* Recommended modules * Recommended modules
* Installation * Installation
* Configuration * Configuration
* Support status
* Maintainers * Maintainers
...@@ -31,8 +32,7 @@ Advanced help hint: ...@@ -31,8 +32,7 @@ Advanced help hint:
https://www.drupal.org/project/advanced_help_hint https://www.drupal.org/project/advanced_help_hint
If Advanced help is not enabled, this module will generate a hint If Advanced help is not enabled, this module will generate a hint
string that can be used in the project's hook_help to hint that string that can be used in the project's hook_help to hint that
Advanced help should be Advanced help should be enabled.
enabled.
Installation Installation
...@@ -47,11 +47,31 @@ further information. ...@@ -47,11 +47,31 @@ further information.
Configuration Configuration
------------- -------------
By itself, this module doesn't do much. The Advanced help assists There is no configuration.
other modules and themes in showing help texts. Nothing will show up
until you enable at least one other module that makes use of the When you enable the module, you will have access to on-screen help,
Advanced help framework or comes with a file named README.md or including README-files, created to tie in with the **Advanced help**
README.txt. framework.
Support status
--------------
Reported bugs for the Drupal 7 branch will be fixed in a timely
manner. Older versions are no longer supported.
Community support in the form of patches are very welcome for both
Drupal 7 and Drupal 8 versions. For QA, the project needs community
support in the form of reviews of patches, development versions and
releases.
The primary goal of the module is to remain light-weight and simple.
This means that not all feature requests will be implemented, even if
they are a good idea. Feature requests accompanied by patches are
more likely to make it into a release.
The maintainer hopes that the community is willing to help out by
answering & closing support requests.
Maintainers Maintainers
......
...@@ -32,10 +32,27 @@ ...@@ -32,10 +32,27 @@
* links.) * links.)
*/ */
/**
* Implements hook_help().
*/
function advanced_help_help($path, $arg) {
if ($path == 'admin/help#advanced_help') {
$output = '<p>' . t('This module provides extended help and documentation.') . '</p>';
if (function_exists('advanced_help_hint_docs')) {
$output .= '<p>' . advanced_help_hint_docs('advanced_help', 'https://www.drupal.org/docs/7/modules/advanced-help', TRUE) . '</p>';
}
else {
$output .= t('If you install and enable the module <strong>!url</strong>, you will get more help for <strong>Advanced help</strong>.',
array('!url' => l('Advanced help hint', 'https://www.drupal.org/project/advanced_help_hint')));
}
return $output;
}
}
/** /**
* Implements hook_menu(). * Implements hook_menu().
* *
* Strings in hook_help() should not be run through t(). * Strings in hook_menu() should not be run through t().
*/ */
function advanced_help_menu() { function advanced_help_menu() {
$help_exists = module_exists('help') ? TRUE : FALSE; $help_exists = module_exists('help') ? TRUE : FALSE;
...@@ -590,7 +607,7 @@ function theme_advanced_help_topic($variables) { ...@@ -590,7 +607,7 @@ function theme_advanced_help_topic($variables) {
function advanced_help_get_topic_filename($module, $topic) { function advanced_help_get_topic_filename($module, $topic) {
$info = advanced_help_get_topic_file_info($module, $topic); $info = advanced_help_get_topic_file_info($module, $topic);
if ($info) { if ($info) {
return "./$info[path]/$info[file]"; return "$info[path]/$info[file]";
} }
} }
...@@ -605,6 +622,9 @@ function _advanced_help_get_module_type($module) { ...@@ -605,6 +622,9 @@ function _advanced_help_get_module_type($module) {
/** /**
* Load and render a help topic. * Load and render a help topic.
*
* The strategy is first to see if a translated file for the current
* active language exists. If not found, look for the default.
*/ */
function advanced_help_get_topic_file_info($module, $topic) { function advanced_help_get_topic_file_info($module, $topic) {
global $language; global $language;
...@@ -617,16 +637,14 @@ function advanced_help_get_topic_file_info($module, $topic) { ...@@ -617,16 +637,14 @@ function advanced_help_get_topic_file_info($module, $topic) {
// Search paths: // Search paths:
$module_type = _advanced_help_get_module_type($module); $module_type = _advanced_help_get_module_type($module);
$paths = array( $paths = array(
// Allow theme override. // First see if a translation exists.
path_to_theme() . '/help',
// Translations.
drupal_get_path($module_type, $module) . "/translations/help/$language->language", drupal_get_path($module_type, $module) . "/translations/help/$language->language",
// In same directory as .inc file. // In same directory as .inc file.
$info['path'], $info['path'],
); );
foreach ($paths as $path) { foreach ($paths as $path) {
if (file_exists("./$path/$info[file]")) { if (file_exists("$path/$info[file]")) {
return array('path' => $path, 'file' => $info['file']); return array('path' => $path, 'file' => $info['file']);
} }
} }
...@@ -824,36 +842,43 @@ function advanced_help_get_settings() { ...@@ -824,36 +842,43 @@ function advanced_help_get_settings() {
function _advanced_help_parse_ini() { function _advanced_help_parse_ini() {
global $language; global $language;
static $ini = NULL; static $ini = NULL;
if (!isset($ini)) { if (!isset($ini)) {
$cache = cache_get('advanced_help_ini:' . $language->language); $cache = cache_get('advanced_help_ini:' . $language->language);
if ($cache) { if ($cache) {
$ini = $cache->data; $ini = $cache->data;
} }
} }
if (!isset($ini)) { if (!isset($ini)) {
// No cached list of topics - create it.
$ini = array('topics' => array(), 'settings' => array()); $ini = array('topics' => array(), 'settings' => array());
foreach (array_merge(module_list(), list_themes()) as $plugin) { foreach (array_merge(module_list(), list_themes()) as $plugin) {
$module = is_string($plugin) ? $plugin : $plugin->name; $module = is_string($plugin) ? $plugin : $plugin->name;
$module_path = drupal_get_path(is_string($plugin) ? 'module' : 'theme', $module); $module_path = drupal_get_path(is_string($plugin) ? 'module' : 'theme', $module);
$info = array();
// Parse ini-file if it exists
if (file_exists("$module_path/help/$module.help.ini")) { if (file_exists("$module_path/help/$module.help.ini")) {
$path = "$module_path/help"; $path_html = "$module_path/help";
$info = parse_ini_file("./$module_path/help/$module.help.ini", TRUE); $info = parse_ini_file("./$module_path/help/$module.help.ini", TRUE);
if (!$info) {
drupal_set_message(t('There is a syntax error in the default .ini-file. Unable to display topics.'), 'error');
} }
elseif (!file_exists("$module_path/help")) { }
else {
$info = array();
}
if (empty($info) || !empty($info['advanced help settings']['show readme'])) {
// Look for one or more README files. // Look for one or more README files.
$files = file_scan_directory("./$module_path", $files = file_scan_directory("./$module_path",
'/^(readme).*\.(txt|md)$/i', array('recurse' => FALSE)); '/^(readme).*\.(txt|md)$/i', array('recurse' => FALSE));
$path = "./$module_path"; $path_readme = "$module_path";
foreach ($files as $name => $fileinfo) { foreach ($files as $name => $fileinfo) {
$info[$fileinfo->filename] = array( $info[$fileinfo->filename] = array(
'line break' => TRUE, 'line break' => TRUE,
'readme file' => TRUE, 'readme file' => TRUE,
'file' => $fileinfo->filename, 'file' => $fileinfo->filename,
'title' => $fileinfo->name, 'title' => $fileinfo->name,
'weight' => -99,
); );
} }
} }
...@@ -863,6 +888,9 @@ function _advanced_help_parse_ini() { ...@@ -863,6 +888,9 @@ function _advanced_help_parse_ini() {
$translation = array(); $translation = array();
if (file_exists("$module_path/translations/help/$language->language/$module.help.ini")) { if (file_exists("$module_path/translations/help/$language->language/$module.help.ini")) {
$translation = parse_ini_file("$module_path/translations/help/$language->language/$module.help.ini", TRUE); $translation = parse_ini_file("$module_path/translations/help/$language->language/$module.help.ini", TRUE);
if (!$translation) {
drupal_set_message(t('There is a syntax error in the translated .ini-file.'), 'error');
}
} }
$ini['settings'][$module] = array(); $ini['settings'][$module] = array();
...@@ -895,9 +923,10 @@ function _advanced_help_parse_ini() { ...@@ -895,9 +923,10 @@ function _advanced_help_parse_ini() {
// Require extension. // Require extension.
'file' => isset($topic['readme file']) ? $file : $file . '.html', 'file' => isset($topic['readme file']) ? $file : $file . '.html',
// Not in .ini file. // Not in .ini file.
'path' => $path, 'path' => isset($topic['readme file']) ? $path_readme : $path_html,
'line break' => isset($topic['line break']) ? $topic['line break'] : (isset($ini['settings'][$module]['line break']) ? $ini['settings'][$module]['line break'] : FALSE), 'line break' => isset($topic['line break']) ? $topic['line break'] : (isset($ini['settings'][$module]['line break']) ? $ini['settings'][$module]['line break'] : FALSE),
'navigation' => isset($topic['navigation']) ? $topic['navigation'] : (isset($ini['settings'][$module]['navigation']) ? $ini['settings'][$module]['navigation'] : TRUE), 'navigation' => isset($topic['navigation']) ? $topic['navigation'] : (isset($ini['settings'][$module]['navigation']) ? $ini['settings'][$module]['navigation'] : TRUE),
'show readme' => isset($topic['show readme']) ? $topic['show readme'] : (isset($ini['settings'][$module]['show readme']) ? $ini['settings'][$module]['show readme'] : FALSE),
'css' => isset($topic['css']) ? $topic['css'] : (isset($ini['settings'][$module]['css']) ? $ini['settings'][$module]['css'] : NULL), 'css' => isset($topic['css']) ? $topic['css'] : (isset($ini['settings'][$module]['css']) ? $ini['settings'][$module]['css'] : NULL),
'readme file' => isset($topic['readme file']) ? $topic['readme file'] : FALSE, 'readme file' => isset($topic['readme file']) ? $topic['readme file'] : FALSE,
); );
......
[readme] [advanced help settings]
title = README show readme = TRUE
[introduction]
title = Introduction
weight = -11 weight = -11
[using-advanced-help] [using-advanced-help]
......
...@@ -35,19 +35,26 @@ use a more friendly name than appears in the project's .info file.</dd> ...@@ -35,19 +35,26 @@ use a more friendly name than appears in the project's .info file.</dd>
module/theme index. It overrides the <code>name</code> setting above, module/theme index. It overrides the <code>name</code> setting above,
as well as the project's name in its .info file.</dd> as well as the project's name in its .info file.</dd>
<dt><code>show readme</code> (FALSE)</dt>
<dd>For projects that comes with a set of HTML-files, the default is
to hide the project's <code>README</code>-file. Setting this TRUE will
show the README along with the HTML-files.</dd>
<dt><code>hide</code> (FALSE)</dt> <dt><code>hide</code> (FALSE)</dt>
<dd>This may be used to hide a module or theme in the module/theme <dd>This may be used to hide a module or theme in the module/theme
index. This is particularly useful for modules who insert their help index. This is particularly useful for modules who insert their help
files into the hierarchy of another module or theme, as might be done files into the hierarchy of another module or theme. By setting this
by modules that extend <strong>Views</strong> or derived themes that to TRUE the project will not appear as its own entry.</dd>
extend base themes like <strong>Zen</strong>. By setting this to TRUE
the project will not appear as its own entry.</dd>
</dl> </dl>
<p>Each section after that will correspond to a single help file for a <p>Each section after that will correspond to a single help file for a
single topic. It starts with the topic name in square brackets single topic. It starts with the topic machine name in square
(e.g. <code>[ini-file]</code>). The following settings may be set for brackets (e.g. <code>[introduction]</code>). The file containing the
each file/topic, with the default value (if any) in brackets.</p> documentation for that topic will have the same machine name with the
extension <code>html</code> (e.g. <code>introduction.html</code>) The
following settings may be set for each file/topic, with the default
value (if any) in brackets.</p>
<dl> <dl>
<dt><code>title</code></dt> <dt><code>title</code></dt>
...@@ -68,8 +75,8 @@ are sorted alphabetically.</dd> ...@@ -68,8 +75,8 @@ are sorted alphabetically.</dd>
<dt><code>parent</code></dt> <dt><code>parent</code></dt>
<dd>The topic ID to use in a hierarchy; children will be listed <dd>The topic ID to use in a hierarchy; children will be listed
beneath parents in the topic list, and will have the parent in their beneath parents in the topic list, and will have the parent in their
breadcrumb trail. You may parent this topic to a topic in another breadcrumb trail. You may parent this topic to a topic
module or theme by using <code>module%topic</code> in <em>another</em> module or theme by using <code>module%topic</code>
or <code>theme%topic</code> as the identifier, or <code>theme%topic</code> as the identifier,
where <code>module</code> or <code>theme</code> is the project's short where <code>module</code> or <code>theme</code> is the project's short
name. For example if parent is set to, '<code>views%display</code>', name. For example if parent is set to, '<code>views%display</code>',
...@@ -93,25 +100,5 @@ will override any .css file added by the global settings.</dd> ...@@ -93,25 +100,5 @@ will override any .css file added by the global settings.</dd>
<dd>The height in pixels of the popup window.</dd> <dd>The height in pixels of the popup window.</dd>
</dl> </dl>
<p>For example, here is a version of the <code>advanced_help.help.ini</code> file:</p> <p>Take a look at the .ini-file for this project to see an
example.</p>
<pre>
[readme]
title = README
weight = -11
[using-advanced-help]
title = Using advanced help
weight = -10
[translation]
title = Translating advanced help
[ini-file]
title = Help .ini file format
line break = FALSE
[why-advanced-help]
title = Why advanced help?
line break = TRUE
</pre>
<p>The <strong>Advanced help</strong> module provides a framework that
allows help texts to be viewed as integrated into a Drupal
website.</p>
<p>These help texts are stored in ordinary <code>.html</code>-files
that lives in the file system (as opposed to the database). These
files are distributed from the project Drupal.org repo in the same
package as the module or theme, and placed in a subdirectory named
<code>help</code> in the project or theme directory.</p>
<p>The help texts can be marked up with standard HTML. They will be
rendered using your site's theme, but you may provide custom css. If
there is a <code>README.md</code> or <code>README.txt</code> in the
package, the content of that file may be shown as well.</p>
<p>The help texts can be placed in an hierarchical book, allowing for
top-down navigation, or placed in popups that can be added to a page
with plain text links or themed icon links.</p>
<p>Cross-linking book-sections,using fragment identifiers, works as
one would expect.</p>
<p>The help texts may be made searchable, but are not so by default (see
<a href="&topic:advanced_help/using-advanced-help#search&">Using advanced help</a>
for details). If search is enabled, all help texts are fully
indexed. This means that the entire contents of the advanced help set
of pages can be searched for keywords.</p>
<p>Modules and themes can even insert help texts into another
project's hierarchy.</p>
<p>May be integrated into <code>hook_help()</code> using companion
module
<a href="https://www.drupal.org/project/advanced_help_hint"><strong>Advanced help hint</strong></a>.</p>
<h2 id="demo">Demonstrations</h2>
<p>The project comes with a small demo module named
<strong>Advanced help example</strong> to demonstrate how it works.
For an example of a project that makes extensive use of the advanced
help features, see the <strong>Views</strong> project.</p>
<p>For an example of translation of help text, see the
directory <code>translations/help/nb</code> in the <strong>Advanced
help example</strong> submodule. For translation instructions, see the
section named “<a href="&topic:advanced_help/translation&">Translating
advanced help</a>”.</p>
<h2 id="project-description">Synopsis</h2>
<p>The <strong>Advanced help</strong> module provides a framework that allows
module and theme developers integrate help texts in a Drupal site.</p>
<p>These help texts are stored in ordinary <code>.html</code>-files
that lives in the file system (as opposed to the database). These
files are distributed from the project Drupal.org repo in the same
package as the module or theme, and placed in a subdirectory named
<code>help</code> in the project or theme directory. This means that
the help texts can be easily kept in sync with the project they
provide help texts for, but also that read access to these files
are not managed by any content access restrictions imposed by Drupal.</p>
<p>The help texts can be marked up with standard HTML. They will be
rendered using your site's theme.</p>
<p>If the module or theme author does not make use of the
<em>Advanced help</em> HTML-framework, but if there is a
<code>README.md</code> or <code>README.txt</code> in the package,
the content of that file will be shown instead.</p>
<p>The help texts may appear in a popup or not as the project prefers.
By taking away access to view the popups, a site can hide popups from
users.</p>
<p>The help texts can be placed in a hierarchy, allowing for top down
navigation of help.</p>
<p>The help texts may be made searchable. If advanced help search is
enabled, all help texts are fully indexed. This means that the entire
contents of the advanced help set of pages can be searched for
keywords.</p>
<h2 id="use">Using the module</h2>
<p>When you enable the module, a new tab with the legend “Advanced
help” will show up under “Help”:
<div class="ta-center">
<img class="help-img-center" alt="ahelp_tab.png" src="&path&ahelp_tab.png" width="661" height="225" border="1" />
</div>
<p>By itself, this module doesn't do much. The <strong>Advanced
help</strong> assists other modules and themes in showing help texts.
Nothing will show up until you enable at least one other module that
makes use of the advanced help framework or comes with a file
named <code>README.md</code> or <code>README.txt</code>. However, it
comes with a small companion demo module named
<strong>Advanced help example</strong> to demonstrate how it works.
For more extensive example of use of the advanced help features, see
the <strong>Views</strong> project.</p>
<!--
<h2 id="project-recommended">Recommended modules</h2>
<ul>
<li><a href="https://www.drupal.org/project/markdown">Markdown filter</a>:<br>
When this module is enabled, display of any <code>README.md</code> the
module shows will be rendered with markdown.</li>
<li><a href="https://www.drupal.org/project/attributions">Attributions</a>:<br>
When this module is enabled, attributions of third party content used
by the project (i.e. some text from Wikipedia) will be available in an
attribution block and on an attribution page.</li>
</ul>
-->
<h2 id="support-status">Support status</h2>
<p>Reported bugs for the Drupal 7 branch will be fixed in a timely
manner. Bugs in the issue queue for the Drupal 6 branch will only be
fixed if accompanied with a patch, after the patch has been reviewed
and tested by the community. No Drupal 8 version is currently under
development. Post a message in
the <a href="https://www.drupal.org/node/1928218">issue queue</a> if
you're interested in managing a port of the project to to Drupal
8. Older versions are no longer supported.</p>
<p>Community support in the form of patches are very welcome for both
Drupal 6 and Drupal 7 versions, and will be given priority. For QA,
the project needs community support in the form of reviews of patches,
development versions and releases.</p>
<p>The primary goal of the module is to remain <strong>light-weight
and simple</strong>. This means that not all feature requests will be
implemented, even if they are a good idea. Feature requests
accompanied by patches are more likely to make it into a release.</p>
<p>The maintainer hopes that the community is willing to help out by
answering &amp; closing support requests.</p>
<!--
<h2 id="project-problems">Known problems</h2>
-->
<h2 id="project-maintainers">Credits</h2>
<ul>
<li><a href="https://www.drupal.org/u/merlinofchaos">merlinofchaos</a> (52 commits, original creator)</li>
<li><a href="https://www.drupal.org/u/redndahead">redndahead</a> (8 commits)</li>
<li><a href="https://www.drupal.org/u/dmitrig01">dmitrig01</a> (3 commits)</li>
<li><a href="https://www.drupal.org/u/amitgoyal">amitgoyal </a> (5 commits)</li>
<li><a href="https://www.drupal.org/u/gisle">gisle</a> (current maintainer, D7)</li>
<li><a href="https://www.drupal.org/u/gnuget">gnuget</a> (current maintainer, D8)</li>
</ul>
<p>The <strong>Advanced help</strong> module provides a framework that <p>The <strong>Advanced help</strong> module provides a framework that
allows module and theme developers integrate help texts in a Drupal allows module and theme developers integrate help texts in a Drupal
site. Although the <strong>Advanced help</strong> does not provide site.</p>
general help by itself, it provides a powerful and easy framework that
modules and themes may use to provide their own help.</p> <p>It provides a framework for creating and maintaing HTML help texts.
It may also be used to display a module's or
theme's <code>README</code>-file on the screen.</p>
<h2 id="ah_enable">Enabling the module</h2>
<p>When you enable the module, a new tab with the legend “Advanced
help” will show up under “Help”:
<div class="ta-center">
<img class="help-img-center" alt="ahelp_tab.png" src="&path&ahelp_tab.png" width="661" height="225" border="1" />
</div>
<p>Links to the help texts are under this tab.</p>
<h2 id="ah_crehlp">Creating help</h2>
<p>Modules and themes utilizing <strong>Advanced help</strong> should <p>Modules and themes utilizing <strong>Advanced help</strong> should
create a subdirectory named <code>help</code> inside their own main create a subdirectory named <code>help</code> inside their own main
...@@ -11,62 +26,78 @@ directory. Place the file ...@@ -11,62 +26,78 @@ directory. Place the file
formatted similar to the following example:</p> formatted similar to the following example:</p>
<pre> <pre>
[about-php] [advanced help settings]
title = About PHP navigation = FALSE
file = about-php show readme = FALSE
weight = -10
[history] [about-example]
title = History of PHP title = About the help example
parent = about-php weight = -11
[usage] [lorem]
title = Usage of PHP title = Lorem ipsum
weight = 1 weight = -10
[security]
title = Security of PHP
weight = 2
[syntax] [etiam]
title = PHP syntax title = Etiam ultricies
parent = usage parent = lorem
line break = TRUE
</pre> </pre>
<p>This file defines five help topics (inside the square brackets), and <p>This file defines some global settings as well as three help topics
some settings for them. (inside the square brackets), and some settings for them. See:
See: <a href="&topic:advanced_help/ini-file&">Advanced help .ini file format</a> for <a href="&topic:advanced_help/ini-file&">Advanced help .ini file
a list of defined settings.</p> format</a>” for a list of defined settings.</p>
<p>Characters <code>?{}|&~!()^"</code> should not be used anywhere in
the title as they have a special meaning, unless the the string is
quoted. An error message like the one below indicates that quotes
should be used:</p>
<p>All topics are addressed by the module or theme providing the <blockquote><p>Warning: syntax error, unexpected '(' in example.help.ini &hellip;</p></blockquote>
topic, and by the topic id. To produce a themed link to popup
about a topic, use the a format similar to the following example:</p>
<!-- D6 <h2 id="ah_lnkhlp">Linking to help</h2>
<pre>
$output = theme('advanced_help_topic', 'help_example', 'about-php'); <p>All topics are addressed by the module or theme providing the
$output .= '&nbsp;' . t('Click the help icon!'); topic, and by the topic id. To produce a themed link to popup about a
</pre> topic, there is a theme
--> function <code>theme_advanced_help_topic()</code> accepting three
named parameters passed in an array:</p>
<ol>
<li><code>'module'</code>: The machine name of the module that owns this help topic.</li>
<li><code>'topic'</code>: The identifier for the topic.</li>
<li><code>'type'</code>: The type of link to create:<ul>
<li>'<code>icon'</code> to display the question mark icon</li>
<li>'<code>title'</code> to display the topic's title</li>
<li>any other text to display the text. Wrap it in <code>t()</code> to make it translatable.</li>
</ul></li>
</ol>
<p>The following example shows how to link to a popup with the
topic <code>'about-example'</code> owned by the module
<code>'help_example'</code> using the question mark icon:</p>
<!-- D7 --> <!-- D7 -->
<pre> <pre>
// Create the question mark icon.
$output = theme('advanced_help_topic', array( $output = theme('advanced_help_topic', array(
'module' => 'help_example', 'module' => 'help_example',
'topic' => 'about-php', 'topic' => 'about-example',
'type' => 'icon',
)); ));
// Append some explanatory text.
$output .= '&nbsp;' . t('Click the help icon!'); $output .= '&nbsp;' . t('Click the help icon!');
</pre> </pre>
<p>This produces the following output:</p> <p>This produces the following output:</p>
<pre> <pre>
&lt;a class="advanced-help-link" title="About PHP" &lt;a class="advanced-help-link" title="About the help example"
onclick="var w=window.open(this.href, 'advanced_help_window', onclick="var w=window.open(this.href, 'advanced_help_window',
'width=500,height=500,scrollbars,resizable'); 'width=500,height=500,scrollbars,resizable');
w.focus(); return false;" w.focus(); return false;"
href="/help/help_example/about-php?popup=1"&gt; href="/help/help_example/about-example?popup=1"&gt;
&lt;span&gt;Help&lt;/span&gt; &lt;span&gt;Help&lt;/span&gt;
&lt;/a&gt; &lt;/a&gt;
Click the help icon! Click the help icon!
...@@ -79,12 +110,12 @@ $output .= '&nbsp;' . t('Click the help icon!'); ...@@ -79,12 +110,12 @@ $output .= '&nbsp;' . t('Click the help icon!');
<img class="help-img-center" alt="clickable icon" src="&path&click_icon.png" width="180" height="90" border="0" /> <img class="help-img-center" alt="clickable icon" src="&path&click_icon.png" width="180" height="90" border="0" />
</div> </div>
<p>Inside your help file, you may link to other help topics using this format:</p> <p>You may link to other help topics inside your HTML help file using
this format:</p>
<pre> <pre>
&lt;a href="&amp;topic:module/topic&amp;"&gt;topic&lt;/a&gt; &lt;a href="&amp;topic:module/topic&amp;"&gt;topic&lt;/a&gt;
</pre> </pre>
<p>This format will ensure the popup status remains consistent when
switching between links.</p>
<p>To reference items within the help directory, such as images you wish to embed within the help text, use:</p> <p>To reference items within the help directory, such as images you wish to embed within the help text, use:</p>
...@@ -93,7 +124,9 @@ switching between links.</p> ...@@ -93,7 +124,9 @@ switching between links.</p>
&lt;img src="&amp;trans_path&amp;example.png"/&gt; &lt;img src="&amp;trans_path&amp;example.png"/&gt;
</pre> </pre>
<p>The <code>trans_path</code> keyword refers to a translated version of the image in the translation directory and may be used it differs from the original.</p> <p>The <code>trans_path</code> keyword refers to a translated version
of the image in the translation directory and may be used if it
differs from the original.</p>
<p>To reference any normal path in the site, use:</p> <p>To reference any normal path in the site, use:</p>
<pre> <pre>
...@@ -107,21 +140,26 @@ This is currently still supported, but will be removed in a future ...@@ -107,21 +140,26 @@ This is currently still supported, but will be removed in a future
version. By adding the &amp;'s these tokens are now not limited version. By adding the &amp;'s these tokens are now not limited
to <code>href=""</code> and <code>src=""</code> parameters.</p> to <code>href=""</code> and <code>src=""</code> parameters.</p>
<h2 id="access-control">Access control</h2> <h2 id="access-control">Hiding help files</h2>
<p>When this module is installed, users with the <p>When this module is installed, users with the
<code>view advanced help index</code> <code>view advanced help index</code>
permission can access the advanced help index by going to permission can access the advanced help index by going to
<em>Administer &rarr; Advanced Help</em> <em>Administer » Advanced Help</em>
(<code>admin/advanced_help</code>). Additional permissions (<code>admin/advanced_help</code>). Additional permissions
<code>view advanced help topic</code> and <code>view advanced help topic</code> and
<code>view advanced help popup</code> <code>view advanced help popup</code> allows the user to click
enable users to access the actual help pages and popups.</p> trough to the actual help pages and popups.</p>
<p>By taking away thes permissions from a role, a site can “hide” the
direct access to these topics and popup. Note that this does not
restrict <em>access</em>, as the contents of an unprotected HTML-file
on a Drupal website can be viewed by anyone who know (or is able to
guess) its URL.</p>
<p>The help texts are stored as plain .html-files and can, unless
protected, be accessed by anyone who knows their URL. To protect <p>To protect these files, place the following four lines in a file
them, place the following four lines in a file named named <code>.htaccess</code> in project's <code>help</code> directory:</p>
<code>.htaccess</code> in project's <code>help</code> directory:</p>
<pre> <pre>
&lt;Files *\.html&gt; &lt;Files *\.html&gt;
...@@ -140,7 +178,7 @@ protection from direct access.</p> ...@@ -140,7 +178,7 @@ protection from direct access.</p>
<h2 id="search">Search</h2> <h2 id="search">Search</h2>
<p>To enable advanced help search, navigate to <p>To enable advanced help search, navigate to
<em>Administration Configuration Search and metadata Search settings</em>. <em>Administration » Configuration » Search and metadata » Search settings</em>.
Scroll down to <em>Active search modules</em> and tick the box to the Scroll down to <em>Active search modules</em> and tick the box to the
left of “Advanced help”. The search form will appear on the top of left of “Advanced help”. The search form will appear on the top of
the advanced help index pages.</p> the advanced help index pages.</p>
...@@ -148,5 +186,6 @@ the advanced help index pages.</p> ...@@ -148,5 +186,6 @@ the advanced help index pages.</p>
<p>If the core <strong>Search</strong> module is enabled, the contents <p>If the core <strong>Search</strong> module is enabled, the contents
of the advanced help framework will be indexed on cron. If you enable of the advanced help framework will be indexed on cron. If you enable
new modules or themes and wish to immediately index their help text, new modules or themes and wish to immediately index their help text,
navigate to <em>Administration Reports Status report</em> and navigate to <em>Administration » Reports » Status report</em> and
click the link “run cron manually”.</p> click the link “run cron manually”.</p>
The <strong>Advanced help</strong> framework was designed to replace the original Drupal help system, which has several flaws that make it hard to create new help, hard to maintain existing help, and particularly hard to access help. The <strong>Advanced help</strong> framework is designed to supplement the Drupal core help system: <code>hook_help()</code>. The goal is to provide a help framework where it is easy for maintainers of modules and themes to create and maintain rich help texts, and for users to access help on the screen.
The primary goal, then, is to increase the accessibility of help, meaning the ability of both the user and the help text author to access the needed tools to use, create, maintain and translate the help. Unlike the core help system, it allows for help-pages under the “Advanced help”-tab to be structured like an hierarchical book. It also allows pop-ups that provide context sensitive help on demand. By allowing help to be available on demand, the system conforms more naturally to how most people work.
This system is completely separate from Drupal's <code>hook_help()</code>. In Drupal 6 and 7, it actually co-exists with it; in the future, it is hoped that it will completely replace it allowing <code>hook_help()</code> to be deprecated and removed.
Messages added to the top of a page are not really “help”. Often these messages are an introduction to a form or a short blurb telling a user what to do with a particular page. The problem is, these messages are always there, they are easily ignored, and they come before the actual page. In general, when users are learning, they want to see the page first, then ask questions. The reverse order is much less conducive to actually teaching a user how to use something. By allowing help to be available on request, the system conforms more naturally to how most people work.
<h2>Advanced help is organized by topic</h2> <h2>Advanced help is organized by topic</h2>
With the <code>hook_help()</code> method, help text is organized by URL path. This is fine if you have help text describing how to use a particular page or what a particular page does, but ultimately is limiting because manuals and documentation are usually grouped by topic, and those topics are determined by the material itself.
<strong>Advanced help</strong> allows the documentation author to organize topics as he or she sees fit; the only restriction, really, is that each individual chunk of text needs to stand on its own as a discrete topic. With the <code>hook_help()</code> method, help text is organized by URL path. This is fine if you have help text describing how to use a particular project or what a particular project does, but because manuals and documentation are usually grouped by topic, and those topics are determined by the material itself, this format is sometimes limiting.
What's more, modules and themes can insert their topics into another's hierarchy. This would allow the Drupal core to create a task based help navigation system which allows modules and themes to insert topics into that navigation fluidly. This allows modules and themes to continue to keep their systems separate, yet integrate into the main system. <strong>Advanced help</strong> allows the documentation author to organize topics as he or she sees fit. The only restriction is that each individual chunk of text needs to stand on its own as a discrete topic.
<h2>Advanced help topics are processed HTML in their own files</h2> Modules and themes can insert their topics into another project's hierarchy, as might be done by projects that extend <strong>Views</strong> or derived themes that extend base themes like <strong>Zen</strong>. Please see the entries for <code>hide</code> and <code>parent</code> in the section “<a href="&topic:advanced_help/ini-file&">Advanced help .ini file format</a>” for details.
This separation makes it easy to find and modify. Currently, everything is lumped together in <code>hook_help()</code> in PHP strings that are run through <code>t()</code>, and there is a fair amount of PHP code necessary in this system that actually gets in the way of writing good, explanatory text.
In fact, requiring a documentation author to understand PHP at all is a detriment. The idea that documentation writers need to have PHP development as a skill seriously reduces the number of available contributors. HTML, on the other hand, is a much more common skill, is relatively easy to learn, and the amount of HTML needed to write documentation is only a little bit more than the HTML used in forum posts. <h2>Advanced help topics are processed HTML in their own files</h2>
Another benefit from not using PHP is that the files themselves are safe. They are filtered to escape malicious script code that could take over the server or do worse things. This means that these files can be used relatively easily on Drupal.org itself. It also means that descriptions of the project pulled from the project's help pages or README.txt or README.md can be made on the project's Drupal.org without the need to download the module or theme to look at the contents of these files. This also simplifies maintenance, as the files can be corrected easily by patches, which are updated by the maintainer and pushed to git. This separation of documentation from code makes it easy to find and modify help text. Currently, everything is lumped together in <code>hook_help()</code> in PHP strings that are run through <code>t()</code>, and there is a fair amount of PHP code necessary in this system that actually gets in the way of writing good, explanatory text.
By moving all docymentation into help files, we could, if we wanted, package the Drupal.org handbooks, or a subset of them, directly into a Drupal distribution, or a Drupal add-on, so that Drupal administrators can have Drupal help without needing to visit Drupal.org. This can be valuable in locked down corporate environments and on planes. But more importantly, the handbooks can be made version aware much more easily than the current method on Drupal.org. In fact, requiring a documentation author to understand PHP at all is a detriment. The idea that documentation writers need to have PHP development as a skill seriously reduces the number of available contributors. HTML, on the other hand, is a much more common skill, is relatively easy to learn, and the amount of HTML needed to write documentation is only a little bit more than the HTML used in forum posts.
The downside to this method is that these books can't easily be made dynamic. Though the use of alter hooks could allow a module or theme to make modifications to the help as needed, doing this could make the help files less useful when you take them out of context. Another benefit from not using PHP is that the HTML-files themselves are safe. They are filtered to escape malicious script code that could take over the server or do worse things.
<h2>Advanced help files are translated as a file</h2> <h2>Advanced help files are translated as a file</h2>
It is actually not easy to translate documents as strings, particularly when the language being used is very much unlike English. In fact, when translating a document, the organization of the sentences may change drastically. It is also a burden on the CPU to do this, as you are indexing on very long strings. It is actually not easy to translate documents as strings, particularly when the language being used is very much unlike English. In fact, when translating a document, the organization of the sentences may change drastically. It is also a burden on the CPU to do this, as you are indexing on very long strings.
...@@ -30,15 +24,17 @@ It is actually not easy to translate documents as strings, particularly when the ...@@ -30,15 +24,17 @@ It is actually not easy to translate documents as strings, particularly when the
Translators have a much better time translating a document as a unit, because of the presence of the entire context. Translators have a much better time translating a document as a unit, because of the presence of the entire context.
<h2>Advanced help has its own navigation system</h2> <h2>Advanced help has its own navigation system</h2>
By making use of a navigation system specified in a .ini file (which is not PHP code and therefore safe to use), the help can be structured like a book, which is typical of online manuals. This is familiar to users, can be organized (and re-organized) and allows a module or theme to include significantly richer text without burdening the PHP code with having its help loaded unnecessarily. By making use of a navigation system specified in a .ini file (which is not PHP code and therefore safe to use), the help can be structured like a book, which is typical of online manuals. This is familiar to users, can be organized (and re-organized) and allows a module or theme to include significantly richer text without burdening the PHP code with having its help loaded unnecessarily.
This book can be navigated hierarchically as well, making it easy to keep related topics together. This book can be navigated hierarchically as well, making it easy to keep related topics together.
<h2>Advanced help is indexed by the search engine</h2> <h2>Advanced help is indexed by the search engine</h2>
An important goal of this system was to add searchability to the help. By being able to enter keywords into the search box and find relevant topics, we come up with a system that resembles the kind of help that comes with many operating systems. This is very valuable when searching through manuals trying to find out how to do a particular thing. An important goal of this system was to add searchability to the help. By being able to enter keywords into the search box and find relevant topics, we come up with a system that resembles the kind of help that comes with many operating systems. This is very valuable when searching through manuals trying to find out how to do a particular thing.
This search is specific to the help, meaning that the help will not be mixed in with the global node search. This can be considered both an advantage and a disadvantage. For the most part, this help system is meant to provide help to site administrators, and content searches should not find it. The disadvantage, of course, is when you want to use it for end user help, you will not be able to. This search is specific to the help, meaning that the help will not be mixed in with the global node search. This can be considered both an advantage and a disadvantage. For the most part, this help system is meant to provide help to site administrators, and content searches should not find it. The disadvantage, of course, is when you want to use it for end user help, you will not be able to.
<h2>Inline help can be brought in via popups</h2> <h2>Inline help can be brought in via popups</h2>
In addition to the manual-like hierarchical navigation, <strong>Advanced help</strong> can also provide context-sensitive additional help through a popup. While popups are controversial, the argument for using them is that when getting help while on a form, <i>a popup will not throw away a user's data.</i> Browsers are not very friendly to input forms if they are not submitted, and navigating away from the form can be dangerous. There are various other solutions to this problem, but each one has a drawback. The drawbacks to popups are well known, but mostly it is the irritation of having new windows. When getting help, though, a popup is usually invited. Help should not interfere with what the operation the user is trying to complete. It differs greatly from the uninvited popup, which are usually ads or popups meant to prevent users from navigating away from a site.
Popups can be added to a page with plain text links or themed icon links. In addition to the manual-like hierarchical navigation, <strong>Advanced help</strong> can also provide context-sensitive additional help through a popup. While popups are controversial, the argument for using them is that when getting help while on a form, <em>a popup will not throw away a user's data.</em> Browsers are not very friendly to input forms if they are not submitted, and navigating away from the form can be dangerous. There are various other solutions to this problem, but each one has a drawback. The drawbacks to popups are well known, but mostly it is the irritation of having new windows. When getting help, though, a popup is usually invited. Help should not interfere with what the operation the user is trying to complete. It differs greatly from the uninvited popup, which are usually ads or popups meant to prevent users from navigating away from a site.
# wikipedia_adaption.
help/:
type: asset
approved: https://www.drupal.org/node/2460769
title: About PHP, History of PHP, Usage of PHP, PHP Syntax, Security of PHP
rights: http://creativecommons.org/licenses/by-sa/3.0/
originalTitle: PHP (Wikipedia)
originalAttributionText: multiple Wikipedia contributors
originalAttributionUrl: http://en.wikipedia.org/w/index.php?title=PHP&action=history
source: http://en.wikipedia.org/wiki/PHP
orgiginalLicense: CC BY-SA 3.0
orgiginalRights: http://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License
weight: -1
path: help_example
# lerdorf image
help/180px-Lerdorf.jpg:
type: asset
approved: https://www.drupal.org/node/2460769
attributionText: Jud Dagnall
source: http://en.wikipedia.org/wiki/File:Lerdorf.jpg
title: Rasmus Lerdorf
license: CC BY-SA 3.0
rights: http://creativecommons.org/licenses/by-sa/3.0/deed.en
path: 'help_example\/history'
# gutmans image
help/180px-Andi_Gutmans_1.jpg:
type: asset
approved: https://www.drupal.org/node/2460769
attributionText: Jim Winstead
attributionUrl: "https://www.flickr.com/people/81342178@N00"
source: http://en.wikipedia.org/wiki/File:Andi_Gutmans_1.jpg
title: Andi Gutmans
license: CC BY 2.0
rights: http://creativecommons.org/licenses/by/2.0/deed.en
path: 'help_example\/history'
CONTENTS OF THIS FILE
---------------------
* Introduction
* Requirements
* Installation
* Configuration
Introduction
------------
This is a simple example demonstrating how to use Advanced help.
Requirements
------------
This module required Advanced help to be installed.
Installation
------------
Install the module as you would normally install a contributed Drupal
module. See
https://drupal.org/documentation/install/modules-themes/modules-7 for
further information.
Configuration and use
---------------------
There is nothing to configure.
When you enable the module, the item “Example help” will show up in
the black administration toolbar. Click on the link, to see an example
of a help popup.
When you navigate to *Help » Advanced help » Advanced help example »
About help example*, you may see the help files as an hierarchical
manual.
When you disable the module, this goes away.
help_example/help/180px-Andi_Gutmans_1.jpg

10.7 KiB

help_example/help/180px-Lerdorf.jpg

14.2 KiB

<p>This is an example of an help page created using the
<strong>Advanced help</strong> framework. If you have the appropriate
permissions, you may view the contents of this and other HTML help
files. To view it as an hierarchical manual or book, you navigate to
<em>Help » Advanced help » Advanced help example » About help example</em>.
To view it as a popup, click on <em>Example help</em> in the black
administrative toolbar and click on the question mark icon.</p>
<p>To try out the search features, first enable advanced help search,
then run cron to index the help pages.</p>
<p>You may also want to read up on <a href="&topic:help_example/lorem&">Lorem ipsum</a>.</p>
<ol>
<li><code>topic</code>: &topic:help_example/lorem&</li>
<li><code>path</code>: &path&</li>
<li><code>trans_path</code>: &trans_path&</li>
</ol>
<p><b>PHP</b> (<i>PHP: Hypertext Preprocessor</i>) is a computer <a href="http://en.wikipedia.org/wiki/Scripting_language" title="Scripting language">scripting language</a>, originally designed for producing <a href="http://en.wikipedia.org/wiki/Dynamic_web_page" title="Dynamic web page">dynamic web pages</a>. It is mainly used in <a href="http://en.wikipedia.org/wiki/Server-side_scripting" title="Server-side scripting">server-side scripting</a>, but can be used from a <a href="http://en.wikipedia.org/wiki/Command_line_interface"title="Command line interface">command line interface</a> or in <a href="http://en.wikipedia.org/wiki/Standalone" title="Standalone">standalone</a> <a href="http://en.wikipedia.org/wiki/Graphical_user_interface" title="Graphical user interface">graphical applications</a>.</p>
<p>While PHP was originally created by <a
href="http://en.wikipedia.org/wiki/Rasmus_Lerdorf" title="Rasmus
Lerdorf">Rasmus Lerdorf</a> in 1994, the main implementation of PHP is
now produced by The PHP Group and serves as the <a
href="http://en.wikipedia.org/wiki/De_facto_standard" title="De facto
standard"><i>de facto</i> standard</a> for PHP as there is
no <a
href="http://en.wikipedia.org/wiki/Formal_specification" title="Formal
specification">formal specification</a>. Released under the <a
href="http://en.wikipedia.org/wiki/PHP_License" title="PHP
License">PHP License</a>, the <a
href="http://en.wikipedia.org/wiki/Free_Software_Foundation"
title="Free Software Foundation">Free Software Foundation</a>
considers it to be <a
href="http://en.wikipedia.org/wiki/Free_software" title="Free
software">free software</a>.</p>
<p>PHP is a widely-used general-purpose scripting language that is
especially suited for <a
href="http://en.wikipedia.org/wiki/Web_development" title="Web
development">web development</a> and can be embedded
into <a href="http://en.wikipedia.org/wiki/HTML"
title="HTML">HTML</a>. It generally runs on a <a
href="http://en.wikipedia.org/wiki/Web_server" title="Web server">web
server</a>, taking PHP code as its input and
creating <a
href="http://en.wikipedia.org/wiki/Web_page" title="Web page">web
pages</a> as output. It can be deployed on most web servers and on
almost every <a
href="http://en.wikipedia.org/wiki/Operating_system" title="Operating
system">operating system</a> and <a
href="http://en.wikipedia.org/wiki/Platform_%28computing%29"
class="mw-redirect" title="Platform (computing)">platform</a> free of
charge. PHP is installed on more than 20 million
websites and 1 million <a
href="http://en.wikipedia.org/wiki/Server_%28computing%29"
title="Server (computing)">servers</a>, although the number of
websites with PHP <a
href="http://en.wikipedia.org/wiki/Installation_%28computer_programs%29"
title="Installation (computer programs)">installed</a> has declined
since August 2005.
It is also the most popular <a
href="http://en.wikipedia.org/wiki/Apache_HTTP_Server" title="Apache
HTTP Server">Apache</a> module among computers using Apache as a web
server.
The most recent major release of PHP was version 5.2.5
on <a href="http://en.wikipedia.org/wiki/November_8"
title="November 8">November 8</a>, <a
href="http://en.wikipedia.org/wiki/2007"
title="2007">2007</a>.</p>
<p class="attribution">This excerpt is adapted from <a href="http://en.wikipedia.org/wiki/PHP">Wikipedia: PHP</a>. It is used here under a <a href="http://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License">Creative Commons BY-SA 3.0</a> license.</p>
Etiam ultricies dolor enim, vel tincidunt est dictum vel. Curabitur porttitor ex nibh, id feugiat sapien ornare eu. Nulla id efficitur mi. Mauris vel suscipit ex. Sed odio turpis, consequat a dictum et, consectetur ac tortor. Ut ut erat ut justo suscipit porta tincidunt tempus ipsum. Sed rutrum, magna sit amet interdum pharetra, erat enim feugiat nibh, sit amet porttitor tortor erat sit amet justo.
Sed sit amet orci congue, laoreet odio non, sodales massa. Vestibulum mattis, odio eu gravida semper, nulla ex mattis dolor, sit amet hendrerit eros risus eget neque. Aliquam commodo, tortor at pellentesque venenatis, turpis nisl placerat est, et lobortis nisl justo et elit. Morbi dapibus urna tellus, sed placerat enim rhoncus sit amet.
Mauris sit amet ante vel mi ullamcorper dapibus. Pellentesque ipsum est, molestie at pellentesque eu, commodo eget lacus. Nulla a volutpat augue, ut finibus dui. Suspendisse efficitur ligula vestibulum varius facilisis.
[about-php] [advanced help settings]
title = About PHP navigation = FALSE
weight = -10 show readme = FALSE
[history]
title = History of PHP
parent = about-php
[usage] [about-example]
title = Usage of PHP title = About the help example
weight = 1 weight = -11
[security] [lorem]
title = Security of PHP title = Lorem ipsum
weight = 2 weight = -10
[syntax] [etiam]
title = PHP syntax title = Etiam ultricies
parent = usage parent = lorem
\ No newline at end of file line break = TRUE
<div class="help-box help-left">
<a href="http://en.wikipedia.org/wiki/Image:Lerdorf.jpg" class="image" title="Rasmus Lerdorf, who wrote the original Common Gateway Interface binaries"><img alt="Rasmus Lerdorf, who wrote the original Common Gateway Interface binaries" src="&path&180px-Lerdorf.jpg" width="180" height="270" border="0" /></a>
<div><a href="http://en.wikipedia.org/wiki/Rasmus_Lerdorf" title="Rasmus Lerdorf">Rasmus Lerdorf</a>, who wrote the original <a href="http://en.wikipedia.org/wiki/Common_Gateway_Interface" title="Common Gateway Interface">Common Gateway Interface</a> binaries.</div>
</div>
<p>PHP, standing for Personal Home Page, began as a set of <a href="http://en.wikipedia.org/wiki/Common_Gateway_Interface" title="Common Gateway Interface">Common Gateway Interface</a> <a href="http://en.wikipedia.org/wiki/Binary_file" title="Binary file">binaries</a> written in the <a href="http://en.wikipedia.org/wiki/C_programming_language" class="mw-redirect" title="C programming language">C programming language</a> in 1994 by the <a href="http://en.wikipedia.org/wiki/Danish_people" title="Danish people">Danish</a>/<a href="http://en.wikipedia.org/wiki/Greenland" title="Greenland">Greenlandic</a> programmer <a href="http://en.wikipedia.org/wiki/Rasmus_Lerdorf" title="Rasmus Lerdorf">Rasmus Lerdorf</a>. Lerdorf initially created these Personal Home Page Tools to replace a small set of <a href="http://en.wikipedia.org/wiki/Perl" title="Perl">Perl</a> scripts he had been using to maintain his <a href="http://en.wikipedia.org/wiki/Personal_homepage" class="mw-redirect" title="Personal homepage">personal homepage</a>. The tools were originally created to perform tasks such as displaying his <a href="http://en.wikipedia.org/wiki/R%C3%A9sum%C3%A9" title="Résumé">résumé</a> and recording how much <a href="http://en.wikipedia.org/wiki/Web_traffic" title="Web traffic">traffic</a> his page was receiving. He combined these binaries with his Form Interpreter to create PHP/FI, which had more functionality. It included a larger <a href="http://en.wikipedia.org/wiki/C_%28programming_language%29" title="C (programming language)">C implementation</a> which could communicate with <a href="http://en.wikipedia.org/wiki/Database" title="Database">databases</a> and helped build simple, dynamic <a href="http://en.wikipedia.org/wiki/Web_application" title="Web application">web applications</a>. He released PHP publicly on <a href="http://en.wikipedia.org/wiki/June_8" title="June 8">June 8</a>, <a href="http://en.wikipedia.org/wiki/1995" title="1995">1995</a> to speed up the finding of <a href="http://en.wikipedia.org/wiki/Software_bug" title="Software bug">bugs</a> and improving the code. This release was named PHP version 2, and already had basic functionality that PHP has today. This includes Perl-like variables, form handling, and the ability to embed HTML. The syntax was similar to Perl but was more limited, simpler, and less consistent.</p>
<div class="help-box help-right">
<a href="http://en.wikipedia.org/wiki/Image:Andi_Gutmans_1.jpg" class="image" title="Andi Gutmans, who, along with Zeev Suraski, rewrote the parser that formed PHP 3"><img alt="Andi Gutmans, who, along with Zeev Suraski, rewrote the parser that formed PHP 3" src="&path&180px-Andi_Gutmans_1.jpg" width="180" height="244" border="0" class="thumbimage" /></a>
<div class="help-leftalign"><a href="http://en.wikipedia.org/wiki/Andi_Gutmans" title="Andi Gutmans">Andi Gutmans</a>, who, along with <a href="http://en.wikipedia.org/wiki/Zeev_Suraski" title="Zeev Suraski">Zeev Suraski</a>, rewrote the <a href="http://en.wikipedia.org/wiki/Parsing#Parser" title="Parser">parser</a> that formed PHP&nbsp;3.</div>
</div>
<p><a href="http://en.wikipedia.org/wiki/Zeev_Suraski" title="Zeev Suraski">Zeev Suraski</a> and <a href="http://en.wikipedia.org/wiki/Andi_Gutmans" title="Andi Gutmans">Andi Gutmans</a>, two <a href="http://en.wikipedia.org/wiki/Israelis" title="Israelis">Israeli</a> developers at the <a href="http://en.wikipedia.org/wiki/Technion_IIT" class="mw-redirect" title="Technion IIT">Technion IIT</a>, rewrote the <a href="http://en.wikipedia.org/wiki/Parsing#Parser title="Parser">parser</a> in 1997 and formed the base of PHP 3, changing the language's name to the <a href="http://en.wikipedia.org/wiki/Recursive_initialism" class="mw-redirect" title="Recursive initialism">recursive initialism</a> <i>PHP: Hypertext Preprocessor</i>. The development team officially released PHP/FI 2 in November 1997 after months of <a href="http://en.wikipedia.org/wiki/Development_stage#beta" class="mw-redirect" title="Development stage">beta</a> testing. Afterwards, public testing of PHP 3 began, and the official launch came in June 1998. Suraski and Gutmans then started a new <a href="http://en.wikipedia.org/wiki/Rewrite_%28programming%29" title="Rewrite (programming)">rewrite</a> of PHP's core, producing the <a href="http://en.wikipedia.org/wiki/Zend_Engine" title="Zend Engine">Zend Engine</a> in 1999. They also founded <a href="http://en.wikipedia.org/wiki/Zend_Technologies" title="Zend Technologies">Zend Technologies</a> in <a href="http://en.wikipedia.org/wiki/Ramat_Gan" title="Ramat Gan">Ramat Gan</a>, Israel, which manages the development of PHP.</p>
<p>On <a href="http://en.wikipedia.org/wiki/May_22" title="May 22">May 22</a>, <a href="http://en.wikipedia.org/wiki/2000" title="2000">2000</a>, PHP 4, powered by the Zend Engine 1.0, was released. On <a href="http://en.wikipedia.org/wiki/July_13" title="July 13">July 13</a>, <a href="http://en.wikipedia.org/wiki/2004" title="2004">2004</a>, PHP 5 was released and is powered by the new Zend Engine II. PHP 5 included new features such as improved support for <a href="http://en.wikipedia.org/wiki/Object-oriented_programming" title="Object-oriented programming">object-oriented programming</a>, the PHP Data Objects extension (which defines a lightweight and consistent interface for accessing databases), and numerous performance enhancements. The most recent update released by The PHP Group is for the older PHP version 4 code branch. As of January 2008, this branch is up to version 4.4.8. PHP 4 will be supported by security updates until <a href="http://en.wikipedia.org/wiki/August_8" title="August 8">August 8</a>, <a href="http://en.wikipedia.org/wiki/2008" title="2008">2008</a>.</p>
<p>PHP 5 is the only stable version still being developed. <a href="http://en.wikipedia.org/wiki/Late_static_binding" class="mw-redirect" title="Late static binding">Late static binding</a> has been missing from PHP and will be added in version 5.3. Development on PHP 4 ceased at the end of 2007, except for the critical security updates for PHP 4 already mentioned. PHP 6 is now under development and major changes include the removal of <code>register_globals</code>, <a href="http://en.wikipedia.org/wiki/Magic_quotes" title="Magic quotes">magic quotes</a>, and <a href="http://en.wikipedia.org/wiki/Safe_mode#Application_software_safe_mode" title="Safe mode">safe mode</a>. PHP does not have complete native support for <a href="http://en.wikipedia.org/Unicode" title="Unicode">Unicode</a> or multibyte strings; unicode support will be added in PHP 6. Many high profile open source projects ceased to support PHP 4 in new code as of <a href="http://en.wikipedia.org/wiki/February_5" title="February 5">February 5</a>, <a href="http://en.wikipedia.org/wiki/2008" title="2008">2008</a>, due to the GoPHP5 initiative, provided by a consortium of PHP developers promoting the transition from PHP 4 to PHP 5.</p>
<p class="attribution">This excerpt is adapted from <a href="http://en.wikipedia.org/wiki/PHP#History">Wikipedia: PHP - history</a>. It is used here under a <a href="http://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License">Creative Commons BY-SA 3.0</a> license.
Picture of Rasmus <a href="http://en.wikipedia.org/wiki/File:Lerdorf.jpg" title="Link to work">Lerdorf</a> by Jud Dagnall, available under <a href="http://creativecommons.org/licenses/by-sa/3.0/deed.en" title="Link to license">Creative Commons BY-SA 3.0</a>.
Picture of <a href="http://en.wikipedia.org/wiki/File:Andi_Gutmans_1.jpg" title="Link to work">Andi Gutmans</a> by <a href="https://www.flickr.com/people/81342178@N00" title="Link to author">Jim Winstead</a>, available under <a href="http://creativecommons.org/licenses/by/2.0/deed.en" title="Link to license">Creative Commons BY 2.0</a>.</p>
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi eget
dolor ligula. Suspendisse sollicitudin purus eget erat eleifend
faucibus. Mauris urna quam, tincidunt ut varius ac, fermentum
fermentum urna. Suspendisse potenti.</p>
<p>Donec ac sapien et metus rutrum scelerisque posuere eu
augue. Vivamus libero ipsum, imperdiet sed sollicitudin ut, suscipit
volutpat sapien. Nullam at massa non odio sodales pretium. In hac
habitasse platea dictumst. Nam accumsan suscipit ultrices. Fusce nec
dui auctor nisl pellentesque pellentesque. Fusce consequat lacus quis
tincidunt commodo. In mattis enim nec lorem blandit eleifend. In
semper, ante eget gravida porttitor, eros mauris pharetra massa, et
accumsan risus purus non arcu.</p>
<p>PHP is a popular target of <a href="http://en.wikipedia.org/wiki/Hacker" title="Hacker">hackers</a> who exploit vulnerable applications written in PHP. Software vulnerabilities related to PHP are identified among the <a href="http://en.wikipedia.org/wiki/Common_Vulnerabilities_and_Exposures" title="Common Vulnerabilities and Exposures">CVE (Common Vulnerabilities and Exposures)</a> records, available from the <a href="http://en.wikipedia.org/wiki/National_Vulnerability_Database" title="National Vulnerability Database">National Vulnerability Database</a>. The proportion of vulnerabilities related to PHP, out of the total of all common vulnerabilities, amounted to: 12% in 2003, 20% in 2004, 28% in 2005, 43% in 2006, 36% in 2007, and 33.8% for the first quarter of 2008. More than a quarter of all software vulnerabilities listed in this database are related to PHP, and more than a third of vulnerabilities listed recently. Most of these vulnerabilities can be exploited remotely, that is without being logged on the computer hosting the vulnerable application. Such exploitation is made possible due to poor programming habits, such as failing to check data before entering it into a database, and features of the language such as <code>register_globals</code>, which is now deprecated. These result in <a href="http://en.wikipedia.org/wiki/Code_injection" title="Code injection">code injection</a>, <a href="http://en.wikipedia.org/wiki/Cross-site_scripting" title="Cross-site scripting">cross-site scripting</a> and other <a href="http://en.wikipedia.org/wiki/Application_security" title="Application security">application security</a> issues. It's important to note that none of these attacks are exclusive to PHP and all are avoidable by following proper coding techniques and principles.</p>
<p class="attribution">This excerpt is adapted from <a href="http://en.wikipedia.org/wiki/PHP#Security">Wikipedia: PHP - security</a>. It is used here under a <a href="http://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License">Creative Commons BY-SA 3.0</a> license.</p>
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment