fix a spelling error
[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
bf909925
TC
350=item warn_obsolete
351
352Some obsolete tags will warn to stderr if this is non-zero. Default:
353don't warn.
354
b19047a6
TC
355=back
356
357=head2 [mail]
358
35c0719f 359This section controls how BSE sends email.
b19047a6
TC
360
361=over
362
363=item smtp_server
364
365The host or IP address of your mail server. If this is not set
366C<sendmail> will be used instead. If this is set you must also set
367I<helo>.
368
369=item helo
370
371The name that BSE uses to identify itself when sending mail via SMTP.
372Required if I<smtp_server> is set.
373
374=item sendmail
375
376The path to the C<sendmail> binary. Default: /usr/lib/sendmail
377
378=item sendmail_opts
379
380The options supplied to sendmail. Default: -t -oi
381
382You may want to add the -odq option to this if you want mail queued
383rather than sent immediately.
384
67b69296
TC
385=item set_errors_to_from
386
387If true, we add an Errors-To header set to the same as the From
388header. Default: true.
389
0c2e7f7a
TC
390=item html_system_email
391
392If non-zero then emails sent via the compose mail system that aren't
393being sent to a member record, will be sent as HTML, if the HTML
394template is available.
395
61551101
TC
396=back
397
ca9aa2bf 398=head2 [children of I<id>]
721cd24c
TC
399
400Where I<id> is the identifier for an article.
401
402=over
403
404=item template
405
406the name of the default template for children of the given parent
407
408=item template_dirs
409
410a comma-separated list of extra directories under $TMPLDIR to search
411for templates that can be used for children of the given parent article.
412
413=back
414
ca9aa2bf
TC
415=head2 [article I<id>]
416
417Where I<id> is the identifier of an article.
418
419=over
420
421=item template_dirs
422
423A comma-separated list of extra directories under $TMPLDIR to search
424for templates that can be used for children of the given parent
425article.
426
427=item extra_templates
428
429A comma-separated list of extra templates under $TMPLDIR that can be
430used for the given article.
431
432=back
433
caa7299c
TC
434=head2 [level I<level>]
435
436=over
437
438=item template
439
440The default template for this level of article, assuming it hasn't
441been set in the [children of I<article id>] section.
442
443=item template_dirs
444
445A comma-separated list of extra directories under $TMPLDIR to search
446for templates that can be used for articles at the given I<level>.
447
448=back
449
450=head2 [catalogs]
451
452=over
453
454=item template
455
456The default template for catalogs.
457
458=back
459
460=head2 [products]
461
462=over
463
464=item template
465
466The default template for products.
467
d64413ee
TC
468=item extra_templates
469
470A comma separated list of extra templates that can be used for
471products.
472
caa7299c
TC
473=back
474
61551101
TC
475=head2 [messages]
476
477This can be used to control translation of error messages. Each key
478has a prefix identifying the module that uses the error, followed by
479'/' followed by a specific identifier for the message.
480
481Message parameters, expressed as $I<digit>, are replaced with the
482parameters passed to the message. C<$$> is replaced with C<$>.
483
484Each message identifier below is documented with the id, when it
485occurs, the default message, and any parameters.
486
487=over
488
489=item user/needlogon
490
491the user attempted to logon without entering a logon name. Default:
492"Please enter a logon name". No parameters.
493
494=item user/needpass
495
496the user attempted to logon without entering a password. Default:
497"Please enter your password." No parameters.
498
499=item user/baduserpass
500
501the user's logon name or password was not found or did not match.
502Default: "Invalid user or password". No parameters.
503
504=item user/notloggedon
505
506the user attempted to logoff while not logged on. Default: "You
507aren't logged on". No parameters.
508
509=item user/optsoldpass
510
511the user entered a new password on the options page without entering
512their old password. Default: "You need to enter your old password to
513change your password". No parameters.
514
515=back
516
2404a911
TC
517=head2 [downloads]
518
519=over
520
521=item must_be_paid
522
523if non-zero, the order must be marked as paid for before the file can
524be downloaded.
525
526=item must_be_filled
527
528if non-zero the order must be marked as filled before the files can be
529downloaded.
530
4afdbb1b
TC
531=item require_logon
532
533if non-zero the user must be registered/logged on to download I<any>
534file.
535
2404a911
TC
536=back
537
b19047a6
TC
538=head2 [confirmations]
539
540Control over confirmation emails.
541
542=over
543
544=item subject
545
546The subject of email confirmation emails. Default: Subcription
547Confirmation.
548
549=item from
550
551The from field for the email. Default: $SHOP_FROM
552
553=back
554
531fb3bc
TC
555=head2 [subscriptions]
556
557Control over subscription messages.
558
559=over
560
561=item from
562
563The from field for the email. Default: $SHOP_FROM.
564
d09682dd
TC
565=item testname
566
567Default for the "Test Name" field for sending test subscription
568messages.
569
570=item testemail
571
572Default for the "Test Email" field for sending test subscription
573messages.
574
575=item testtextonly
576
577Set to 1 if you want the "Test Text Only" box checked by default for
578sending test subscription messages.
579
580=item testing
581
582Set to 0 to disable display of the test subscription messages portions
583of the subscriptions send form.
584
99b7cef0
TC
585=item text_link_inline
586
587Set to format links as they appear in the text version of emails.
588C<$1> is replaced with the title, C<$2> with the URL and C<$3> with
589the index. C<$$> is replaced with '$'. Default: C<$1 [$3]>
590
591=item text_link_list
592
593Set to format links as they appear at the footer of the body text. If
594this is set to the empty string then no list appears. C<$1>, C<$2>,
595C<$3>, C<$$> are replaced as for I<text_link_inline> and $n is
596replaced with newline. Default: C<[$3] $2>
597
598=item text_link_list_prefix
599
600A line of text produced above the list of URLs if there is one.
601Default: C<----->. $n in this is replaced with newlines.
602
531fb3bc
TC
603=back
604
99b7cef0
TC
605For example, if the configuration is:
606
607 text_link_inline="$1" ($3)
608 text_link_list_prefix=$n$n-------
609 text_link_list=($3) "$1"$n => $2
610
611and the body text is:
612
613 doclink[3]
614 link[http://www.example.com/|Example]
615
616the result will be:
617
618 "The Shop" (1)
619 "Example" (2)
620
621
622 -------
623 (1) "The Shop"
624 => http://www.yoursite.com/shop/index.html
625 (2) "Example"
626 => http://www.example.com/
627
6e3d2da5
TC
628=head2 [search]
629
630=over
631
632=item highlight_partial
633
634If this is true then partial matches will be highlight in search
635result excerpts. Default: True
636
54c97cf6
TC
637=item keep_inaccessible
638
639If this is true then resulting articles that can't be accessed by the
640user are listed in the search results. Default: false.
641
6e3d2da5
TC
642=back
643
61693c75
TC
644=head2 [search highlight]
645
646Sets the prefix and suffix used for highlighting matches for different
647fields.
648
649These are used by the highlight_result, excerpt, pageTitle, author,
650keywords and matchFile tags.
651
652Each field has a prefix and suffix entry. The key is
653I<fieldname>_prefix or I<fieldname>_suffix. For file fields this is
654file_I<fieldname}_prefix and file_I<fieldname}_suffix.
655
656The default prefix is <b>. The default suffix is </b>.
657
658For example you can do:
659
660 [search highlight]
661 body_prefix=<span class="searchfound">
662 body_suffix=</span>
663
6e3d2da5
TC
664=head2 [shop]
665
666=over
667
7b81711b
TC
668=item enabled
669
670Used by some templates to check if the shop is enabled. Set this to 1
671to enable the shop, or 0 to disable it.
672
57d988af
TC
673=item secureurl_articles
674
675If this is false then shop articles will not use the secureurl as their
676baseurl. Default: True
677
6e3d2da5
TC
678=item register_if_files
679
680If true the customer is required to register before checkout if there
681are any for sale files attached to products in the cart. Default: True
682
683=item require_logon
684
685If true the customer is required to be logged on before checkout,
686whether or not for sale files are attached to products in the cart.
687Default: False.
688
08123550
TC
689=item payment_types
690
691A comma-separated list of acceptable payment types. Default: 0
692
693The possible payment types are:
694
695=over
696
697=item *
698
6990 - the user enters a credit card number, name and expiry date
700
701=item *
702
7031 - the customer will send a cheque
704
705=item *
706
7072 - contact customer for details
708
709=back
710
81f3292d
TC
711Other types can be added by adding entries to the [payment type names]
712and [payment type descs] sections.
713
08123550
TC
714=item address1
715
716=item address2
717
718=item address3
719
720These are used by various shop templates to present an address that a
721cheque payment should be sent to.
722
331fd099
TC
723=item from
724
725From email address for emails sent by the shop. Overides $SHOP_FROM
726in Constants.pm
727
728=item to_name
729
730To name for emailed orders sent by the shop. Overrides $SHOP_TO_NAME
731in Constants.pm
732
733=item to_email
734
735To email for emailed orders sent by the shop. Overrides $SHOP_TO_EMAIL
736in Constants.pm
737
d09682dd
TC
738=item noencrypt
739
740If this is true then orders sent to you by the shop will not be
741encrypted. Enabling this disabled acceptance of credit card orders,
742and the default for C<payment_types> will become C<1> instead or C<0>.
743
744Please realize that other potentially commercially sensitive
745information is being sent in the clear to a central location,
746unencrypted.
747
748=item email_order
749
750If true, then the order is email to to_email, possibly with credit
751card information included. Default: $SHOP_EMAIL_ORDER.
752
d49f56a6
TC
753=item display_I<field>
754
755Used to translate the stored order field name into a presentation name
756suitable for error messages.
757
41e7c841
TC
758=item cardprocessor
759
760The name of a class to load to process credit card transactions online.
761
762Currently this can be either DevHelp::Payments::Test or
763DevHelp::Payments::Inpho.
764
26c634af
TC
765=item crypt_module
766
767Name of the encryption module to use. Default: $SHOP_CRYPTO.
768
769=item crypt_signing_id
770
771Id of the key to sign the order email with. If this is non-empty then
772the email is signed even if [basic].sign is false. Default:
773$SHOP_SIGNING_ID.
774
775=item crypt_gpg
776
777Path to the GnuPG program. Default: $SHOP_GPG
778
745a6c13 779=item crypt_passphrase
26c634af
TC
780
781Passphrase of the key used to sign the email. Default:
782$SHOP_PASSPHRASE.
783
745a6c13
TC
784=item show_card_type
785
786If true, request the card type when requesting credit card
787information. Default: False.
788
56f87a80
TC
789=item cart_entry_limit
790
791Maximum number of entries in the cart. This limits the number of
792distinct products (with options) in the cart, not the total
793quantities. Default: Unlimited.
794
6e3d2da5
TC
795=back
796
41e7c841
TC
797=head2 [Shop Order Validation]
798
799This section can contain extra order validation information, including
800specifying required fields, display names and extra validation rules.
801
6e3d2da5
TC
802=head2 [fields]
803
804=over
805
806=item title_size
807
808The maximum length of the article title field. Default: 255. Should
809not be set higher than this unless you change the database schema.
810
811=back
812
ee6577c3
TC
813=head2 [interest]
814
815Controls the interest.pl script.
816
817=over
818
819=item notify
820
821Email address that is notified of the interest. Defaults to $SHOP_FROM.
822
ca9aa2bf 823=back
ee6577c3 824
6e3d2da5
TC
825=head2 [debug]
826
827Used for debugging.
828
829=over
830
831=item logon_cookies
832
833When a user logs on, and the site url is different to the secure url
834BSE attempts to refresh to the other "side" of the site to set the
835same cookie.
836
837BSE does some simple comparisons to attempt to determine whether the
838logon form was triggered on the secure side of the site (possibly from
839the shop) or on the insecure side. Since CGI doesn't necessarily give
840us all the information required, it's possible it will guess wrong.
841
d2730773
TC
842Setting this option to 1 will enable debugging information sent to
843standard error, which will be sent to the error log on Apache. This
844probably isn't useful on IIS.
845
846=item file_unlink
847
848Reports errors to STDERR (hence to the error log on Apache) if there
849is a problem deleting the actual file when an attached file is
850removed.
851
852=item mail_encryption
853
854Reports debugging information to standard error while encrypting your
855mail.
6e3d2da5 856
2d873eb6
TC
857=item cookies
858
859Reports cookies received from the browser and sent to the browser to
860STDERR (hence to the error log on Apache.)
861
4175638b
TC
862=item dump_session
863
864If nonzero the session hash is dumped to STDERR after it is retrived
865from the database.
866
af74f0b4
TC
867=item subscription_expiry
868
869If non-zero then subscription expiry date calculations are dumped to
870STDERR.
871
efcc5a30
TC
872=item jit_dynamic_regen
873
874If non-zero then information about jit_dynamic_regen is sent to
875STDERR.
876
db7d73a7
TC
877=item ifUserCan
878
879If non-zero then the ifUserCan tag will output some trace information
880to STDERR.
881
ca9aa2bf
TC
882=back
883
884=head2 [uri]
885
886Contains various URIs.
887
888This is underused, so don't rely on it yet.
889
890=over
891
892=item cgi
893
894The URI to the CGI directory. Default: /cgi-bin
895
896=item images
897
898The URI where images are kept. Default: /images
899
900=item shop
901
902=item articles
903
9168c88c 904=back
ca9aa2bf 905
9168c88c 906=head2 [articles]
ca9aa2bf 907
9168c88c
TC
908This will provide translations from symbolic names to article ids.
909
910Currently this is used for converting article ids in the access
911control code, and for looking up the id of the shop.
6e3d2da5 912
0b406a07
TC
913=head2 [printable type]
914
915If the user supplies a template name to printable.pl then you can use
916a different content type by adding an entry to this section. The key
917is the template name, and the value is the full content type.
918
918735d1
TC
919=head2 [search index scores]
920
921This section is used when generating the search index to override the
922default scores for each field in the articles.
923
924The default scores are:
925
74b21f6d
TC
926 Field Score Notes
927 ----- ----- -----
928 title 5
929 body 3
930 keyword 4
931 pageTitle 5
932 author 4
933 summary 0
934 description 0 Products only
935 product_code 0 Products only
936 file_displayName 2 displayName for files
937 file_description 2 description for files
938 file_notes 1 notes for files
918735d1
TC
939
940=head2 [article flags]
941
942=head2 [product flags]
943
944=head2 [catalog flags]
945
946Flags that can be set for articles, products and catalogs
947respectively. Note that flags for articles are also visible in
948products and catalogs.
949
950All flag Ids are single letters or digits. Uppercase letters are
951reserved for use by BSE internally, leaving lower-case letters and
952digits for your own use.
953
954Use the id of the flag as the key, and a description of the flag as
955it's value.
956
95989433
TC
957=head2 [article uris]
958
959Each key is an article id, the values are base URIs to store the HTML
960form of those articles and their children under.
961
962=head2 [protect link]
963
964The keys are ids of articles that shouldn't have their link field
965overwritten. The value should be a true value, but is otherwise
966ignored.
967
d09682dd
TC
968=head2 [datadump]
969
970=over
971
972=item to
973
974The recipient for the data dump email sent by datadump.pl. Default:
975$DATA_EMAIL.
976
977=item from
978
979the From for the data dump email sent by datadump.pl. Default:
980$SHOP_FROM.
981
982=back
983
2a295ea9
TC
984=head2 [site users]
985
986Configuration for site users.
987
988=over
989
990=item nopassword
991
992If this is set to true then no passwords are required during
993registration, a confirmation email is sent immediately upon
994registration and that confirmation email contains a link the user can
995use to manage their details.
996
997This option has some security concerns since it can leave links to the
998user's information in the browser history. This option is not
999recommended.
1000
1001You cannot use this to control access to the shop.
1002
1003=item require_name1
1004
1005=item require_name2
1006
1007=item require_address
1008
1009=item require_city
1010
1011=item require_state
1012
1013=item require_postcode
1014
1015=item require_telephone
1016
1017=item require_facsimile
1018
1019=item require_country
1020
1021=item require_title
1022
1023=item require_organization
1024
1025Set these to true to require the corresponding field during
1026registration, and to keep it required after modification. Default:
1027false.
1028
1029If you enable any of these, you should enable C<info_on_register> as
1030well, or modify the registration template to include the given fields.
1031
1032=item display_I<field name>
1033
1034Controls how the given field is displayed in error messages. If you
1035change the field names on the registration and/or options forms you
1036should probably change them here too. Default: internal field name
1037with the first character converted to upper-case.
1038
1039=item info_on_register
1040
1041If this is set then the user info is prompted for during user
1042registration. The information still isn't required unless the
1043appropriate require_I<field> option is set. Default: false.
1044
1045=item register_refresh
1046
1047The default URL to refresh to on completing registration if no r
1048parameter is supplied.
1049
1050=item subscribe_all
1051
1052If this is set then the subcription checkboxes are all checked on
1053registration by default. Default: false.
1054
1055The user will only receive the subscriptions if they leave them checked
1056and follow the link in the confirmation email.
1057
1058=item subscribe_I<id>
1059
1060Where I<id> is the number identifying a subscription. If this is set
1061then the subscription checkbox for that subscription will be checked
1062by default on the registration form. Default: false.
1063
1064The user will only receive the subscriptions if they leave it checked
1065and follow the link in the confirmation email.
1066
1067You can get the I<id> of a subcription by looking at the Edit link on the
1068subscriptions management page, the number after "id=" is the id.
1069
9063386f
TC
1070=item billing_on_main_opts
1071
1072If set to zero then user billing options will be managed on a separate
1073page. This is controlled by the user/options_base.tmpl template.
1074
1075=item user_register
1076
1077If set to zero then users cannot register themselves. Default: true,
1078allowing users to register themselves.
1079
cf9f9cbc
TC
1080=item notify_register
1081
1082If true then an email is sent when a new user registers on your site.
1083The email address sent to is the first set of [site
1084users].notify_register_email, [shop].from or $SHOP_FROM from
1085Constants.pm
1086
1087No email is sent if a new user is created from the administration user
1088interface.
1089
1090See also: notify_register_email, notify_register_subject.
1091
1092=item notify_register_email
1093
1094The email to sent the registration notification too. See
1095notify_register above.
1096
1097=item notify_register_subject
1098
1099The subject of the notification email sent when a new user registers.
1100Any {I<field>} is replaced with the given field from the registered
1101user. See notify_register above.
1102
1103Default: New user {userId} registered
1104
2a295ea9
TC
1105=back
1106
81f3292d
TC
1107=head2 [payment type names]
1108
1109This section and [payment type descs] are used to configure new
1110paymeny type ids.
1111
1112The key is the integer representing the payment type. The value is
1113the name used in tags for checking the payment type.
1114
1115You can also add a description (currently unused) to [payment type
1116descs].
1117
1118You should use numbers starting from 10 to avoid conflicts with future
1119BSE payment types.
1120
1121=head2 [payment type descs]
1122
1123See [payment type names].
1124
1125=head2 [payment type required]
1126
1127Set the key given by the payment type id to a value of a
1128comma-separated list of fields required for that payment type.
1129
3ae524f3
TC
1130=head2 [help style I<style-name>]
1131
1132This type of configuration section is used to set values for a style
1133of help icon. Only the C<template> and C<prefix> values are used
1134directly by the code, the others are used by the default helpicon
1135templates.
1136
1137=over
1138
1139=item prefix
1140
1141The URI to the help files for this style. Default: /help/ in style
1142"user", /admin/help/ in style "admin".
1143
1144=item template
1145
1146The template used to produce the icon. Default: helpicon in style
1147user, admin/helpicon in style "admin".
1148
1149=item icon
1150
1151URI to the help icon image. Default: /images/admin/help.gif
1152
1153=item iconwidth
1154
1155The width of the help icon image. Default: 16
1156
1157=item iconheight
1158
1159The height of the help icon image. Default: 16
1160
1161=back
1162
1163If you just want to change the help icon image for user help icons you
1164might do:
1165
1166 [help style user]
1167 icon=/images/help.gif
1168
4175638b
TC
1169=head2 [affiliate]
1170
1171=over
1172
1173=item allowed_referer
1174
1175A semi-colon (;) separated list of referer domains that are allowed to
1176link to the C<a_set> target of L<affiliate.pl>.
1177
1178If the user's browser supplies a referer header then it will be
1179checked against this list.
1180
1181=item require_referer
1182
1183If this is set then the C<a_set> target of L<affiliate.pl> will
1184require that the user's browser supply a Referer header.
1185
1186=item default_refresh
1187
1188If no C<r> parameter is supplied to the C<a_set> target of
1189L<affiliate.pl> then this is used as the default refresh.
1190
1191Default: the site base url.
1192
829c9ed9
TC
1193=item subscription_required
1194
1195This is either the numeric or text of a subscription for which the
1196affiliate must have an active subscription.
1197
fdc2b7a2
TC
1198=item flag_required
1199
1200A single letter flag which the site administrator must set for the
1201affiliate page to be displayed for the given member.
1202
ea646070
TC
1203=item set_cookie
1204
1205If this is set then affiliate.pl will set the named cookie to the
1206affiliate id.
1207
1b5a718f
TC
1208=item other_cookies
1209
1210This is a comma-separated list of other cookies that should be set by
1211the a_set target. The values for the cookies should be passed to the
1212a_set target. For example with:
1213
1214 [affiliate]
1215 other_cookies=alpha,beta
1216
1217if the url:
1218
1219 http://your.site.com/cgi-bin/affiliate.pl?a_set=1&id=someid&alpha=1&beta=2&gamme=3
1220
1221is accessed, then the cookie alpha is set to "1", beta is set to "2".
1222The cookie gamma will not be set since it's not listed.
1223
ea646070
TC
1224=item linkbaseurl
1225
1226Used as the link base URL for the afflink.tmpl side bar template when
1227an affiliate id is set. Default: example.com
1228
1229=item linkbasedesc
1230
1231Used at the text of the link for the afflink.tmpl side bar template
1232when an affiliate id is set. Default: Your Site.
1233
1234=item linkdefurl
1235
1236Used as the link URL for the afflink.tmpl side bar template when an
1237affiliate id is not set. Default: example.com
1238
1239=item linkdefdesc
1240
1241Used as the text of the link for the afflink.tmpl side bar template
1242when an affiliate id is not set. Default: Our site
1243
4175638b
TC
1244=back
1245
3c32512d
TC
1246=head2 [BSE Siteuser Images]
1247
1248Each key is the id of a member image, with a corresponding [BSE
1249Siteuser Image I<image_id>] section. The values are ignored.
1250
1251=head2 [BSE Siteuser Image I<image_id>]
1252
1253Provides information about a single member image "template".
1254
1255=over
1256
1257=item description
1258
1259Short description on the image, like "Logo". Used in error messages.
1260
1261=item help
1262
1263Longer description of the image. Accessible with the member_image tag.
1264
1265=item minwidth
1266
1267=item minheight
1268
1269=item maxwidth
1270
1271=item maxheight
1272
1273The minimum and maximum dimensions of the image.
1274
1275=item widthsmallerror
1276
1277=item heightsmallerror
1278
1279=item widthlargeerror
1280
1281=item heightlargeerror
1282
1283Error messages displayed in the when the image is outside the
1284configured dimensions.
1285
1286=item largeerror
1287
1288=item smallerror
1289
1290Default error messages for the above.
1291
1292=item maxspace
1293
1294Maximum storage the image can use in bytes. Default: 1000000.
1295
1296=item spaceerror
1297
1298Error message displayed if the image uses too much storage.
1299
1300=back
1301
ab2cd916
TC
1302=head2 [editor]
1303
1304Various editor settings.
1305
1306=over
1307
1308=item allow_thumb
1309
1310If this is non-zero the system will attempt to load the configured
1311thumbnail class, and put thumbnail images on the image manager page
1312rather than full-size images. Default: off
1313
1314=item thumbs_class
1315
1316The name of a perl class that implement's BSE's thumbnail API. At
1317this point the only class that implements that is BSE::Thumb::Imager,
1318supplied with BSE. Default: None
1319
1320=item default_thumbnail
1321
1322URI to the default thumbnail image. This is presented when the
1323runtime production of a thumbnail image fails.
1324
1325=item default_thumbnail_width
1326
1327=item default_thumbnail_height
1328
1329Dimensions of the default thumbnail image.
1330
1331=item default_thumbnail_alt
1332
1333Alt text for the default thumbnail image.
1334
1761af79
TC
1335=item check_modified
1336
1337If this is true then BSE will check the value of the lastModified
1338parameter passed against the value in the article. If these don't
1339match the article isn't saved and is redisplayed with an error
1340message. This provides simple protection against one user saving
1341changes over those made by another.
1342
ab2cd916
TC
1343=back
1344
1345=head2 [thumbnails]
1346
1347=over
1348
1349=item max_width
1350
1351=item max_height
1352
1353=item max_pixels
1354
1355Default values for the thumbimage tag.
1356
1357=back
1358
829c9ed9
TC
1359=head2 [includes]
1360
1361Each value is used as the relative or absolute name of a file or
1362directory to load more configuration data from.
1363
1364The keywords must remain unique.
1365
1366Only the [includes] section from bse.cfg itself is used to locate more
1367configuration data.
1368
1369If the value references a directory, all files with an extension of
1370C<.cfg> are read for configuration data.
1371
1372The order the files are read (which later files overriding older
1373files) is:
1374
1375=over
1376
1377=item 1.
1378
1379bse.cfg is read
1380
1381=item 2.
1382
1383the entries in [includes] are sorted alphabetically (or rather
1384asciily), so an entry with key "A" is read before one with key "B",
1385one with key "01" is read before "02", but key "10" would be read
1386I<before> key "2".
1387
1388=item *
1389
1390if an entry is a file then that is read and the values merged.
1391
1392=item *
1393
1394if an entry is a directory, then that is scanned and the files found
1395read alphabetically as above.
1396
1397=back
1398
6a8a6ac5
TC
1399=head2 [error_img]
1400
1401This is used to configure the error icon displayed next to fields that
1402fail validation.
1403
1404=over
1405
1406=item image
1407
1408URI to the image file.
1409
1410=item width
1411
1412=item height
1413
1414The width and height of the error icon image.
1415
1416=back
1417
fdc2b7a2
TC
1418=head2 [site user flags]
1419
1420Flags that can be set for site users.
1421
1422All flag Ids are single letters or digits. Uppercase letters are
1423reserved for use by BSE internally, leaving lower-case letters and
1424digits for your own use.
1425
1426Use the id of the flag as the key, and a description of the flag as
1427it's value.
1428
deae2a52
TC
1429=head2 [article defaults]
1430
1431=head2 [catalog defaults]
1432
1433=head2 [product defaults]
1434
1435These sections contain defaults values for the corresponding article
1436types.
1437
1438Each key is the name of a column for the article type.
1439
1440If an entry is not found in [catalog defaults] then [article defaults]
1441is also checked.
1442
1443If an entry is not found in [product defaults] then [article defaults]
1444is also checked.
1445
1446These sections are checked B<after> the C<[children of >I<id>C<]> and
1447C<[level >I<level>C<]> sections.
1448
1449These defaults are used when creating an article where no value is
1450supplied, they can also be accessed via the <:default I<name>:> tag.
1451
1c3e5303
TC
1452=head2 [newsletter filters]
1453
1454Contains C<criteria>I<index> entries starting from C<criteria1>, then
1455C<criteria2>, etc.
1456
1457Each entry consists of a filter class name, followed by a ; followed
1458by data passed to that filter.
1459
1460 ; user the original SQL based filter, configured from
1461 ; section [foo]
1462 criteria1=BSE::NLFilter::SQL;foo
1463
1464See the documentation for each filter to configure the filters.
1465
c2096d67
TC
1466=head2 [Query Groups]
1467
1468The key of each entry is the numeric identifier of a query group, the
1469values are the name of the query group. For example:
1470
1471 [query groups]
1472 1=some name
1473
1474 [query group some name]
1475 sql=select id from site_users where id = ? and name1 like '%some%'
1476
1477Each entry also has a corresponding [Query Group I<name>] section.
1478
1479=head2 [query group I<name>]
1480
1481This section corresponds to an entry in [Query Groups].
1482
1483=over
1484
1485=item sql
1486
1487This is an SQL statement. One placeholder is required and is passed
1488the siteuser id (primary key) of the user to be checked. If this
1489query returns I<any> rows then the user is considered part of the
1490group.
1491
1492=back
1493
16901a2a
TC
1494=head2 [template types]
1495
1496Each key is a template name, the value is the content type to be used
1497when displaying the template dynamically.
1498
8f84f3f1
TC
1499=head2 [body class]
1500
1501This section defines CSS class names for BSE's body text link tags.
1502The key is the tag name, the value is the CSS class to be used.
1503
1504By default the class used is the same as the name of the tag, but you
1505can switch this off by adding an entry setting the class to the empty
1506string, for example:
1507
1508 ; no class attribute for any of the links
1509 [body class]
1510 link=
1511 poplink=
1512 doclink=
1513 popdoclink=
1514
1515You can set p here too to set the class for paragraphs generated as
1516body text. By default no class is set.
1517
def1a923
TC
1518=head2 [popimage]
1519
1520Controls the behaviour of the window displayed by the popimage[] body
1521text tag. If the Javascript for this has been customized then this
1522may not apply.
1523
1524=over
1525
1526=item extrawidth
1527
1528=item extraheight
1529
1530Extra width and height for the window beyond the size of the image.
1531Default: no extra width or height.
1532
1533=item popmiddle
1534
1535If set to non-zero popimage[] will attempt to centre the popup within
1536the current window. Default: 0.
1537
1538=back
1539
1540=over
1541
1542=back
1543
41e7c841
TC
1544=head2 [inpho]
1545
1546This is used to configure the DevHelp::Payments::Inpho module.
1547
1548=over
1549
1550=item test
1551
1552If this is set then the test parameters are used instead of the
1553product values.
1554
1555=item url
1556
1557The URL to process requests through.
1558
1559Default: https://extranet.inpho.com.au/cc_ssl/process
1560
1561=item user
1562
1563Inpho supplied user name.
1564
1565=item password
1566
1567Inpho supplied password.
1568
1569=item test_url
1570
1571The URL to process test requests through.
1572
1573=item test_user
1574
1575The user to supply to test requests.
1576
1577=item test_password
1578
1579The password to supply to test requests.
1580
1581=back
1582
f2bf0d11
TC
1583=head2 [custom]
1584
1585This section controls whether some custom class methods are called:
1586
1587=over
1588
1589=item saveopts
1590
1591If this is non-zero then siteuser_saveopts is called.
1592
1593=back
1594
0a66f55c
AO
1595=head2 [levelI<level> menus]
1596
1597Where I<level> is the article level at which the defined menu options will be available.
1598Configure each menu value and description as I<key> and I<value>.
1599
1600=over
1601
1602For example:
1603
1604 [level1 menus]
1605 0=Default
1606 1=Sidebar
1607 2=Footer
1608
1609To create a menus using such values, use the "allkids_of" iterator "filter" option.
1610
1611For example:
1612
1613 <:iterator begin allkids_of -1 filter: [menu] == 2 :>
1614
1615=back
1616
37726cc9
AO
1617=head2 [title alias]
1618
1619Enable the "titleAlias" article field and set which level it will be available.
1620
1621=over
1622
1623=item levelI<level>
1624
1625Where I<level> is the article "level" for which the "titleAlias" field should be enabled. To enable
1626set the value to non-zero.
1627
1628For example:
1629
1630 [title alias]
1631 level1=1
1632
1633The "titleAlias" can be used as an alternate "short" title for the given article, especially useful
1634for space critical iterated menus. A template conditional can be used to display the "titleAlias"
1635in place of the article "title" when appropriate.
1636
1637=back
1638
195977cd
TC
1639=head2 [thumb geometries]
1640
1641Each key represents a geometry identifier for use by the thumbimage[],
1642gthumbimage[] body text tags and the <:thumbimage ...:>, <:gthumbimage
b864cc90 1643...:>, <:dthumbimage ...:> template tags.
195977cd
TC
1644
1645The key is the geometry identifier, the value is the geometry string
1646as follows.
1647
1648The geometry string consists of:
1649
1650=over
1651
1652=item *
1653
1654dimensions
1655
1656=item *
1657
1658crop flag - if present
1659
1660=item *
1661
1662optional fill
1663
1664=back
1665
1666The dimensions can be in any of the following forms:
1667
1668=over
1669
1670=item *
1671
1672<width>x<height> - the desired maximum width and height. eg 200x150
1673
1674=item *
1675
1676<width>x - the desired width, with the height calculated
1677proportionally based on the source image size
1678
1679=item *
1680
1681x<height> - the designed height, with the width calculated
1682proportionally based on the source image size.
1683
1684=item *
1685
1686<size> - the desired maximum size in both directions. so "200" is
1687equivalent to "200x200"
1688
1689=back
1690
1691The crop flag is a single letter "c", if present then the image should
1692be scaled so the smaller dimension matches the requested size, and the
1693longer dimension will be cropped to fit.
1694
1695The fill if present is: fill(color) where color is a color recognized
1696by the underlying graphics implementation. This should be at least
1697hex web colors without the #, eg fill(FF0000) will fill with red.
1698
b864cc90
TC
1699=head2 [thumb classes]
1700
1701Each key represents a geometry identifier for use by the thumbimage[],
1702gthumbimage[] body text tags and the <:thumbimage ...:>, <:gthumbimage
1703...:>, <:dthumbimage ...:> template tags.
1704
1705The value is used as the class for the generated img tag.
1706
510a9ee7
TC
1707=head2 [targets]
1708
1709Each value represents a handler or script name for the <:dyntarget
1710I<script> I<target> ...:> tag.
1711
1712Each key has a TARGET version and a no-TARGET version, with the key
1713suffixed with C<_n>.
1714
1715The default C<nuser> target is C</cgi-bin/nuser.pl/user/TARGET>. The
1716default no-target C<nuser> is C</cgi-bin/nuser.pl/user>.
1717
1718For other targets the default is
1719C</cgi-bin/>I<script>C<.pl?a_TARGET=1> and
1720C</cgi-bin/>I<script>C<.pl>.
1721
1722The string C<TARGET> is replaced with the target specified in the
1723dyntarget tag.
1724
1725This, along with dyntarget is intended to allow a more "Web 2.0" type
1726of access to BSE. eg. you might set:
1727
1728 [targets]
1729 shop=/xshop/TARGET
1730 shop_x=/xshop/
1731
1732and have a rewrite rule:
1733
1734 RewriteRule ^/xshop/(.*)$ /cgi-bin/nuser.pl/shop/$1 [PT]
1735
8a153d74
TC
1736=head2 [popimage class I<classname>]
1737
1738This defines the settings for a class of images generated by the
1739popimage[] and gpopimage[] body text markup tags. For example, the
1740settings for C<popimage[imageid|foo]> can be found in section
1741C<[popimage class foo]>.
1742
1743=over
1744
1745=item html
1746
1747The html generated for this class. Tags of the form
1748C<{>I<identifier>C<}> are replaced, where I<identifier> can be
1749C<inline_> or C<outline_> followed by an image field name, for example
1750C<inline_src> is the URL to the inline image.
1751
1752Default: <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>
1753
1754The default may be tuned as needed.
1755
1756=item inline
1757
1758The inline image geometry. Default: editor (the value used for
1759thumbnails on the admin side)
1760
1761=item outline
1762
1763The outline image geometry. If no value is supplied then the original
1764image values are used.
1765
1766=back
1767
0c2e7f7a
TC
1768=head2 [mail resources]
1769
1770Each key is the identifier of a file that can be attached to
1771BSE::ComposeMail emails. The value is comma separated filename,
1772content type, inline status.
1773
1774The files are searched for through the template search mechanism, so
1775the filename can be relative to either the master or local templates
1776directories.
1777
1778If the content type is not supplied, if the filename end in gif, png
1779or jpg the appropriate content type is used, otherwise
1780application/octet-stream.
1781
1782If the inline status is not supplied then images are considered
1783inline, and other files arent.
1784
61551101
TC
1785=head1 AUTHOR
1786
1787Tony Cook <tony@develop-help.com>
1788
1789=cut