[bse.git] / site / docs / bse.pod

=head1 NAME

BSE - an engine for simple magazine style WWW sites.

=head1 DESCRIPTION

BSE is an engine for creating simple magazine stype web sites.

Maybe I'll add some other bits here.

=head1 CHANGES

=head2 0.10_07

Another test release:

=over

=item *

initial step kids|parents for the shop

=item *

new popup menu templates from Adrian

=item *

added acknowledgements to AUTHOR section

=back

=head2 0.10_06

Test release for Adrian, with his new templates.

=head2 0.10_05

Test release for Adrian.

=head2 0.10_04

Don't use this version.

=over

=item *

URLs can be directly associated with an image

=item *

multiple levels of catalogs

=item *

shop item options

=item *

filtering/sorting of orders from the template

=item *

embedded templates can be based on the template of the article being
embedded

=item *

order status information, marking an order has having been filled

=item *

better handling of generation errors

=item *

partial support for Microsoft SQL Server under IIS

=item *

extended price tag for the cart and checkout pages

=item *

prePurchase target for the shop, to allow custom credit card processing

=item *

template based filtering of the order list

=back

=head2 0.10_03

=over

=item *

added the admin/reorder.pl script

=item *

template names in <: embed :> tags have $ replaced with the template
name of the article.

=back

=head2 0.10_02

=over

=item *

added the image[] tag  (image[index|align|url])

=item *

added printable.pl, site/templates/printable/printable.tmpl to allow
printable versions of pages (among other things)

=item *

implemented the ifCurrentPage tag

=back

=head2 0.10_01

=over

=item *

added <:siteUrl:> tag in %EXTRA_TAGS (used by the RSS templates)

=item *

fixed broken template value for the formatting guide (initial.pl)

=item *

fixed broken admin links for the formatting guide (initial.pl)

=item *

the formatting guide now generates to
http://your.site/a/format_guide.html (initial.pl)

=item *

RDF/RSS is now generated to /a/site.rdf.  This includes links and
titles for the articles on the home page, and a search field (if the
tool displaying the RSS supports that.)

=back

=head2 0.10

WARNING: the tag for articles found for a search has changed from:

  article I<field>

to:

  result I<field>

There is a new module required: HTML::Parser

=over 4

=item *

the <:embed child:> tags meaning has been expanded to allow embedding
of any article with an optional template

=item *

there's now an embed[] tag for use in body text.  Both this and 
<:embed ... :> are protected against infinite recursion.

=item *

changed display values for sections etc in Constants.pm, you can still
put your own in when you customize.

=item *

the default templates for each level have been set to a single
template, for a simpler default setup

=item *

new admin index pages, which may display a little better in some
browsers

=item *

you can move articles between levels, if enabled in Constants.pm

=item *

unquoted search terms will do "start of word" searches if enabled in 
Constants.pm

=item *

html[] tags and <html> body text now has tags stripped when displayed
as a summary or as a search excerpt.  The search indexing can now
handle both of these too.

=item *

the search template now uses 'result' rather than 'article' for the
search result entries.  This is needed since the search base page is
generated as an article, using a dummy article.  The title and
titleImage for this dummy article can be specified in Constants.pm.

=item *

you can now control whether an unlisted level1 article is displayed in
the crumbs for an article.  By default unlisted level1 articles are
NOT listed anymore.

=item *

a bunch of new templates from adrian, including moving the common
layout into base.tmpl where possible, support for "sidebars".

=item *

a formatting guide article in initial.pl (from adrian) (and then an
updated version of it)

=item *

renamed INSTALL to INSTALL.txt to prevent wierdness if someone tries
"make install" on a case-insensitive file system.

=item *

administration templates are now kept in the admin directory in the
templates directory

=item *

added simple test installer.  WARNING: this destroys the existing content
of your site.

=item *

distribution now includes site/htdocs/shop as a directory rather than
as a file

=item *

schema/bse.sql now drops the tables if they already exist

=item *

the item description in the shopping cart is now a link to the item

=item *

changed some defaults in Constants.pm

=item *

catalog templates from $TMPLDIR/templates/catalogs weren't being handled
correctly

=back

=head2 0.09

=over 4

=item *

added support for controlling access to the regenerate option

=item *

added the ability to disable auto-regeneration

