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