handle global files too
[bse.git] / site / docs / config.pod
CommitLineData
61551101
TC
1=head1 NAME
2
3config.pod - documents BSE configuration file options
4
5=head1 DESCRIPTION
6
7BSE historically used Constants.pm to keep most configuration
8information. The plan is to make sure any new configuration is kept
9in bse.cfg, and to slowly move most configuration information into
10bse.cfg.
11
12Keeping configuration information in Constants.pm makes it difficult
13to perform upgrades and makes it impossible to use tools such as
14mod_perl, at least if you want more than one site on the machine.
15
16=head1 CONFIGURATION ENTRIES
17
41f10371
TC
18=head2 [site]
19
20Contains URL configuration for the site.
21
22=over
23
24=item url
25
26The normal URL for the non-secure parts of the site.
27
28=item secureurl
29
30The secure URL for the shop, products and other portions of the site
31that should use SSL. This isn't checked to make sure it is https.
32
33=item name
34
35Used as the site "name" in a few places.
36
37=item adminurl
38
39If set, this is used as the base URL for accessing the administrative
40functions of your site.
41
42=item secureadmin
43
44Ignored if C<adminurl> is set.
45
46If this is true then C<secureurl> is used as the base URL for
47accessing the administrative functions of your site, otherwise C<url>
48is used as the base URL. Default: false (C<url>'s value is used)
49
c5f849c7
TC
50=item forward_from
51
52Configure the IP address of one or more front-end proxies. This can
53be a regular expression except that C<.> is translated to C<\.> and
54C<*> is tranlated to C<.*> to give more glob() like matching.
55
56If the reqesting host matches then admin site URL matching is done
57against HTTP_X_FORWARDED_SERVER instead of SERVER_NAME.
58
59Default: no front-end server configured.
60
41f10371
TC
61=back
62
61551101
TC
63=head2 [paths]
64
65Contains various file system paths.
66
67=over
68
69=item downloads
70
71This is where the files uploads with the file wizard are stored. It
72must be writable by the web server user.
73
74=item admin_templates
75
76Directory containing administrative templates. Note: this is not
77completely implemented for now, so assume the default. Default: admin
78directory under $TMPLDIR.
79
80=item templates
81
aefcabcb
TC
82Directory base for most templates.
83
84=item local_templates
85
86Local Directory base for templates. This is searched before the
87templates directory.
61551101 88
ca9aa2bf
TC
89=item images
90
91Where uploaded images are stored. This is not yet completely
92implemented. Default: $IMAGEDIR.
93
331fd099
TC
94=item libraries
95
96Local search path for BSE::Custom, or the class configured by
97C<custom_class> in [basic].
98
3c32512d
TC
99=item siteuser_images
100
101Where uploaded siteuser images are stored. This must be set in the
102config file. The default bse.cfg include an entry to use the current
103values of [paths].downloads
104
efcc5a30
TC
105=item dynamic_cache
106
107Pregenerated dynamic article pages are stored here. This must be
108defined if you site contains any dynamicly generated pages.
109
195977cd
TC
110=item scalecache
111
112The directory where cached versions of scaled thumbnails are stored.
113Defaults to image_dir/scaled. This must be in the document tree. If
114you set this you should also set scalecacheurl.
115
116=item scalecacheurl
117
118The URL to the directory represented by scalecache. Defaults to
119/images/scaled.
120
61551101
TC
121=back
122
123=head2 [extensions]
124
125This section is used by the file wizard to map uploaded file
126extensions to MIME content types. This can be used to extend
127BSE::FileEditor's internal extension map. It cannot override that
128map.
129
130The key for each entry is the extension, without the leading '.'.
131
132eg.
133
134 xls = application/msexcel
135
136=head2 [templates]
137
138Used for translating symbolic template names into full names under the
139template directory.
140
141In each case the default is the name with a C<.tmpl> extension.
142
143=over
144
145=item user/logon
146
147user logon page
148
149=item user/register
150
151user registration page
152
153=back
154
155=head2 [admin templates]
156
157Used for translating the names of administration templates into filenames.
158
159In each case the default is the name with a C<.tmpl> extension.
160
161=over
162
163=item filelist
164
165article file wizard
166
d2730773
TC
167=item catalog
168
169Catalog editor page. Default admin/edit_catalog.tmpl
170
171=item 1
172
173=item 2
174
175=item 3
176
177=item 4
178
179=item 5
180
181Article edit pages. Default admin/edit_<number>.tmpl
182
183=item steps
184
185Step child/parent management page. Default admin/edit_steps.tmpl
186
61551101
TC
187=back
188
189=head2 [html]
190
191Minor html items.
192
193=over
194
195=item charset
196
197The value of the charset keyword when outputting HTML from a script.
198Set to the empty string to suppress the charset keyword. Default:
199iso-8859-1.
200
5af99440
TC
201=item redirect_links
202
203If this is a non-zero number, then all but mailto links are redirected
204to C<nuser.pl/redirect> so you can display a diclaimer. If this
205contained alphabetics it's treated as a comma separated list of url
206schemes that should be handled via C<nuser.pl/redirect>. If 0 or not
207present, no redirection is done.
208
209The redirect URL includes a hash of the url, title and the redirect
210salt to prevent using this mechanism by external sites for cookie
211stealing attacks.
212
213=item redirect_salt
214
215The salt used in generating the has for redirect_links. Default: an
216empty string.
217
61551101
TC
218=back
219
220=head2 [basic]
221
222=over
223
224=item cookie_lifetime
225
226The expiry time for cookies. This should be in the form supported by
227CGI.pm for the -expires parameter. Typically you want a plus ('+'), a
228number, and a time character (s - seconds, m - minutes, h - hours, d -
229days, M - months). Default: +3h
230
a8ddb0f3
TC
231=item cookie_domain
232
233This overrides the domain value set for cookies. This is useful if
234you allow the site to run under both example.com and www.example.com,
235if you set cookie_domain to example.com then a user visiting
236www.example.com will still have their cookies when they visit
237example.com.
238
3c8b9c2c
TC
239=item cookie_name
240
241This overrides the cookie name used to store the session id. Default:
242sessionid. This is useful when you have 2 sites under the same
243top-level domain, and helps disambiguate the cookie returned by the
244browser.
245
61551101
TC
246=item minpassword
247
248Minimum password length in characters. Default: 4.
249
b19047a6
TC
250=item randomdata
251
252Device to read random data from. This device should not block when it
253runs out of entropy.
254
6e3d2da5
TC
255=item sign
256
257If this is true then the encrypted messages containing the customer's
258credit card number are sent to the shop owner signed. To avoid
259keeping a passphrase and signing key on the server you can set this to
260false (0). This has the effect that anyone could send you an unsigned
261message encrypted with your public key, though this may not be a
262security threat. Default: True.
263
ca9aa2bf
TC
264=item link_titles
265
266If this is true then the links to your articles within BSE will be
267followed by a / and then by a simplified version of the article title.
268The aim is to include at least some title information in the URL
269without modifying the name of the HTML file. Default: False.
270
9168c88c
TC
271=item access_control
272
273If this is true then the user/group/permissions database is used to
274control access to the system. Default: False.
275
147e99e8
TC
276=item access_filter_steps
277
278If this is true, then the drop-down lists of possible stepparents and
279stepchildren on the article edit pages are filtered for access control.
280Default: False.
281
444957b9
TC
282=item access_filter_parents
283
284If this is true, then the drop-down lists of possible parents on the
285newsletter edit pages are filtered for access control.
286Default: False.
287
d49f56a6
TC
288=item server_auth
289
290Set this to non-zero to enable authentication via server
291authentication (usually Basic Authentication.) You should normally
292set this if you set htusers below. Default: 0 (disabled)
293
9168c88c
TC
294=item htusers
295
296This should be the path to a file to be updated with the list of users
297and crypt() versions of their passwords. If this is set then the
298security system will check for a user set by the browser before
299attempting a form based logon. Default: None.
300
331fd099
TC
301=item custom_class
302
303The name of the custom class for your site. This is currently only
304used for article editing customizations. This class should derive
305from BSE::CustomBase. Default: BSE::Custom.
306
671a9877 307=item jit_dynamic_pregen
efcc5a30
TC
308
309If this is true, then pre-generation for dynamic pages will be delayed
310until the page is displayed to a user. Default: off.
311
74b21f6d
TC
312=item staticajax
313
314If true, the ifAjax and ajax tags will be active for static pages.
315
195977cd
TC
316=item cache_thumbnails
317
318If set to zero the results of the thumbimage/gthumbimage body/template
319tags will not be cached. Default: 1 (caching is enabled).
320
b902f9de
TC
321=item static_thumbnails
322
323If true and cache_thumbnails is true then thumbnails for the thumbnail
324cache will be generated when a static page is regenerated, and the
325link from the page will link to the image in the cache rather than to
326C<thumb.pl>. Default: 1 (static thumbnails enabled).
327
73e6b73a
TC
328=item alias_prefix
329
330The prefix applied to articles that use a linkAlias url. This should
331start with a /.
332
333=item use_alias
334
335If this is non-zero then an article with linkAlias set will use an
336alias url instead of the "real" url. You will need to configure a
337RewriteRule or ErrorDocument to page.pl to direct the user to the
338correct URL. Default: 1.
339
340=item alias_suffix
341
342If this is non-zero then the title is cleaned up (all but
343alphanumerics removed) and appended to the alias URL generated.
344
8a153d74
TC
345=item default_popupimage
346
347This is the default popup image class for the popimage[] and
348gpopimage[] tags. Default: popup.
349
b19047a6
TC
350=back
351
352=head2 [mail]
353
35c0719f 354This section controls how BSE sends email.
b19047a6
TC
355
356=over
357
358=item smtp_server
359
360The host or IP address of your mail server. If this is not set
361C<sendmail> will be used instead. If this is set you must also set
362I<helo>.
363
364=item helo
365
366The name that BSE uses to identify itself when sending mail via SMTP.
367Required if I<smtp_server> is set.
368
369=item sendmail
370
371The path to the C<sendmail> binary. Default: /usr/lib/sendmail
372
373=item sendmail_opts
374
375The options supplied to sendmail. Default: -t -oi
376
377You may want to add the -odq option to this if you want mail queued
378rather than sent immediately.
379
67b69296
TC
380=item set_errors_to_from
381
382If true, we add an Errors-To header set to the same as the From
383header. Default: true.
384
61551101
TC
385=back
386
ca9aa2bf 387=head2 [children of I<id>]
721cd24c
TC
388
389Where I<id> is the identifier for an article.
390
391=over
392
393=item template
394
395the name of the default template for children of the given parent
396
397=item template_dirs
398
399a comma-separated list of extra directories under $TMPLDIR to search
400for templates that can be used for children of the given parent article.
401
402=back
403
ca9aa2bf
TC
404=head2 [article I<id>]
405
406Where I<id> is the identifier of an article.
407
408=over
409
410=item template_dirs
411
412A comma-separated list of extra directories under $TMPLDIR to search
413for templates that can be used for children of the given parent
414article.
415
416=item extra_templates
417
418A comma-separated list of extra templates under $TMPLDIR that can be
419used for the given article.
420
421=back
422
caa7299c
TC
423=head2 [level I<level>]
424
425=over
426
427=item template
428
429The default template for this level of article, assuming it hasn't
430been set in the [children of I<article id>] section.
431
432=item template_dirs
433
434A comma-separated list of extra directories under $TMPLDIR to search
435for templates that can be used for articles at the given I<level>.
436
437=back
438
439=head2 [catalogs]
440
441=over
442
443=item template
444
445The default template for catalogs.
446
447=back
448
449=head2 [products]
450
451=over
452
453=item template
454
455The default template for products.
456
d64413ee
TC
457=item extra_templates
458
459A comma separated list of extra templates that can be used for
460products.
461
caa7299c
TC
462=back
463
61551101
TC
464=head2 [messages]
465
466This can be used to control translation of error messages. Each key
467has a prefix identifying the module that uses the error, followed by
468'/' followed by a specific identifier for the message.
469
470Message parameters, expressed as $I<digit>, are replaced with the
471parameters passed to the message. C<$$> is replaced with C<$>.
472
473Each message identifier below is documented with the id, when it
474occurs, the default message, and any parameters.
475
476=over
477
478=item user/needlogon
479
480the user attempted to logon without entering a logon name. Default:
481"Please enter a logon name". No parameters.
482
483=item user/needpass
484
485the user attempted to logon without entering a password. Default:
486"Please enter your password." No parameters.
487
488=item user/baduserpass
489
490the user's logon name or password was not found or did not match.
491Default: "Invalid user or password". No parameters.
492
493=item user/notloggedon
494
495the user attempted to logoff while not logged on. Default: "You
496aren't logged on". No parameters.
497
498=item user/optsoldpass
499
500the user entered a new password on the options page without entering
501their old password. Default: "You need to enter your old password to
502change your password". No parameters.
503
504=back
505
2404a911
TC
506=head2 [downloads]
507
508=over
509
510=item must_be_paid
511
512if non-zero, the order must be marked as paid for before the file can
513be downloaded.
514
515=item must_be_filled
516
517if non-zero the order must be marked as filled before the files can be
518downloaded.
519
4afdbb1b
TC
520=item require_logon
521
522if non-zero the user must be registered/logged on to download I<any>
523file.
524
2404a911
TC
525=back
526
b19047a6
TC
527=head2 [confirmations]
528
529Control over confirmation emails.
530
531=over
532
533=item subject
534
535The subject of email confirmation emails. Default: Subcription
536Confirmation.
537
538=item from
539
540The from field for the email. Default: $SHOP_FROM
541
542=back
543
531fb3bc
TC
544=head2 [subscriptions]
545
546Control over subscription messages.
547
548=over
549
550=item from
551
552The from field for the email. Default: $SHOP_FROM.
553
d09682dd
TC
554=item testname
555
556Default for the "Test Name" field for sending test subscription
557messages.
558
559=item testemail
560
561Default for the "Test Email" field for sending test subscription
562messages.
563
564=item testtextonly
565
566Set to 1 if you want the "Test Text Only" box checked by default for
567sending test subscription messages.
568
569=item testing
570
571Set to 0 to disable display of the test subscription messages portions
572of the subscriptions send form.
573
99b7cef0
TC
574=item text_link_inline
575
576Set to format links as they appear in the text version of emails.
577C<$1> is replaced with the title, C<$2> with the URL and C<$3> with
578the index. C<$$> is replaced with '$'. Default: C<$1 [$3]>
579
580=item text_link_list
581
582Set to format links as they appear at the footer of the body text. If
583this is set to the empty string then no list appears. C<$1>, C<$2>,
584C<$3>, C<$$> are replaced as for I<text_link_inline> and $n is
585replaced with newline. Default: C<[$3] $2>
586
587=item text_link_list_prefix
588
589A line of text produced above the list of URLs if there is one.
590Default: C<----->. $n in this is replaced with newlines.
591
531fb3bc
TC
592=back
593
99b7cef0
TC
594For example, if the configuration is:
595
596 text_link_inline="$1" ($3)
597 text_link_list_prefix=$n$n-------
598 text_link_list=($3) "$1"$n => $2
599
600and the body text is:
601
602 doclink[3]
603 link[http://www.example.com/|Example]
604
605the result will be:
606
607 "The Shop" (1)
608 "Example" (2)
609
610
611 -------
612 (1) "The Shop"
613 => http://www.yoursite.com/shop/index.html
614 (2) "Example"
615 => http://www.example.com/
616
6e3d2da5
TC
617=head2 [search]
618
619=over
620
621=item highlight_partial
622
623If this is true then partial matches will be highlight in search
624result excerpts. Default: True
625
54c97cf6
TC
626=item keep_inaccessible
627
628If this is true then resulting articles that can't be accessed by the
629user are listed in the search results. Default: false.
630
6e3d2da5
TC
631=back
632
61693c75
TC
633=head2 [search highlight]
634
635Sets the prefix and suffix used for highlighting matches for different
636fields.
637
638These are used by the highlight_result, excerpt, pageTitle, author,
639keywords and matchFile tags.
640
641Each field has a prefix and suffix entry. The key is
642I<fieldname>_prefix or I<fieldname>_suffix. For file fields this is
643file_I<fieldname}_prefix and file_I<fieldname}_suffix.
644
645The default prefix is <b>. The default suffix is </b>.
646
647For example you can do:
648
649 [search highlight]
650 body_prefix=<span class="searchfound">
651 body_suffix=</span>
652
6e3d2da5
TC
653=head2 [shop]
654
655=over
656
7b81711b
TC
657=item enabled
658
659Used by some templates to check if the shop is enabled. Set this to 1
660to enable the shop, or 0 to disable it.
661
57d988af
TC
662=item secureurl_articles
663
664If this is false then shop articles will not use the secureurl as their
665baseurl. Default: True
666
6e3d2da5
TC
667=item register_if_files
668
669If true the customer is required to register before checkout if there
670are any for sale files attached to products in the cart. Default: True
671
672=item require_logon
673
674If true the customer is required to be logged on before checkout,
675whether or not for sale files are attached to products in the cart.
676Default: False.
677
08123550
TC
678=item payment_types
679
680A comma-separated list of acceptable payment types. Default: 0
681
682The possible payment types are:
683
684=over
685
686=item *
687
6880 - the user enters a credit card number, name and expiry date
689
690=item *
691
6921 - the customer will send a cheque
693
694=item *
695
6962 - contact customer for details
697
698=back
699
81f3292d
TC
700Other types can be added by adding entries to the [payment type names]
701and [payment type descs] sections.
702
08123550
TC
703=item address1
704
705=item address2
706
707=item address3
708
709These are used by various shop templates to present an address that a
710cheque payment should be sent to.
711
331fd099
TC
712=item from
713
714From email address for emails sent by the shop. Overides $SHOP_FROM
715in Constants.pm
716
717=item to_name
718
719To name for emailed orders sent by the shop. Overrides $SHOP_TO_NAME
720in Constants.pm
721
722=item to_email
723
724To email for emailed orders sent by the shop. Overrides $SHOP_TO_EMAIL
725in Constants.pm
726
d09682dd
TC
727=item noencrypt
728
729If this is true then orders sent to you by the shop will not be
730encrypted. Enabling this disabled acceptance of credit card orders,
731and the default for C<payment_types> will become C<1> instead or C<0>.
732
733Please realize that other potentially commercially sensitive
734information is being sent in the clear to a central location,
735unencrypted.
736
737=item email_order
738
739If true, then the order is email to to_email, possibly with credit
740card information included. Default: $SHOP_EMAIL_ORDER.
741
d49f56a6
TC
742=item display_I<field>
743
744Used to translate the stored order field name into a presentation name
745suitable for error messages.
746
41e7c841
TC
747=item cardprocessor
748
749The name of a class to load to process credit card transactions online.
750
751Currently this can be either DevHelp::Payments::Test or
752DevHelp::Payments::Inpho.
753
26c634af
TC
754=item crypt_module
755
756Name of the encryption module to use. Default: $SHOP_CRYPTO.
757
758=item crypt_signing_id
759
760Id of the key to sign the order email with. If this is non-empty then
761the email is signed even if [basic].sign is false. Default:
762$SHOP_SIGNING_ID.
763
764=item crypt_gpg
765
766Path to the GnuPG program. Default: $SHOP_GPG
767
745a6c13 768=item crypt_passphrase
26c634af
TC
769
770Passphrase of the key used to sign the email. Default:
771$SHOP_PASSPHRASE.
772
745a6c13
TC
773=item show_card_type
774
775If true, request the card type when requesting credit card
776information. Default: False.
777
6e3d2da5
TC
778=back
779
41e7c841
TC
780=head2 [Shop Order Validation]
781
782This section can contain extra order validation information, including
783specifying required fields, display names and extra validation rules.
784
6e3d2da5
TC
785=head2 [fields]
786
787=over
788
789=item title_size
790
791The maximum length of the article title field. Default: 255. Should
792not be set higher than this unless you change the database schema.
793
794=back
795
ee6577c3
TC
796=head2 [interest]
797
798Controls the interest.pl script.
799
800=over
801
802=item notify
803
804Email address that is notified of the interest. Defaults to $SHOP_FROM.
805
ca9aa2bf 806=back
ee6577c3 807
6e3d2da5
TC
808=head2 [debug]
809
810Used for debugging.
811
812=over
813
814=item logon_cookies
815
816When a user logs on, and the site url is different to the secure url
817BSE attempts to refresh to the other "side" of the site to set the
818same cookie.
819
820BSE does some simple comparisons to attempt to determine whether the
821logon form was triggered on the secure side of the site (possibly from
822the shop) or on the insecure side. Since CGI doesn't necessarily give
823us all the information required, it's possible it will guess wrong.
824
d2730773
TC
825Setting this option to 1 will enable debugging information sent to
826standard error, which will be sent to the error log on Apache. This
827probably isn't useful on IIS.
828
829=item file_unlink
830
831Reports errors to STDERR (hence to the error log on Apache) if there
832is a problem deleting the actual file when an attached file is
833removed.
834
835=item mail_encryption
836
837Reports debugging information to standard error while encrypting your
838mail.
6e3d2da5 839
2d873eb6
TC
840=item cookies
841
842Reports cookies received from the browser and sent to the browser to
843STDERR (hence to the error log on Apache.)
844
4175638b
TC
845=item dump_session
846
847If nonzero the session hash is dumped to STDERR after it is retrived
848from the database.
849
af74f0b4
TC
850=item subscription_expiry
851
852If non-zero then subscription expiry date calculations are dumped to
853STDERR.
854
efcc5a30
TC
855=item jit_dynamic_regen
856
857If non-zero then information about jit_dynamic_regen is sent to
858STDERR.
859
db7d73a7
TC
860=item ifUserCan
861
862If non-zero then the ifUserCan tag will output some trace information
863to STDERR.
864
ca9aa2bf
TC
865=back
866
867=head2 [uri]
868
869Contains various URIs.
870
871This is underused, so don't rely on it yet.
872
873=over
874
875=item cgi
876
877The URI to the CGI directory. Default: /cgi-bin
878
879=item images
880
881The URI where images are kept. Default: /images
882
883=item shop
884
885=item articles
886
9168c88c 887=back
ca9aa2bf 888
9168c88c 889=head2 [articles]
ca9aa2bf 890
9168c88c
TC
891This will provide translations from symbolic names to article ids.
892
893Currently this is used for converting article ids in the access
894control code, and for looking up the id of the shop.
6e3d2da5 895
0b406a07
TC
896=head2 [printable type]
897
898If the user supplies a template name to printable.pl then you can use
899a different content type by adding an entry to this section. The key
900is the template name, and the value is the full content type.
901
918735d1
TC
902=head2 [search index scores]
903
904This section is used when generating the search index to override the
905default scores for each field in the articles.
906
907The default scores are:
908
74b21f6d
TC
909 Field Score Notes
910 ----- ----- -----
911 title 5
912 body 3
913 keyword 4
914 pageTitle 5
915 author 4
916 summary 0
917 description 0 Products only
918 product_code 0 Products only
919 file_displayName 2 displayName for files
920 file_description 2 description for files
921 file_notes 1 notes for files
918735d1
TC
922
923=head2 [article flags]
924
925=head2 [product flags]
926
927=head2 [catalog flags]
928
929Flags that can be set for articles, products and catalogs
930respectively. Note that flags for articles are also visible in
931products and catalogs.
932
933All flag Ids are single letters or digits. Uppercase letters are
934reserved for use by BSE internally, leaving lower-case letters and
935digits for your own use.
936
937Use the id of the flag as the key, and a description of the flag as
938it's value.
939
95989433
TC
940=head2 [article uris]
941
942Each key is an article id, the values are base URIs to store the HTML
943form of those articles and their children under.
944
945=head2 [protect link]
946
947The keys are ids of articles that shouldn't have their link field
948overwritten. The value should be a true value, but is otherwise
949ignored.
950
d09682dd
TC
951=head2 [datadump]
952
953=over
954
955=item to
956
957The recipient for the data dump email sent by datadump.pl. Default:
958$DATA_EMAIL.
959
960=item from
961
962the From for the data dump email sent by datadump.pl. Default:
963$SHOP_FROM.
964
965=back
966
2a295ea9
TC
967=head2 [site users]
968
969Configuration for site users.
970
971=over
972
973=item nopassword
974
975If this is set to true then no passwords are required during
976registration, a confirmation email is sent immediately upon
977registration and that confirmation email contains a link the user can
978use to manage their details.
979
980This option has some security concerns since it can leave links to the
981user's information in the browser history. This option is not
982recommended.
983
984You cannot use this to control access to the shop.
985
986=item require_name1
987
988=item require_name2
989
990=item require_address
991
992=item require_city
993
994=item require_state
995
996=item require_postcode
997
998=item require_telephone
999
1000=item require_facsimile
1001
1002=item require_country
1003
1004=item require_title
1005
1006=item require_organization
1007
1008Set these to true to require the corresponding field during
1009registration, and to keep it required after modification. Default:
1010false.
1011
1012If you enable any of these, you should enable C<info_on_register> as
1013well, or modify the registration template to include the given fields.
1014
1015=item display_I<field name>
1016
1017Controls how the given field is displayed in error messages. If you
1018change the field names on the registration and/or options forms you
1019should probably change them here too. Default: internal field name
1020with the first character converted to upper-case.
1021
1022=item info_on_register
1023
1024If this is set then the user info is prompted for during user
1025registration. The information still isn't required unless the
1026appropriate require_I<field> option is set. Default: false.
1027
1028=item register_refresh
1029
1030The default URL to refresh to on completing registration if no r
1031parameter is supplied.
1032
1033=item subscribe_all
1034
1035If this is set then the subcription checkboxes are all checked on
1036registration by default. Default: false.
1037
1038The user will only receive the subscriptions if they leave them checked
1039and follow the link in the confirmation email.
1040
1041=item subscribe_I<id>
1042
1043Where I<id> is the number identifying a subscription. If this is set
1044then the subscription checkbox for that subscription will be checked
1045by default on the registration form. Default: false.
1046
1047The user will only receive the subscriptions if they leave it checked
1048and follow the link in the confirmation email.
1049
1050You can get the I<id> of a subcription by looking at the Edit link on the
1051subscriptions management page, the number after "id=" is the id.
1052
9063386f
TC
1053=item billing_on_main_opts
1054
1055If set to zero then user billing options will be managed on a separate
1056page. This is controlled by the user/options_base.tmpl template.
1057
1058=item user_register
1059
1060If set to zero then users cannot register themselves. Default: true,
1061allowing users to register themselves.
1062
cf9f9cbc
TC
1063=item notify_register
1064
1065If true then an email is sent when a new user registers on your site.
1066The email address sent to is the first set of [site
1067users].notify_register_email, [shop].from or $SHOP_FROM from
1068Constants.pm
1069
1070No email is sent if a new user is created from the administration user
1071interface.
1072
1073See also: notify_register_email, notify_register_subject.
1074
1075=item notify_register_email
1076
1077The email to sent the registration notification too. See
1078notify_register above.
1079
1080=item notify_register_subject
1081
1082The subject of the notification email sent when a new user registers.
1083Any {I<field>} is replaced with the given field from the registered
1084user. See notify_register above.
1085
1086Default: New user {userId} registered
1087
2a295ea9
TC
1088=back
1089
81f3292d
TC
1090=head2 [payment type names]
1091
1092This section and [payment type descs] are used to configure new
1093paymeny type ids.
1094
1095The key is the integer representing the payment type. The value is
1096the name used in tags for checking the payment type.
1097
1098You can also add a description (currently unused) to [payment type
1099descs].
1100
1101You should use numbers starting from 10 to avoid conflicts with future
1102BSE payment types.
1103
1104=head2 [payment type descs]
1105
1106See [payment type names].
1107
1108=head2 [payment type required]
1109
1110Set the key given by the payment type id to a value of a
1111comma-separated list of fields required for that payment type.
1112
3ae524f3
TC
1113=head2 [help style I<style-name>]
1114
1115This type of configuration section is used to set values for a style
1116of help icon. Only the C<template> and C<prefix> values are used
1117directly by the code, the others are used by the default helpicon
1118templates.
1119
1120=over
1121
1122=item prefix
1123
1124The URI to the help files for this style. Default: /help/ in style
1125"user", /admin/help/ in style "admin".
1126
1127=item template
1128
1129The template used to produce the icon. Default: helpicon in style
1130user, admin/helpicon in style "admin".
1131
1132=item icon
1133
1134URI to the help icon image. Default: /images/admin/help.gif
1135
1136=item iconwidth
1137
1138The width of the help icon image. Default: 16
1139
1140=item iconheight
1141
1142The height of the help icon image. Default: 16
1143
1144=back
1145
1146If you just want to change the help icon image for user help icons you
1147might do:
1148
1149 [help style user]
1150 icon=/images/help.gif
1151
4175638b
TC
1152=head2 [affiliate]
1153
1154=over
1155
1156=item allowed_referer
1157
1158A semi-colon (;) separated list of referer domains that are allowed to
1159link to the C<a_set> target of L<affiliate.pl>.
1160
1161If the user's browser supplies a referer header then it will be
1162checked against this list.
1163
1164=item require_referer
1165
1166If this is set then the C<a_set> target of L<affiliate.pl> will
1167require that the user's browser supply a Referer header.
1168
1169=item default_refresh
1170
1171If no C<r> parameter is supplied to the C<a_set> target of
1172L<affiliate.pl> then this is used as the default refresh.
1173
1174Default: the site base url.
1175
829c9ed9
TC
1176=item subscription_required
1177
1178This is either the numeric or text of a subscription for which the
1179affiliate must have an active subscription.
1180
fdc2b7a2
TC
1181=item flag_required
1182
1183A single letter flag which the site administrator must set for the
1184affiliate page to be displayed for the given member.
1185
ea646070
TC
1186=item set_cookie
1187
1188If this is set then affiliate.pl will set the named cookie to the
1189affiliate id.
1190
1b5a718f
TC
1191=item other_cookies
1192
1193This is a comma-separated list of other cookies that should be set by
1194the a_set target. The values for the cookies should be passed to the
1195a_set target. For example with:
1196
1197 [affiliate]
1198 other_cookies=alpha,beta
1199
1200if the url:
1201
1202 http://your.site.com/cgi-bin/affiliate.pl?a_set=1&id=someid&alpha=1&beta=2&gamme=3
1203
1204is accessed, then the cookie alpha is set to "1", beta is set to "2".
1205The cookie gamma will not be set since it's not listed.
1206
ea646070
TC
1207=item linkbaseurl
1208
1209Used as the link base URL for the afflink.tmpl side bar template when
1210an affiliate id is set. Default: example.com
1211
1212=item linkbasedesc
1213
1214Used at the text of the link for the afflink.tmpl side bar template
1215when an affiliate id is set. Default: Your Site.
1216
1217=item linkdefurl
1218
1219Used as the link URL for the afflink.tmpl side bar template when an
1220affiliate id is not set. Default: example.com
1221
1222=item linkdefdesc
1223
1224Used as the text of the link for the afflink.tmpl side bar template
1225when an affiliate id is not set. Default: Our site
1226
4175638b
TC
1227=back
1228
3c32512d
TC
1229=head2 [BSE Siteuser Images]
1230
1231Each key is the id of a member image, with a corresponding [BSE
1232Siteuser Image I<image_id>] section. The values are ignored.
1233
1234=head2 [BSE Siteuser Image I<image_id>]
1235
1236Provides information about a single member image "template".
1237
1238=over
1239
1240=item description
1241
1242Short description on the image, like "Logo". Used in error messages.
1243
1244=item help
1245
1246Longer description of the image. Accessible with the member_image tag.
1247
1248=item minwidth
1249
1250=item minheight
1251
1252=item maxwidth
1253
1254=item maxheight
1255
1256The minimum and maximum dimensions of the image.
1257
1258=item widthsmallerror
1259
1260=item heightsmallerror
1261
1262=item widthlargeerror
1263
1264=item heightlargeerror
1265
1266Error messages displayed in the when the image is outside the
1267configured dimensions.
1268
1269=item largeerror
1270
1271=item smallerror
1272
1273Default error messages for the above.
1274
1275=item maxspace
1276
1277Maximum storage the image can use in bytes. Default: 1000000.
1278
1279=item spaceerror
1280
1281Error message displayed if the image uses too much storage.
1282
1283=back
1284
ab2cd916
TC
1285=head2 [editor]
1286
1287Various editor settings.
1288
1289=over
1290
1291=item allow_thumb
1292
1293If this is non-zero the system will attempt to load the configured
1294thumbnail class, and put thumbnail images on the image manager page
1295rather than full-size images. Default: off
1296
1297=item thumbs_class
1298
1299The name of a perl class that implement's BSE's thumbnail API. At
1300this point the only class that implements that is BSE::Thumb::Imager,
1301supplied with BSE. Default: None
1302
1303=item default_thumbnail
1304
1305URI to the default thumbnail image. This is presented when the
1306runtime production of a thumbnail image fails.
1307
1308=item default_thumbnail_width
1309
1310=item default_thumbnail_height
1311
1312Dimensions of the default thumbnail image.
1313
1314=item default_thumbnail_alt
1315
1316Alt text for the default thumbnail image.
1317
1761af79
TC
1318=item check_modified
1319
1320If this is true then BSE will check the value of the lastModified
1321parameter passed against the value in the article. If these don't
1322match the article isn't saved and is redisplayed with an error
1323message. This provides simple protection against one user saving
1324changes over those made by another.
1325
ab2cd916
TC
1326=back
1327
1328=head2 [thumbnails]
1329
1330=over
1331
1332=item max_width
1333
1334=item max_height
1335
1336=item max_pixels
1337
1338Default values for the thumbimage tag.
1339
1340=back
1341
829c9ed9
TC
1342=head2 [includes]
1343
1344Each value is used as the relative or absolute name of a file or
1345directory to load more configuration data from.
1346
1347The keywords must remain unique.
1348
1349Only the [includes] section from bse.cfg itself is used to locate more
1350configuration data.
1351
1352If the value references a directory, all files with an extension of
1353C<.cfg> are read for configuration data.
1354
1355The order the files are read (which later files overriding older
1356files) is:
1357
1358=over
1359
1360=item 1.
1361
1362bse.cfg is read
1363
1364=item 2.
1365
1366the entries in [includes] are sorted alphabetically (or rather
1367asciily), so an entry with key "A" is read before one with key "B",
1368one with key "01" is read before "02", but key "10" would be read
1369I<before> key "2".
1370
1371=item *
1372
1373if an entry is a file then that is read and the values merged.
1374
1375=item *
1376
1377if an entry is a directory, then that is scanned and the files found
1378read alphabetically as above.
1379
1380=back
1381
6a8a6ac5
TC
1382=head2 [error_img]
1383
1384This is used to configure the error icon displayed next to fields that
1385fail validation.
1386
1387=over
1388
1389=item image
1390
1391URI to the image file.
1392
1393=item width
1394
1395=item height
1396
1397The width and height of the error icon image.
1398
1399=back
1400
fdc2b7a2
TC
1401=head2 [site user flags]
1402
1403Flags that can be set for site users.
1404
1405All flag Ids are single letters or digits. Uppercase letters are
1406reserved for use by BSE internally, leaving lower-case letters and
1407digits for your own use.
1408
1409Use the id of the flag as the key, and a description of the flag as
1410it's value.
1411
deae2a52
TC
1412=head2 [article defaults]
1413
1414=head2 [catalog defaults]
1415
1416=head2 [product defaults]
1417
1418These sections contain defaults values for the corresponding article
1419types.
1420
1421Each key is the name of a column for the article type.
1422
1423If an entry is not found in [catalog defaults] then [article defaults]
1424is also checked.
1425
1426If an entry is not found in [product defaults] then [article defaults]
1427is also checked.
1428
1429These sections are checked B<after> the C<[children of >I<id>C<]> and
1430C<[level >I<level>C<]> sections.
1431
1432These defaults are used when creating an article where no value is
1433supplied, they can also be accessed via the <:default I<name>:> tag.
1434
1c3e5303
TC
1435=head2 [newsletter filters]
1436
1437Contains C<criteria>I<index> entries starting from C<criteria1>, then
1438C<criteria2>, etc.
1439
1440Each entry consists of a filter class name, followed by a ; followed
1441by data passed to that filter.
1442
1443 ; user the original SQL based filter, configured from
1444 ; section [foo]
1445 criteria1=BSE::NLFilter::SQL;foo
1446
1447See the documentation for each filter to configure the filters.
1448
c2096d67
TC
1449=head2 [Query Groups]
1450
1451The key of each entry is the numeric identifier of a query group, the
1452values are the name of the query group. For example:
1453
1454 [query groups]
1455 1=some name
1456
1457 [query group some name]
1458 sql=select id from site_users where id = ? and name1 like '%some%'
1459
1460Each entry also has a corresponding [Query Group I<name>] section.
1461
1462=head2 [query group I<name>]
1463
1464This section corresponds to an entry in [Query Groups].
1465
1466=over
1467
1468=item sql
1469
1470This is an SQL statement. One placeholder is required and is passed
1471the siteuser id (primary key) of the user to be checked. If this
1472query returns I<any> rows then the user is considered part of the
1473group.
1474
1475=back
1476
16901a2a
TC
1477=head2 [template types]
1478
1479Each key is a template name, the value is the content type to be used
1480when displaying the template dynamically.
1481
8f84f3f1
TC
1482=head2 [body class]
1483
1484This section defines CSS class names for BSE's body text link tags.
1485The key is the tag name, the value is the CSS class to be used.
1486
1487By default the class used is the same as the name of the tag, but you
1488can switch this off by adding an entry setting the class to the empty
1489string, for example:
1490
1491 ; no class attribute for any of the links
1492 [body class]
1493 link=
1494 poplink=
1495 doclink=
1496 popdoclink=
1497
1498You can set p here too to set the class for paragraphs generated as
1499body text. By default no class is set.
1500
def1a923
TC
1501=head2 [popimage]
1502
1503Controls the behaviour of the window displayed by the popimage[] body
1504text tag. If the Javascript for this has been customized then this
1505may not apply.
1506
1507=over
1508
1509=item extrawidth
1510
1511=item extraheight
1512
1513Extra width and height for the window beyond the size of the image.
1514Default: no extra width or height.
1515
1516=item popmiddle
1517
1518If set to non-zero popimage[] will attempt to centre the popup within
1519the current window. Default: 0.
1520
1521=back
1522
1523=over
1524
1525=back
1526
41e7c841
TC
1527=head2 [inpho]
1528
1529This is used to configure the DevHelp::Payments::Inpho module.
1530
1531=over
1532
1533=item test
1534
1535If this is set then the test parameters are used instead of the
1536product values.
1537
1538=item url
1539
1540The URL to process requests through.
1541
1542Default: https://extranet.inpho.com.au/cc_ssl/process
1543
1544=item user
1545
1546Inpho supplied user name.
1547
1548=item password
1549
1550Inpho supplied password.
1551
1552=item test_url
1553
1554The URL to process test requests through.
1555
1556=item test_user
1557
1558The user to supply to test requests.
1559
1560=item test_password
1561
1562The password to supply to test requests.
1563
1564=back
1565
f2bf0d11
TC
1566=head2 [custom]
1567
1568This section controls whether some custom class methods are called:
1569
1570=over
1571
1572=item saveopts
1573
1574If this is non-zero then siteuser_saveopts is called.
1575
1576=back
1577
0a66f55c
AO
1578=head2 [levelI<level> menus]
1579
1580Where I<level> is the article level at which the defined menu options will be available.
1581Configure each menu value and description as I<key> and I<value>.
1582
1583=over
1584
1585For example:
1586
1587 [level1 menus]
1588 0=Default
1589 1=Sidebar
1590 2=Footer
1591
1592To create a menus using such values, use the "allkids_of" iterator "filter" option.
1593
1594For example:
1595
1596 <:iterator begin allkids_of -1 filter: [menu] == 2 :>
1597
1598=back
1599
37726cc9
AO
1600=head2 [title alias]
1601
1602Enable the "titleAlias" article field and set which level it will be available.
1603
1604=over
1605
1606=item levelI<level>
1607
1608Where I<level> is the article "level" for which the "titleAlias" field should be enabled. To enable
1609set the value to non-zero.
1610
1611For example:
1612
1613 [title alias]
1614 level1=1
1615
1616The "titleAlias" can be used as an alternate "short" title for the given article, especially useful
1617for space critical iterated menus. A template conditional can be used to display the "titleAlias"
1618in place of the article "title" when appropriate.
1619
1620=back
1621
195977cd
TC
1622=head2 [thumb geometries]
1623
1624Each key represents a geometry identifier for use by the thumbimage[],
1625gthumbimage[] body text tags and the <:thumbimage ...:>, <:gthumbimage
b864cc90 1626...:>, <:dthumbimage ...:> template tags.
195977cd
TC
1627
1628The key is the geometry identifier, the value is the geometry string
1629as follows.
1630
1631The geometry string consists of:
1632
1633=over
1634
1635=item *
1636
1637dimensions
1638
1639=item *
1640
1641crop flag - if present
1642
1643=item *
1644
1645optional fill
1646
1647=back
1648
1649The dimensions can be in any of the following forms:
1650
1651=over
1652
1653=item *
1654
1655<width>x<height> - the desired maximum width and height. eg 200x150
1656
1657=item *
1658
1659<width>x - the desired width, with the height calculated
1660proportionally based on the source image size
1661
1662=item *
1663
1664x<height> - the designed height, with the width calculated
1665proportionally based on the source image size.
1666
1667=item *
1668
1669<size> - the desired maximum size in both directions. so "200" is
1670equivalent to "200x200"
1671
1672=back
1673
1674The crop flag is a single letter "c", if present then the image should
1675be scaled so the smaller dimension matches the requested size, and the
1676longer dimension will be cropped to fit.
1677
1678The fill if present is: fill(color) where color is a color recognized
1679by the underlying graphics implementation. This should be at least
1680hex web colors without the #, eg fill(FF0000) will fill with red.
1681
b864cc90
TC
1682=head2 [thumb classes]
1683
1684Each key represents a geometry identifier for use by the thumbimage[],
1685gthumbimage[] body text tags and the <:thumbimage ...:>, <:gthumbimage
1686...:>, <:dthumbimage ...:> template tags.
1687
1688The value is used as the class for the generated img tag.
1689
510a9ee7
TC
1690=head2 [targets]
1691
1692Each value represents a handler or script name for the <:dyntarget
1693I<script> I<target> ...:> tag.
1694
1695Each key has a TARGET version and a no-TARGET version, with the key
1696suffixed with C<_n>.
1697
1698The default C<nuser> target is C</cgi-bin/nuser.pl/user/TARGET>. The
1699default no-target C<nuser> is C</cgi-bin/nuser.pl/user>.
1700
1701For other targets the default is
1702C</cgi-bin/>I<script>C<.pl?a_TARGET=1> and
1703C</cgi-bin/>I<script>C<.pl>.
1704
1705The string C<TARGET> is replaced with the target specified in the
1706dyntarget tag.
1707
1708This, along with dyntarget is intended to allow a more "Web 2.0" type
1709of access to BSE. eg. you might set:
1710
1711 [targets]
1712 shop=/xshop/TARGET
1713 shop_x=/xshop/
1714
1715and have a rewrite rule:
1716
1717 RewriteRule ^/xshop/(.*)$ /cgi-bin/nuser.pl/shop/$1 [PT]
1718
8a153d74
TC
1719=head2 [popimage class I<classname>]
1720
1721This defines the settings for a class of images generated by the
1722popimage[] and gpopimage[] body text markup tags. For example, the
1723settings for C<popimage[imageid|foo]> can be found in section
1724C<[popimage class foo]>.
1725
1726=over
1727
1728=item html
1729
1730The html generated for this class. Tags of the form
1731C<{>I<identifier>C<}> are replaced, where I<identifier> can be
1732C<inline_> or C<outline_> followed by an image field name, for example
1733C<inline_src> is the URL to the inline image.
1734
1735Default: <a href="{outline_src}" rel="lightbox[id]" target="_blank"><img src="{inline_src}" alt="{inline_alt}" width="{inline_width}" height="{inline_height}" border="0" /></a>
1736
1737The default may be tuned as needed.
1738
1739=item inline
1740
1741The inline image geometry. Default: editor (the value used for
1742thumbnails on the admin side)
1743
1744=item outline
1745
1746The outline image geometry. If no value is supplied then the original
1747image values are used.
1748
1749=back
1750
61551101
TC
1751=head1 AUTHOR
1752
1753Tony Cook <tony@develop-help.com>
1754
1755=cut