dynamic.pod - dynamic article generation for BSE.
The 0.15 series of BSE from 0.15_19 on, stable around 0.15_28, added the ability for articles to be generated upon presentation to the user.
There are four ways an article can be set to be dynamically generated:
an article that has any sort of user access controls on it is generated dynamically.
an article with the Always dynamic checkbox checked will be generated dynamically.
an article with any ancestor that has the Always dynamic and Descendants inherit Always Dynamic flags set.
if the all_dynamic flag is set in the [basic] section of
bse.cfg.
BSE 0.15_21 added the ability to restrict siteuser access to articles based on their membership in a group. Articles inherit these access controls from their parent articles if they have the Inherit Parent groups flag set.
If an article has an group requirements, either set on the article itself or inherited from an ancestor article, then that article will be generated dynamically.
If you set the Always dynamic flag on an article then that article is generated dynamically.
If you set the Always dynamic and Descendants inherit Always Dynamic flags on an article then that article and all of its descendants (not stepchildren) will be generated dynamically.
If you set the all_dynamic key in the [basic] section of
bse.cfg to a non-zero value then all articles will be generated
automatically.
Note: you will need to perform web server configuration to point
requests for http://your.site/ at
http://your.site/cgi-bin/page.pl?id=1, and similarly for the RSS
article, otherwise the user will not see generated content for these
articles. See Fixed Links below.
Dynamic articles are processing in 2 stages:
static tag replacement - at this point all of the normal static page tags are replaced. The resulting template is saved to the dynamic cache.
dynamic tag replacement - tags specific to dynamic generation are replaced at this point, and the article is sent to the user.
This is the same as tag replacement for a static page, except:
the page is stored in the dynamic cache instead of in the web server document tree.
the ifDynamic tag is true.
Depending on configuration, this can be done either during normal site/article regeneration or just prior to page.pl displaying the page. See Just in time processing.
Dynamic tags are replaced and the page presented to the user.
The content type sent to the browser is based on the original template
of the article, so you can set a key to give your template a different
type from text/html but setting it in the [template types] section
of bse.cfg.
This is done by the page.pl script.
Normally when you regenerate a dynamically generated article BSE will perform the first pass immediately and save that to the dynamic cache. If your site is large and you do a full site regen this can be very time consuming.
If you set jit_dynamic_regen in [basic] in bse.cfg, then
attempting to regenerate the page (including the regen normally done
on saving an article) will instead simply delete the pregenerated page
from the dynamic cache.
Then when the user attempts to display the page, page.pl will
notice the missing page, pregenerate it and store it in the cache, and
then proceed to normal dynamic page processing.
This means for large sites that you're only generating the pages that users are actually looking at.
Note that if a large percentage of your site is looked at in a day you're probably better off not using this option, since it will increase the load on your web server instead of reducing it.
If your web server normally suffers from high peak-time loads, you should probably not use this, since it moves most page processing to peak-time.
All normal dynamic tags are available during dynamic tag processing, including:
script - value of SCRIPT_NAME (CGI variable) - name of the current script
cgi fieldname - submitted CGI parameters
old fieldname default-func default-args - access to submited CGI parameteres with defaults.
dynreplace source regexp replacement - replace regular expression.
dyntoday
dyntoday "dateformat" - formatted current date
dynreport reportname template arg1 ... - dynamic report embedding
The following tags are available on all user side dynamic pages (search page, shop pages, etc):
user field - access to information from the currently logged on siteuser
ifUser - test if there is a currently logged on siteuser
ifUserCanSee which - test if the user has access to the given article. Note: which must refer to a dynamic article tag (of which there aren't many yet), or an article by number.
The following tags can be used on dynamically generated article pages (as per page.pl):
dynarticle fieldname - access to information from the current article.
There are no dynamic tags specific to catalogs, products or seminars at this point.
Since dynamic pages are generated in two passes a single tag cannot rely upon tags from the two separate passes.
For example:
if Or [ifUser] [ifAdmin]
won't work because ifUser is a dynamic tag and ifAdmin is a static tag.
Some articles, like article 1, the home page, and article 3 the main
shop article have protected links, by having an entry in the
[protect link] section of bse.cfg.
If these articles become dynamic by any of the mechanisms listed in MAKING ARTICLES DYNAMIC then links to these articles will be broken.
For all articles except the home page article you can remove these entries, and your site will work again.
The home page article will need extra web server configuration, you
will need to add a rewrite rule to redirect http://your.site/ to
http://your.site/cgi-bin/page.pl?id=1 or whatever other tool your
web server provides with the same functionality.
There are 2 ways to run page.pl as persistent servers, to reduce startup cost:
run page.pl using Apache::Registry under mod_perl
run page.fcgi under FastCGI
set BSE::Handler::Page as a mod_perl handler for page.pl
This has the severe limitation that you can only run one page.pl per Apache server, due to limitations in BSE.
To configure Apache to run page.pl via mod_perl, add the following to your virtual host configuration:
PerlModule Apache::Registry
<Location /cgi-bin/page.pl>
SetHandler perl-script
PerlHandler Apache::Registry
Options ExecCGI
</Location>
You will need to configure Apache to use mod_fastcgi.
First, Apache needs to be configured to use FastCGI, you may need to install it from source, then configure it:
LoadModule fastcgi_module /usr/lib/apache/1.3/mod_fastcgi.so
Then configure your vhosts cgi-bin directory to run .fcgi scripts with fastcgi:
<Directory /var/www/httpd/bsetest/cgi-bin/>
AllowOverride All
AddHandler fastcgi-script fcgi
</Directory>
Check this works with:
http://your.site/cgi-bin/page.fcgi?page=1
Then setup a rewrite rule:
RewriteRule ^/cgi-bin/page.pl(.*) /cgi-bin/page.fcgi$1 [PT]
This sets a native mod_perl hander to process page.pl requests:
First, let perl know where the BSE libraries are:
<Perl>
use lib '/yourpath/cgi-bin/modules';
</Perl>
Now load the module, and set it as the handler for page.pl:
PerlModule BSE::Handler::Page;
<Location /cgi-bin/page.pl>
PerlSetVar BSEConfig /var/www/httpd/bsetest/cgi-bin/
SetHandler perl-script
PerlHandler BSE::Handler::Page
Options ExecCGI
</Location>
The PerlSetVar line should set BSEConfig to the directory containing your bse.cfg file, not to the file itself.
Tony Cook <tony@develop-help.com>
$Revision$