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