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