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