this initially broke some buttons, fixed

=item *

properly escape child properties in add.pl

=item *

removing an article now removes any associated images

=item *

removing an image from an article now removes the image file when you
save the article.

=item *

added datadump.pl (send an email containing a mysql datadump), with
configuration in Constants.pm

=item *

added imageclean.pl - cleans up the image table and images directory

=item *

added an advanced admin page with links to datadump.pl and
imageclean.pl (you can change these of course).

=item *

previously it was possible for a user with admin rights to choose a
template that was outside the templates directory.  

=back

=head2 0.08

=over 4

=item *

modified administration templates

=item *

formatting is now stripped from body text before an excerpt is
produced (for the search results).

=back

=head2 0.07

I'll add in the 0.07 change list as soon as I figure out what I changed...

Once I get my old 0.08 RC that may include the 0.07 change list.

=head2 0.06

Some changes are being made to allow the engine to be embedded into a
site (specifically squirrelweb.com.au).

=over 4

=item *

Bug fix: shop.pl had a silly exporter mistake, and a sillier reference
to an unknown variable name.

=item *

changed admin links to buttons for the catalog and product pages,
added a Display button to the product page.

=item *

cleaned up the shopitem, cart_base, checkout_base, checkoutfinal_base,
mailorder and mailconfirm templates, removing tags that don't work in
them, removing references to bodyscoop, fixing broken images, removed
thawte stamp.gif.

=item *

%EXTRA_TAGS now work in mailorder and mailconfirm templates

=item *

You can now use $SHOP_EMAIL_ORDER to disable sending the encrypted
order.  (Useful only for testing or until you get encryption keys
organized - there's no other way to get the credit card number and
expiry date.)

=item *

Generate/Product.pm had a hard-coded link to the internal test
site. (Doh!)

=item *

some base URIs can be configured, though this still needs some work.

=back

=head2 0.05

=over 4

=item *

Bug fix: only add the class attribute to thumbnails if one is supplied
(doh!)

=item *

Moved shop configuration from shop.pl to Constants.pm

=item *

Extended template field to 127 characters so directories can be used
without chopping off names.

=item *

Added installation documentation.

=item *

Templates in the drop-down lists in add.pl now includes templates from
$TMPLDIR/$level and $TMPLDIR/common.

=item *

crumbs now include the section, whether or not they are listed.

=item *

added templates.pod, which contains most templating documentation,
copied from new documentation in various places (shop.pl, search.pl,
Generate::*.pm).

=item *

search.pl wasn't handling single-quoted search terms correctly

=item *

added ifInMenu tag

=item *

more changes to support multiple catalogs:

=over 4

=item *

the initial catalog can be removed.  The initial catalog isn't useful
when you need more than one catalog.  If you want multiple catalogs
you need to remove the initial catalog and then add new ones.  The
templates need work too.

=item *

the link/admin fields for the new article are set correctly (oops)

=item *

added a sample section template for a multi-catalog shop

=back

=item *

the sample templates look better, along with better title images

=item *

the shop was being generated with a non-secure url

=item *

parent articles were not being regenerated when an article was deleted

=back

=head2 0.04

You will need to recreate the articles table, since a new column has
been added to support article thumbnails.

=over 4

=item *

Added article thumbnails.

=item *

Multiple product catalogs.

=item *

leadTime is now modifiable in products.

=item *

Bug fix: only list .tmpl files from template directories in article
editing forms.

=item *

Bug fix: prevent adding non-catalog subsections to the shop section.

=item *

Bug fix: the crumbs iterator no longer shows crumbs that have "don't
list in menu" set.  Such subsections often shouldn't be linked to.

=item *

The documentation on article templates has been improved.

=item *

Some tags that operate on articles have been expanded to work on all
article objects available in the template.

=back

=head1 AUTHOR

Tony Cook <tony@develop-help.com>

I originally wrote BSE while an employee at SquirrelWeb
http://www.squirrelweb.com.au/ for http://www.bodyscoop.com.au/

Most of the BSE templates were created by Adrian Oldham
<adriann@visualthought.com.au>.  He also funded and suggested many
improvements.

Realware Systems http://www.realware.com.au/ funded the nested
catalogs, IIS support, the image access tags, and many other shop
improvements, including most of the BSE::Custom hooks.

