[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_09

=over

=item *

put the reorder links into the edit templates

=item *

fix expire labels for edit_1.tmpl and edit_catalog.tmpl

=item *

reordering from the catalog works

=item *

reordering from the product editor works

=back

=head2 0.10_08

Making progress.

=over

=item *

fixed the ordering of items in the allprods tag

=item *

make allprods always work with products

=item *

realware wanted a confirmation page

=back

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