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