=cut
Commit	Line	Data
e8d7cca1 TC	1	=head1 NAME
	2
	3	BSE - an engine for simple magazine style WWW sites.
	4
	5	=head1 DESCRIPTION
	6
	7	BSE is an engine for creating simple magazine stype web sites.
	8
	9	Maybe I'll add some other bits here.
	10
	11	=head1 CHANGES
	12
99ef7979 TC	13	=head2 0.10_07
	14
	15	Another test release:
	16
	17	=over
	18
	19	=item *
	20
	21	initial step kids\|parents for the shop
	22
	23	=item *
	24
	25	new popup menu templates from Adrian
	26
	27	=item *
	28
	29	added acknowledgements to AUTHOR section
	30
	31	=back
	32
	33	=head2 0.10_06
	34
	35	Test release for Adrian, with his new templates.
	36
	37	=head2 0.10_05
	38
	39	Test release for Adrian.
	40
365115ba TC	41	=head2 0.10_04
365115ba TC	42
99ef7979 TC	43	Don't use this version.
99ef7979 TC	44
365115ba TC	45	=over
	46
	47	=item *
	48
	49	URLs can be directly associated with an image
	50
	51	=item *
	52
	53	multiple levels of catalogs
	54
	55	=item *
	56
	57	shop item options
	58
	59	=item *
	60
	61	filtering/sorting of orders from the template
	62
	63	=item *
	64
	65	embedded templates can be based on the template of the article being
	66	embedded
	67
	68	=item *
	69
	70	order status information, marking an order has having been filled
	71
	72	=item *
	73
	74	better handling of generation errors
	75
	76	=item *
	77
	78	partial support for Microsoft SQL Server under IIS
	79
	80	=item *
	81
	82	extended price tag for the cart and checkout pages
	83
	84	=item *
	85
	86	prePurchase target for the shop, to allow custom credit card processing
	87
	88	=item *
	89
	90	template based filtering of the order list
	91
	92	=back
	93
d3fd4b55 TC	94	=head2 0.10_03
	95
	96	=over
	97
	98	=item *
	99
	100	added the admin/reorder.pl script
	101
	102	=item *
	103
	104	template names in <: embed :> tags have $ replaced with the template
	105	name of the article.
	106
	107	=back
	108
8642d701 TC	109	=head2 0.10_02
	110
	111	=over
	112
	113	=item *
	114
	115	added the image[] tag (image[index\|align\|url])
	116
	117	=item *
	118
	119	added printable.pl, site/templates/printable/printable.tmpl to allow
	120	printable versions of pages (among other things)
	121
d3fd4b55 TC	122	=item *
	123
	124	implemented the ifCurrentPage tag
	125
8642d701 TC	126	=back
8642d701 TC	127
6dbadf01 TC	128	=head2 0.10_01
	129
	130	=over
	131
	132	=item *
	133
	134	added <:siteUrl:> tag in %EXTRA_TAGS (used by the RSS templates)
	135
	136	=item *
	137
	138	fixed broken template value for the formatting guide (initial.pl)
	139
	140	=item *
	141
	142	fixed broken admin links for the formatting guide (initial.pl)
	143
	144	=item *
	145
	146	the formatting guide now generates to
	147	http://your.site/a/format_guide.html (initial.pl)
	148
	149	=item *
	150
	151	RDF/RSS is now generated to /a/site.rdf. This includes links and
	152	titles for the articles on the home page, and a search field (if the
	153	tool displaying the RSS supports that.)
	154
	155	=back
	156
25048431 TC	157	=head2 0.10
25048431 TC	158
5c2f0006 TC	159	WARNING: the tag for articles found for a search has changed from:
	160
	161	article I<field>
	162
	163	to:
	164
	165	result I<field>
	166
