0.11_09 commit
[bse.git] / site / docs / bse.pod
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 type web sites.
8
9 Maybe I'll add some other bits here.
10
11 =head1 CHANGES
12
13 =head2 0.11_09
14
15 =over
16
17 =item *
18
19 updated user/* templates from Adrian
20
21 =item *
22
23 checkout code for the shop didn't pass in the config object to the
24 mail class
25
26 =item *
27
28 work around a bug in the search index builder
29
30 =item *
31
32 finally added some test code.  This isn't ready for general use yet and
33 could damage your system.  So don't use it.
34
35 =item *
36
37 BSE::Cfg now checks the current directory as well as $FindBin::Bin,
38 this lets initial.pl work
39
40 =back
41
42 =head2 0.11_08
43
44 This is a test release.
45
46 I still need to integrate some of the customization hooks from the
47 realware branch.
48
49 =over
50
51 =item *
52
53 remove dependency on Time::HiRes (this was used for benchmarking while
54 speeding up the site regen.)
55
56 =item *
57
58 the global date tag didn't handle a date where the time was missing
59 (like article.lastModified).  And it ignored the time when it did
60 manage to extract it.
61
62 =item *
63
64 remove query caching change reports (Table.pm)
65
66 =back
67
68 =head2 0.11_07
69
70 This is a test release.
71
72 =over
73
74 =item *
75
76 initial.pl now looks at the config file for the secure base url
77
78 =item *
79
80 BSE::Util::Secure wasn't importing md5_hex
81
82 =item *
83
84 added missing user/email_conferror_base.tmpl
85
86 =item *
87
88 the user/confirmed.tmpl entry was missing from [pregenerate] in the
89 supplied bse.cfg.  Also user/email_conferror.tmpl
90
91 =item *
92
93 the randomdata key was missing from the [basic] section in the
94 supplied bse.cfg
95
96 =item *
97
98 changed message in site/templates/user/toosoon_base.tmpl to prevent
99 panic when the user goes back and selects another group
100
101 =item *
102
103 changed meaning of ifUser in user templates to accept a parameter if
104 present
105
106 =item *
107
108 updated user/options_base.tmpl to display email confirmed information
109 a bit more correctly
110
111 =item *
112
113 the admin can choose to hide some subscriptions
114
115 =back
116
117 =head2 0.11_06
118
119 This is a test release.
120
121 I wouldn't be suprised to find problems in this release, there have
122 been a lot of changes.
123
124 Still needs some documenting.
125
126 =over
127
128 =item *
129
130 optimized generate_all() for large sites.  Despite the fact most of
131 the improvement came from caching, generate seems to use less memory.
132
133 =item *
134
135 added gen.pl command-line regen script
136
137 =item *
138
139 added option to generate.pl to just regen extras and base pages
140
141 =item *
142
143 $URLBASE and $SECURLBASE from Constants.pm have been moved to C<url>
144 and C<secureurl> in the C<[site]> section of bse.cfg
145
146 =item *
147
148 datadump.pl now uses the newer database configs (has it worked
149 recently?) and the newer mail interfaces.
150
151 =item *
152
153 subscriptions management - interfaces to add new subscription
154 (newsletter) types, and displays options in user options to allow a
155 user to subscribe.  To prevent abuse by spammers (maybe) and by other
156 attackers, we get the user to confirm subscription of their email
157 address.  This is big.
158
159 =item *
160
161 %EXTRA_TAGS has been moved to C<[extra tags]> in bse.cfg
162
163 =back
164
165 =head2 0.11_05
166
167 This is a test release.
168
169 =over
170
171 =item *
172
173 added base_tags() to BSE::Custom (tags available during static
174 generation of most pages.)
175
176 =item *
177
178 step(kids|parents) now available to all articles, though you may have
179 some problems connecting the shop articles (catalogs,products) to
180 others
181
182 =item *
183
184 standard date tag available in most places
185
186 =item *
187
188 the <:summary:> tag now takes an optional which parameter, defaulting
189 to "child".
190
191 =item *
192
193 you can now specify the default template for children of a given
194 article.
195
196 =item *
197
198 you can specify extra template directories to search while editing a
199 given article.
200
201 =item *
202
203 moved the side bar logon form to it's own article (loaded by
204 initial.pl) and added it to the side bar subsection.
205
206 =item *
207
208 shortened the long message used in the refresh back to user.pl when
209 the user has file based products in their cart, but hasn't logged in.
210 This was causing problems with IE6.  It now attempts to pull a longer
211 message out of the config file.
212
213 =back
214
215 =head2 0.11_03
216
217 =over
218
219 =item *
220
221 handling of downloads from the user page is handled better: you don't
222 get a download link unless the file is downloadable, and rejected
223 download results in a refresh to the user page rather than just
224 displaying the user page
225
226 =item *
227
228 the logon and register pages can now be passed a refresh url, which
229 the shop uses when it refreshes to the logon page
230
231 =item *
232
233 add an orders button when logged in
234
235 =item *
236
237 the file list was messed up
238
239 =back
240
241 =head2 0.11_02
242
243 Another test release:
244
245 =over
246
247 =item *
248
249 actually tested the form filling with the user's defaults
250
251 =item *
252
253 modify localinst.perl to remove the default bse.cfg
254
255 =item *
256
257 have the checkout function return if the user needs to register (shop.pl)
258
259 =item *
260
261 check in a few more places if the user needs to register (shop.pl)
262
263 =item *
264
265 changed names of fields in SiteUsers to match the checkout form
266
267 =item *
268
269 added telephone and facsimile fields to the user options
270
271 =back
272
273 =head2 0.11_01
274
275 Test release:
276
277 =over
278
279 =item *
280
281 supports files attached to products for sale
282
283 =item *
284
285 user registration
286
287 =item *
288
289 we now have a config file
290
291 =back
292
293 =head2 0.11
294
295 Looks like all known problems are fixed.  Time to do a semi-major
296 release.
297
298 =head2 0.10_16
299
300 =over
301
302 =item *
303
304 hopefully fixed an occasionaly problem where the images would reorder
305 themselves
306
307 =back
308
309 =head2 0.10_15
310
311 =over
312
313 =item *
314
315 make the depth parameter in <:embed which template depth:> work
316
317 =item *
318
319 give the sitemap a lower depth since 7 levels (5 + the level1 and 2)
320 is too much.
321
322 =back
323
324 =head2 0.10_14
325
326 =over
327
328 =item *
329
330 try to avoid dividing entered prices by 100 when there's an error on
331 the product edit/add form.  There's still some potential problems
332 here, but they're much less likely to cause a problem.
333
334 =item *
335
336 remove the border from image[] generated images
337
338 =item *
339
340 move the error message on the product add form so it isn't mixed up
341 with the menu
342
343 =item *
344
345 the dummy product used to generate the product edit form after an
346 error wasn't useful for getting step catalogs, get the real product
347 object just for that.
348
349 =back
350
351 =head2 0.10_13
352
353 =over
354
355 =item *
356
357 remove the border from embedded images with a url
358
359 =item *
360
361 fixed an old bug that defaulted the threshold from the template (oops)
362
363 =item *
364
365 the ... in <:image which align ...:> or <:image which field ...:> is
366 now appended to the attributes of the image field.  If it includes a
367 border attribute the default border attribute is suppressed.
368
369 =back
370
371 =head2 0.10_12
372
373 =over
374
375 =item *
376
377 new order_list templates from adrian (moved the filter forms into the table)
378
379 =item *
380
381 fixed the image wizard for products.  I'm suprised this ever worked.
382 Wasn't preserving parentid when creating a new product.
383
384 =item *
385
386 new edit_product template from adrian
387
388 =item *
389
390 stupid bug in BSE::Shop::Util
391
392 =item *
393
394 email is now in BSE::CustomBase->required_fields() and can be removed
395 by BSE::Custom->required_fields().  If it is removed then no
396 validation of the email address is performed.
397
398 =item *
399
400 state changes made in handling the confirm page are now saved
401
402 =item *
403
404 added strict to a few modules
405
406 =item *
407
408 added missing error handling methods to BSE::Mail.
409
410 =item *
411
412 old tag on the confirm tag now never gives the undef value message
413
414 =item *
415
416 if you specify a embedding depth less than the current maximum, you
417 won't get an error message embedded when passing that depth.  This
418 lets you do more interesting effects.
419
420 =item *
421
422 shop.pl now writes mail sending errors to STDERR (to the error log on
423 apache) rather than aborting the order display (since the order
424 actually exists at this point.)
425
426 =back
427
428 =head2 0.10_11
429
430 =over
431
432 =item *
433
434 support for filtering the order lists by dates entered by the user
435
436 =item *
437
438 make the add section link work, and make the link itself a little more 
439 usable
440
441 =item *
442
443 removed some old debug code
444
445 =item *
446
447 make BSE::Custom->checkout_actions() work on the confirmation page
448
449 =back
450
451 =head2 0.10_10
452
453 =over
454
455 =item *
456
457 documented new tags for Product.pm and Article.pm
458
459 =item *
460
461 shopadmin.pl can list/move the stepkids (you can hide them too)
462
463 =item *
464
465 added some tests to test if various iterators show anything,
466 ifProducts, ifAnyProds, ifStepProds.
467
468 =back
469
470 =head2 0.10_09
471
472 =over
473
474 =item *
475
476 put the reorder links into the edit templates
477
478 =item *
479
480 fix expire labels for edit_1.tmpl and edit_catalog.tmpl
481
482 =item *
483
484 reordering from the catalog works
485
486 =item *
487
488 reordering from the product editor works
489
490 =back
491
492 =head2 0.10_08
493
494 Making progress.
495
496 =over
497
498 =item *
499
500 fixed the ordering of items in the allprods tag
501
502 =item *
503
504 make allprods always work with products
505
506 =item *
507
508 realware wanted a confirmation page
509
510 =back
511
512 =head2 0.10_07
513
514 Another test release:
515
516 =over
517
518 =item *
519
520 initial step kids|parents for the shop
521
522 =item *
523
524 new popup menu templates from Adrian
525
526 =item *
527
528 added acknowledgements to AUTHOR section
529
530 =back
531
532 =head2 0.10_06
533
534 Test release for Adrian, with his new templates.
535
536 =head2 0.10_05
537
538 Test release for Adrian.
539
540 =head2 0.10_04
541
542 Don't use this version.
543
544 =over
545
546 =item *
547
548 URLs can be directly associated with an image
549
550 =item *
551
552 multiple levels of catalogs
553
554 =item *
555
556 shop item options
557
558 =item *
559
560 filtering/sorting of orders from the template
561
562 =item *
563
564 embedded templates can be based on the template of the article being
565 embedded
566
567 =item *
568
569 order status information, marking an order has having been filled
570
571 =item *
572
573 better handling of generation errors
574
575 =item *
576
577 partial support for Microsoft SQL Server under IIS
578
579 =item *
580
581 extended price tag for the cart and checkout pages
582
583 =item *
584
585 prePurchase target for the shop, to allow custom credit card processing
586
587 =item *
588
589 template based filtering of the order list
590
591 =back
592
593 =head2 0.10_03
594
595 =over
596
597 =item *
598
599 added the admin/reorder.pl script
600
601 =item *
602
603 template names in <: embed :> tags have $ replaced with the template
604 name of the article.
605
606 =back
607
608 =head2 0.10_02
609
610 =over
611
612 =item *
613
614 added the image[] tag  (image[index|align|url])
615
616 =item *
617
618 added printable.pl, site/templates/printable/printable.tmpl to allow
619 printable versions of pages (among other things)
620
621 =item *
622
623 implemented the ifCurrentPage tag
624
625 =back
626
627 =head2 0.10_01
628
629 =over
630
631 =item *
632
633 added <:siteUrl:> tag in %EXTRA_TAGS (used by the RSS templates)
634
635 =item *
636
637 fixed broken template value for the formatting guide (initial.pl)
638
639 =item *
640
641 fixed broken admin links for the formatting guide (initial.pl)
642
643 =item *
644
645 the formatting guide now generates to
646 http://your.site/a/format_guide.html (initial.pl)
647
648 =item *
649
650 RDF/RSS is now generated to /a/site.rdf.  This includes links and
651 titles for the articles on the home page, and a search field (if the
652 tool displaying the RSS supports that.)
653
654 =back
655
656 =head2 0.10
657
658 WARNING: the tag for articles found for a search has changed from:
659
660   article I<field>
661
662 to:
663
664   result I<field>
665
666 There is a new module required: HTML::Parser
667
668 =over 4
669
670 =item *
671
672 the <:embed child:> tags meaning has been expanded to allow embedding
673 of any article with an optional template
674
675 =item *
676
677 there's now an embed[] tag for use in body text.  Both this and 
678 <:embed ... :> are protected against infinite recursion.
679
680 =item *
681
682 changed display values for sections etc in Constants.pm, you can still
683 put your own in when you customize.
684
685 =item *
686
687 the default templates for each level have been set to a single
688 template, for a simpler default setup
689
690 =item *
691
692 new admin index pages, which may display a little better in some
693 browsers
694
695 =item *
696
697 you can move articles between levels, if enabled in Constants.pm
698
699 =item *
700
701 unquoted search terms will do "start of word" searches if enabled in 
702 Constants.pm
703
704 =item *
705
706 html[] tags and <html> body text now has tags stripped when displayed
707 as a summary or as a search excerpt.  The search indexing can now
708 handle both of these too.
709
710 =item *
711
712 the search template now uses 'result' rather than 'article' for the
713 search result entries.  This is needed since the search base page is
714 generated as an article, using a dummy article.  The title and
715 titleImage for this dummy article can be specified in Constants.pm.
716
717 =item *
718
719 you can now control whether an unlisted level1 article is displayed in
720 the crumbs for an article.  By default unlisted level1 articles are
721 NOT listed anymore.
722
723 =item *
724
725 a bunch of new templates from adrian, including moving the common
726 layout into base.tmpl where possible, support for "sidebars".
727
728 =item *
729
730 a formatting guide article in initial.pl (from adrian) (and then an
731 updated version of it)
732
733 =item *
734
735 renamed INSTALL to INSTALL.txt to prevent wierdness if someone tries
736 "make install" on a case-insensitive file system.
737
738 =item *
739
740 administration templates are now kept in the admin directory in the
741 templates directory
742
743 =item *
744
745 added simple test installer.  WARNING: this destroys the existing content
746 of your site.
747
748 =item *
749
750 distribution now includes site/htdocs/shop as a directory rather than
751 as a file
752
753 =item *
754
755 schema/bse.sql now drops the tables if they already exist
756
757 =item *
758
759 the item description in the shopping cart is now a link to the item
760
761 =item *
762
763 changed some defaults in Constants.pm
764
765 =item *
766
767 catalog templates from $TMPLDIR/templates/catalogs weren't being handled
768 correctly
769
770 =back
771
772 =head2 0.09
773
774 =over 4
775
776 =item *
777
778 added support for controlling access to the regenerate option
779
780 =item *
781
782 added the ability to disable auto-regeneration
783
784 this initially broke some buttons, fixed
785
786 =item *
787
788 properly escape child properties in add.pl
789
790 =item *
791
792 removing an article now removes any associated images
793
794 =item *
795
796 removing an image from an article now removes the image file when you
797 save the article.
798
799 =item *
800
801 added datadump.pl (send an email containing a mysql datadump), with
802 configuration in Constants.pm
803
804 =item *
805
806 added imageclean.pl - cleans up the image table and images directory
807
808 =item *
809
810 added an advanced admin page with links to datadump.pl and
811 imageclean.pl (you can change these of course).
812
813 =item *
814
815 previously it was possible for a user with admin rights to choose a
816 template that was outside the templates directory.  
817
818 =back
819
820 =head2 0.08
821
822 =over 4
823
824 =item *
825
826 modified administration templates
827
828 =item *
829
830 formatting is now stripped from body text before an excerpt is
831 produced (for the search results).
832
833 =back
834
835 =head2 0.07
836
837 I'll add in the 0.07 change list as soon as I figure out what I changed...
838
839 Once I get my old 0.08 RC that may include the 0.07 change list.
840
841 =head2 0.06
842
843 Some changes are being made to allow the engine to be embedded into a
844 site (specifically squirrelweb.com.au).
845
846 =over 4
847
848 =item *
849
850 Bug fix: shop.pl had a silly exporter mistake, and a sillier reference
851 to an unknown variable name.
852
853 =item *
854
855 changed admin links to buttons for the catalog and product pages,
856 added a Display button to the product page.
857
858 =item *
859
860 cleaned up the shopitem, cart_base, checkout_base, checkoutfinal_base,
861 mailorder and mailconfirm templates, removing tags that don't work in
862 them, removing references to bodyscoop, fixing broken images, removed
863 thawte stamp.gif.
864
865 =item *
866
867 %EXTRA_TAGS now work in mailorder and mailconfirm templates
868
869 =item *
870
871 You can now use $SHOP_EMAIL_ORDER to disable sending the encrypted
872 order.  (Useful only for testing or until you get encryption keys
873 organized - there's no other way to get the credit card number and
874 expiry date.)
875
876 =item *
877
878 Generate/Product.pm had a hard-coded link to the internal test
879 site. (Doh!)
880
881 =item *
882
883 some base URIs can be configured, though this still needs some work.
884
885 =back
886
887 =head2 0.05
888
889 =over 4
890
891 =item *
892
893 Bug fix: only add the class attribute to thumbnails if one is supplied
894 (doh!)
895
896 =item *
897
898 Moved shop configuration from shop.pl to Constants.pm
899
900 =item *
901
902 Extended template field to 127 characters so directories can be used
903 without chopping off names.
904
905 =item *
906
907 Added installation documentation.
908
909 =item *
910
911 Templates in the drop-down lists in add.pl now includes templates from
912 $TMPLDIR/$level and $TMPLDIR/common.
913
914 =item *
915
916 crumbs now include the section, whether or not they are listed.
917
918 =item *
919
920 added templates.pod, which contains most templating documentation,
921 copied from new documentation in various places (shop.pl, search.pl,
922 Generate::*.pm).
923
924 =item *
925
926 search.pl wasn't handling single-quoted search terms correctly
927
928 =item *
929
930 added ifInMenu tag
931
932 =item *
933
934 more changes to support multiple catalogs:
935
936 =over 4
937
938 =item *
939
940 the initial catalog can be removed.  The initial catalog isn't useful
941 when you need more than one catalog.  If you want multiple catalogs
942 you need to remove the initial catalog and then add new ones.  The
943 templates need work too.
944
945 =item *
946
947 the link/admin fields for the new article are set correctly (oops)
948
949 =item *
950
951 added a sample section template for a multi-catalog shop
952
953 =back
954
955 =item *
956
957 the sample templates look better, along with better title images
958
959 =item *
960
961 the shop was being generated with a non-secure url
962
963 =item *
964
965 parent articles were not being regenerated when an article was deleted
966
967 =back
968
969 =head2 0.04
970
971 You will need to recreate the articles table, since a new column has
972 been added to support article thumbnails.
973
974 =over 4
975
976 =item *
977
978 Added article thumbnails.
979
980 =item *
981
982 Multiple product catalogs.
983
984 =item *
985
986 leadTime is now modifiable in products.
987
988 =item *
989
990 Bug fix: only list .tmpl files from template directories in article
991 editing forms.
992
993 =item *
994
995 Bug fix: prevent adding non-catalog subsections to the shop section.
996
997 =item *
998
999 Bug fix: the crumbs iterator no longer shows crumbs that have "don't
1000 list in menu" set.  Such subsections often shouldn't be linked to.
1001
1002 =item *
1003
1004 The documentation on article templates has been improved.
1005
1006 =item *
1007
1008 Some tags that operate on articles have been expanded to work on all
1009 article objects available in the template.
1010
1011 =back
1012
1013 =head1 AUTHOR
1014
1015 Tony Cook <tony@develop-help.com>
1016
1017 I originally wrote BSE while an employee at SquirrelWeb
1018 (http://www.squirrelgroup.com/) for one of VisualThought's clients,
1019 bodyScoop.com (http://www.bodyScoop.com.au/).
1020
1021 Most of the BSE templates were created by Adrian Oldham of Visual
1022 Thought Communications (http://www.visualthought.com.au) He also
1023 funded and suggested many improvements.
1024
1025 Realware Systems (http://www.realware.com.au/) funded the nested
1026 catalogs, IIS support, the image access tags, and many other shop
1027 improvements, including most of the BSE::Custom hooks.
1028
1029 =cut