HTML help integration for the advanced help module
dbeall - October 21, 2009 - 23:38
| Project: | Boost |
| Version: | 6.x-1.x-dev |
| Component: | Documentation |
| Category: | task |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | closed |
Description
After checking into this a little but, we should have a nice html formatted help page for the people using the advanced _help module.
I will work up a sample to have a look at...
#1
Since this is html, post it long form..
This is a first run,
there are some additional things to consider, such as the module has already been installed..
----------------------------
BOOST MODULE FOR DRUPAL 6.x
HELP CONTENTS & MENU
DESCRIPTION
This module provides static page caching for Drupal 6.x websites.
It provides a significant performance increase as well as
scalability for sites that receive mostly anonymous traffic.
Web pages load very fast from the cache instead of waiting on
PHP and Drupal to serve them from the database. If the page is
not found in the cache, then the request is passed to Drupal.
The built-in crawler makes sure expired content is quickly
regenerated to insure fast page loading at all times.
• The guy that is writing this could brag about Boost,
but he will let you do that part. Enjoy!
Back to top
FEATURES
• This is a partial list, because it could take the whole page.
• Fast page serving for anonymous visitors to your Drupal website.
• Reduces web server load and increases your site's scalability.
• On-demand page caching (static file created after first page request).
• Uses cron run to trigger cleaning of cached files.
• Built in crawler to automatically regenerate cached files.
• Adjustable cache lifetimes for different parts of the website.
• Supports HTML, XML, CSS, JavaScript, JSON/AJAX.
• Injects HTML comment to provide easy verification of Boost.
• Supports shared, VPS and dedicated hosting.
• Supports sub-directory Installations.
• Full support for multi-site Drupal installations.
Back to top
REQUIREMENTS
Boost is designed for Drupal 6.x served by Apache on any platform.
Drupal's clean URLs MUST be enabled and working properly.
If the cached files and pages must be cleared at their expired time,
the cron run for Drupal must be correctly setup to execute more often than,
or as often as the cache lifetime you specify in the settings.
Since the static page caching is implemented with mod_rewrite directives,
Apache version 1.3 or 2.x with mod_rewrite enabled is required (if Drupal's
clean URLs work for you, you're fine; if not, get them working first).
Other web servers, such as Lighttpd, are NOT officially supported at present.
• Lighttpd • Nginx
Back to top
RECOMMENDED MODULES
Path (Drupal Core)
Global Redirect
Transliteration
Pathauto
Token
Poormanscron -dev if cron configuration is not available on your server.
If enabled [x] Clear all cached pages referenced via CCK with a node...
The Node Referrer module is recommended.
Back to top
INSTALLATION
1. Goto: [Administer > Site configuration > Clean URLs] and ensure that
Drupal's clean URLs are enabled and working correctly on your site.
2. Unzip and upload the module folder (as is) to the sites/all/modules
folder in your Drupal installation directory.
3. Goto: [Administer > Site building > Modules] and enable the Boost
module. You will find it in the section labeled "Caching".
4. Goto: [Administer > Site configuration > Performance > Boost settings]
Specify the cache directory, which should be something like
cache/normal/www.example.com (keeping the default directory is recommended)
and must be writeable by the web server: you may need to create the
directory, and set the permissions so it is writeable.
5. On the [Administer > Site configuration > Performance > Boost settings]
page is the Default minimum cache lifetime setting. As cached pages are
created, they are given an expire by date and time, which is the current
date and time plus the minimum cache lifetime. These dates and times are
checked on each cron run; and if a page is expired, the cache is cleared,
and a new cached version will be created the next time the page is
called upon by an anonymous user (including bots). The page will be
regenerated by the Boost crawler if enabled on the Boost settings page.
6. IMPORTANT:
--- This step is easy and required for Boost to work! ---
Back up the original .htaccess file from your Drupal installation directory
for safe keeping. Copy the custom generated htaccess rule from
[Administer > Site configuration > Performance > htaccess rules generation]
page and paste the rules into the Drupal htaccess file as shown below.
# RewriteBase /
-------paste the rules right here--------
# Rewrite URLs of the form 'x' to the form 'index.php?q=x'.
In the boost/htaccess/ folder, the default.txt file shows you
the exact placement of the rules, in case your not sure.
The module package has 3 htaccess templates included in the Boost/htaccess
folder (boosted1.txt, boosted2.txt and default.txt). These templates may
be helpful in some cases and are good for reference. For the technically
inclined, the difference between the two .htaccess templates is due
to boosted1.txt relying on SERVER_NAME versus boosted2.txt using HTTP_HOST.
There are valid use cases for both in more advanced multi-site installations.
7. Goto: [Administer > Site configuration > Performance]
Check and set the Drupal cache settings as desired.
Back to top
SYSTEM CHECK AND VERIFY FUNCTIONS
1. Log out from Drupal (or use another browser) to browse around your site
as the anonymous user. Ensure that static files are indeed being
generated into the Boost cache directory you specified above (#4); and if
you opt to use gzip, likewise check gzipped files are being generated in
the directory you specified for this.
The Administer > Performance > Boost settings page shows how many pages
are cached by Boost.
2. Check the Drupal status page [Administer > Reports > Status report]
for any errors or notices.
3. To check whether you have a cached or dynamic version of a page,
look at the very end of the page's HTML source. You have the cached
version if the last line looks like this:
Back to top
BOOST ADMINISTRATIVE AND STATS BLOCKS
There are 2 blocks that you can add to help with the administrative
side (status, page configuration), and 1 block to support core stats.
Goto: (administer > Site building > Blocks > List) to place them.
The visibility of blocks can also be configured by role and page.
On the Blocks list page, to the right of each block click 'configure'.
Status Block:
This block shows the current status of the page as far as Boost is
concerned. It will state if the page is served 'live' or by 'Boost',
the expiration of the page and has a Flush Page button to clear the
page from the cache manually. The block only appears if your not user
0 and provides useful information about PHP errors on the page.
Page configuration Block:
This block allows the administrator to set pages individually.
Including setting for minimum cache lifetime(select box), preemptive
cache(on or off), scope(page ID, content type or content container).
Stats Block:
Drupal's core stats is supported. Configure the "Popular content" block, but
then disable it. Place the "Boost: AJAX core statistics" in its place. If ajax
stats are loading too slowly, copy stats/boost_stats.php to your webroot and
enable "Cache Statistics Block". The cache gets updated on cron runs.
Back to top
CONFIGURATION TIPS
For the (i18n) and the (Domain) modules:
Enable
[x] Do not store the cache file path in the database
[x] Flush all sites caches in this database (singe db, multi-site)
Disable
[ ] Only allow ASCII characters in path
Enable XML & AJAX/JSON caches
Enable
[x] Cache .xml & /feed
[x] Cache ajax/json
To Use the Cron Crawler:
Enable
[x] Overwrite the cached file if it already exits
[x] Expire content in DB, do not flush file.
[x] Enable the cron crawler
Back to top
IMPORTANT NOTES AND TROUBLESHOOTING
If cron is not clearing the cache as expected.
Set $base_url variable in /sites/default/settings.php (line 125 or so)
so cron runs error free and clears the cache properly when invoked like
'php /path/to/cron.php' or 'drush cron'. This should be something like
http://www.example.comGuide for editing settings.php
If your Drupal URL paths contain non-ASCII characters, you may have to
tweak your locate settings on the server in order to ensure the URL paths
get correctly translated into directory paths in the file system.
You can also turn off the ASCII filter in the Boost Advanced Settings.
OR install the Transliteration module to help fix the characters.
Back to top
FILE SYSTEM CACHE
The cached files are stored (by default) in the cache/normal/ directory
under your Drupal installation directory. The Drupal pages' URL paths
are translated into file system names in the following manner:
http://example.com/=> cache/normal/example.com/_.html
http://example.com/about=> cache/normal/example.com/about_.html
http://example.com/about/staff=> cache/normal/example.com/about/staff_.html
http://example.com/node/42=> cache/normal/example.com/node/42_.html
You'll note that the directory path includes the Drupal site name, enabling
support for multi-site Drupal installations.
Back to top
HOW BOOST WORKS
Once Boost has been installed and enabled, page requests by anonymous
visitors will be cached as static HTML pages in the server's file system.
Periodically (when the Drupal cron runs) stale or expired pages
(i.e. files or pages exceeding the maximum cache lifetime setting)
will be purged, allowing them to be recreated the first time that the
next anonymous visitor requests that page again. If the Cron Crawler
is enabled, the files and pages will be regenerated automatically.
New rewrite rules are added to the .htaccess file supplied with Drupal,
directing the web server to try and fulfill page requests by anonymous
visitors first and foremost from the static page cache, and to only pass the
request through to Drupal if the requested page is not cacheable or hasn't yet
been cached.
Back to top
DISPATCH MECHANISM
For each incoming page request, the new Apache mod_rewrite directives in
.htaccess will check if a cached version of the requested page should be
served as per the following simple rules:
1. First, we check that the HTTP request method being used is GET.
POST requests are not cacheable, and are passed through to Drupal.
2. Since only anonymous visitors can benefit from the static page cache at
present, we check that the page request doesn't include a cookie that
is set when a user logs in to the Drupal site. If the cookie is
present, we simply let Drupal handle the page request dynamically.
3. Now, for the important bit: we check whether we actually have a cached
HTML file for the request URL path available in the file system cache.
If we do, we direct the web server to serve that file directly and to
terminate the request immediately after; in this case, Drupal (and
indeed PHP) is never invoked, meaning the page request will be served
by the web server itself at full speed.
4. If, however, we couldn't locate a cached version of the page, we just
pass the request on to Drupal, which will serve it dynamically in the
normal manner.
Back to top
LIMITATIONS
Only anonymous visitors will be served cached versions of pages;
authenticated users will get dynamic content. This will limit the
usefulness of this module for those community sites that require user
registration and login for active participation.
In contrast to Drupal's built-in caching, static caching will lose any
additional HTTP headers set for an HTML page by a module. This is unlikely
to be problem except for some very specific modules and rare use cases.
Web server software other than Apache is not supported at the moment.
Adding Lighttpd support would be desirable but is not a high priority for
the developer at present (see TODO.txt). (Note that while the LiteSpeed web
server has not been specifically tested by the developer, it may, in fact,
work, since they claim to support .htaccess files and to have mod_rewrite
compatibility. Feedback on this would be appreciated.)
Back to top
BOOST HANDBOOK PAGES
Boost handbook Main Page
Installation & Settings
Boost Tips & Tricks
FAQ & Future Features
Using Boost and Blogging About It/
BOOST PROJECT & DRUPAL LINKS
Boost project page
Post feature requests and bug reports:
Boost issue que
Drupal Help Forum
The original blog post about Boost
CREDITS
Originally Developed by Arto Bendiken(arto) bendiken.net
Ported to Drupal 5.x by Alexander I. Grafov(axel) drupal.ru
Ported to Drupal 6.x by Ben Lavender(bhuga) bhuga.net
Miscellaneous contributions by Jacob Peddicord, Justin Miller & Barry Jaspan.
6.x Developer and Maintainer, Mike Carper(mikeytown2) of 316solutions
Back to top
END OF FILE
#2
looks like instructions to add this stuff is in the advanced help module/help folder..
-add a help folder to boost, contains the .ini file and help files.
-add config file (boost.help.ini) in the help folder
-the boost.help.ini points to the help.html files
boost/help/boost.help.ini
[help]title = Help html
file = help
weight = -10
boost/help/help.html
all html files are listed in the ini file which can form a menu in it's self..
Really neat stuff.
which means we can have an advanced section
EDIT: the ini file is like a book structure with previous(title), next(title)
This is too cool...
It holds the .css file if wanted and it holds images too! Like the boost rocket..
#3
Please advise: I don't know when the next release is due out..
So far I have just 2 pages for advanced help.. this will change depending on time frame..
If it had to go right now...
we need a new folder, with these files.
boost/help
boost/help/readme.html
boost/help/rules.html
boost/help/boost.help.ini
boost/help/rocket.png
#4
replace these 2, will work better for now..
This should be rewritten to a book type format to make the best use of advance help.
A real good example of advanced help done right is CCK.
I only kept the readme html page in there until this task is done right.
-basically, break down the readme into pages and take some stuff out since the module has to be installed to access the pages with advanced help.
-Then add pages for all the advanced stuff that needs to be out there.
-Still need to test the rules item to see what the underlying code does when invoked.
#5
@dbeall
I don't see a release until November, only thing changing that would be a nasty bug. I may not get around to this issue until Monday. Good job, like the idea of the boost rocket in help!
#6
have a look, maybe use it with your live install at the presentation..
Probably needs some work, (like maybe book links at the top of each page <>
We will want to do more with this I am sure. ... include more advanced items...
anyway have a look see, unzip, drop the help folder into boost/
#7
looks good, committed.
#8
Automatically closed -- issue fixed for 2 weeks with no activity.