e1f1b0de TC	167	There is a new module required: HTML::Parser
e1f1b0de TC	168
25048431 TC	169	=over 4
	170
	171	=item *
	172
	173	the <:embed child:> tags meaning has been expanded to allow embedding
	174	of any article with an optional template
	175
	176	=item *
	177
	178	there's now an embed[] tag for use in body text. Both this and
	179	<:embed ... :> are protected against infinite recursion.
	180
	181	=item *
	182
	183	changed display values for sections etc in Constants.pm, you can still
	184	put your own in when you customize.
	185
	186	=item *
	187
	188	the default templates for each level have been set to a single
	189	template, for a simpler default setup
	190
	191	=item *
	192
	193	new admin index pages, which may display a little better in some
	194	browsers
	195
	196	=item *
	197
	198	you can move articles between levels, if enabled in Constants.pm
	199
	200	=item *
	201
	202	unquoted search terms will do "start of word" searches if enabled in
	203	Constants.pm
	204
	205	=item *
	206
	207	html[] tags and <html> body text now has tags stripped when displayed
	208	as a summary or as a search excerpt. The search indexing can now
	209	handle both of these too.
	210
	211	=item *
	212
5c2f0006 TC	213	the search template now uses 'result' rather than 'article' for the
	214	search result entries. This is needed since the search base page is
	215	generated as an article, using a dummy article. The title and
	216	titleImage for this dummy article can be specified in Constants.pm.
	217
eed62368 TC	218	=item *
	219
	220	you can now control whether an unlisted level1 article is displayed in
d093b204 TC	221	the crumbs for an article. By default unlisted level1 articles are
d093b204 TC	222	NOT listed anymore.
eed62368 TC	223
	224	=item *
	225
	226	a bunch of new templates from adrian, including moving the common
	227	layout into base.tmpl where possible, support for "sidebars".
	228
	229	=item *
	230
3f87d74c TC	231	a formatting guide article in initial.pl (from adrian) (and then an
3f87d74c TC	232	updated version of it)
eed62368 TC	233
	234	=item *
	235
	236	renamed INSTALL to INSTALL.txt to prevent wierdness if someone tries
	237	"make install" on a case-insensitive file system.
	238
e1f1b0de TC	239	=item *
	240
	241	administration templates are now kept in the admin directory in the
	242	templates directory
	243
	244	=item *
	245
	246	added simple test installer. WARNING: this destroys the existing content
	247	of your site.
	248
	249	=item *
	250
	251	distribution now includes site/htdocs/shop as a directory rather than
	252	as a file
	253
	254	=item *
	255
	256	schema/bse.sql now drops the tables if they already exist
	257
52770e1a TC	258	=item *
	259
	260	the item description in the shopping cart is now a link to the item
	261
	262	=item *
	263
	264	changed some defaults in Constants.pm
	265
e8b78086 TC	266	=item *
	267
	268	catalog templates from $TMPLDIR/templates/catalogs weren't being handled
	269	correctly
	270
25048431 TC	271	=back
25048431 TC	272
e8d7cca1 TC	273	=head2 0.09
	274
	275	=over 4
	276
	277	=item *
	278
	279	added support for controlling access to the regenerate option
	280
	281	=item *
	282
	283	added the ability to disable auto-regeneration
	284
	285	this initially broke some buttons, fixed
	286
	287	=item *
	288
	289	properly escape child properties in add.pl
	290
	291	=item *
	292
	293	removing an article now removes any associated images
	294
	295	=item *
	296
	297	removing an image from an article now removes the image file when you
	298	save the article.
	299
	300	=item *
	301
	302	added datadump.pl (send an email containing a mysql datadump), with
	303	configuration in Constants.pm
	304
	305	=item *
	306
	307	added imageclean.pl - cleans up the image table and images directory
	308
	309	=item *
	310
	311	added an advanced admin page with links to datadump.pl and
	312	imageclean.pl (you can change these of course).
	313
	314	=item *
	315
	316	previously it was possible for a user with admin rights to choose a
	317	template that was outside the templates directory.
	318
	319	=back
	320
	321	=head2 0.08
	322
	323	=over 4
	324
	325	=item *
	326
	327	modified administration templates
	328
	329	=item *
	330
	331	formatting is now stripped from body text before an excerpt is
	332	produced (for the search results).
	333
	334	=back
	335
	336	=head2 0.07
