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