337
338	I'll add in the 0.07 change list as soon as I figure out what I changed...
339
340	Once I get my old 0.08 RC that may include the 0.07 change list.
341
342	=head2 0.06
343
344	Some changes are being made to allow the engine to be embedded into a
345	site (specifically squirrelweb.com.au).
346
347	=over 4
348
349	=item *
350
351	Bug fix: shop.pl had a silly exporter mistake, and a sillier reference
352	to an unknown variable name.
353
354	=item *
355
356	changed admin links to buttons for the catalog and product pages,
357	added a Display button to the product page.
358
359	=item *
360
361	cleaned up the shopitem, cart_base, checkout_base, checkoutfinal_base,
362	mailorder and mailconfirm templates, removing tags that don't work in
363	them, removing references to bodyscoop, fixing broken images, removed
364	thawte stamp.gif.
365
366	=item *
367
368	%EXTRA_TAGS now work in mailorder and mailconfirm templates
369
370	=item *
371
372	You can now use $SHOP_EMAIL_ORDER to disable sending the encrypted
373	order. (Useful only for testing or until you get encryption keys
374	organized - there's no other way to get the credit card number and
375	expiry date.)
376
377	=item *
378
379	Generate/Product.pm had a hard-coded link to the internal test
380	site. (Doh!)
381
382	=item *
383
384	some base URIs can be configured, though this still needs some work.
385
386	=back
387
388	=head2 0.05
389
390	=over 4
391
392	=item *
393
394	Bug fix: only add the class attribute to thumbnails if one is supplied
395	(doh!)
396
397	=item *
398
399	Moved shop configuration from shop.pl to Constants.pm
400
401	=item *
402
403	Extended template field to 127 characters so directories can be used
404	without chopping off names.
405
406	=item *
407
408	Added installation documentation.
409
410	=item *
411
412	Templates in the drop-down lists in add.pl now includes templates from
413	$TMPLDIR/$level and $TMPLDIR/common.
414
415	=item *
416
417	crumbs now include the section, whether or not they are listed.
418
419	=item *
420
421	added templates.pod, which contains most templating documentation,
422	copied from new documentation in various places (shop.pl, search.pl,
423	Generate::*.pm).
424
425	=item *
426
427	search.pl wasn't handling single-quoted search terms correctly
428
429	=item *
430
431	added ifInMenu tag
432
433	=item *
434
435	more changes to support multiple catalogs:
436
437	=over 4
438
439	=item *
440
441	the initial catalog can be removed. The initial catalog isn't useful
442	when you need more than one catalog. If you want multiple catalogs
443	you need to remove the initial catalog and then add new ones. The
444	templates need work too.
445
446	=item *
447
448	the link/admin fields for the new article are set correctly (oops)
449
450	=item *
451
452	added a sample section template for a multi-catalog shop
453
454	=back
455
456	=item *
457
458	the sample templates look better, along with better title images
459
460	=item *
461
462	the shop was being generated with a non-secure url
463
464	=item *
465
466	parent articles were not being regenerated when an article was deleted
467
468	=back
469
470	=head2 0.04
471
472	You will need to recreate the articles table, since a new column has
473	been added to support article thumbnails.
474
475	=over 4
476
477	=item *
478
479	Added article thumbnails.
480
481	=item *
482
483	Multiple product catalogs.
484
485	=item *
486
487	leadTime is now modifiable in products.
488
489	=item *
490
491	Bug fix: only list .tmpl files from template directories in article
492	editing forms.
493
494	=item *
495
496	Bug fix: prevent adding non-catalog subsections to the shop section.
497
498	=item *
499
500	Bug fix: the crumbs iterator no longer shows crumbs that have "don't
501	list in menu" set. Such subsections often shouldn't be linked to.
502
503	=item *
504
505	The documentation on article templates has been improved.
506
507	=item *
508
509	Some tags that operate on articles have been expanded to work on all
510	article objects available in the template.
511
512	=back
513
99ef7979 TC	514	=head1 AUTHOR
	515
	516	Tony Cook <tony@develop-help.com>
	517
	518	I originally wrote BSE while an employee at SquirrelWeb
	519	http://www.squirrelweb.com.au/ for http://www.bodyscoop.com.au/
	520
	521	Most of the BSE templates were created by Adrian Oldham
	522	<adriann@visualthought.com.au>. He also funded and suggested many
	523	improvements.
	524
	525	Realware Systems http://www.realware.com.au/ funded the nested
	526	catalogs, IIS support, the image access tags, and many other shop
	527	improvements, including most of the BSE::Custom hooks.
	528
e8d7cca1	529	=cut