t10edit.t now cleans up the article it creates
[bse.git] / site / docs / config.pod
CommitLineData
981d07ba 1
61551101
TC
2=head1 NAME
3
4config.pod - documents BSE configuration file options
5
6=head1 DESCRIPTION
7
8BSE historically used Constants.pm to keep most configuration
9information. The plan is to make sure any new configuration is kept
10in bse.cfg, and to slowly move most configuration information into
11bse.cfg.
12
13Keeping configuration information in Constants.pm makes it difficult
14to perform upgrades and makes it impossible to use tools such as
15mod_perl, at least if you want more than one site on the machine.
16
71721575
TC
17F<bse.cfg> is read as a utf-8 encoded file.
18
61551101
TC
19=head1 CONFIGURATION ENTRIES
20
41f10371
TC
21=head2 [site]
22
23Contains URL configuration for the site.
24
25=over
26
27=item url
28
29The normal URL for the non-secure parts of the site.
30
31=item secureurl
32
33The secure URL for the shop, products and other portions of the site
34that should use SSL. This isn't checked to make sure it is https.
35
36=item name
37
38Used as the site "name" in a few places.
39
40=item adminurl
41
42If set, this is used as the base URL for accessing the administrative
43functions of your site.
44
45=item secureadmin
46
47Ignored if C<adminurl> is set.
48
49If this is true then C<secureurl> is used as the base URL for
50accessing the administrative functions of your site, otherwise C<url>
51is used as the base URL. Default: false (C<url>'s value is used)
52
c5f849c7
TC
53=item forward_from
54
55Configure the IP address of one or more front-end proxies. This can
56be a regular expression except that C<.> is translated to C<\.> and
57C<*> is tranlated to C<.*> to give more glob() like matching.
58
59If the reqesting host matches then admin site URL matching is done
60against HTTP_X_FORWARDED_SERVER instead of SERVER_NAME.
61
62Default: no front-end server configured.
63
f13d1b43
TC
64=item secret
65
66A secret used (currently) for hashing cookie values passed between the
67secure and non-secure parts of the site. This must be set. A
68suitable value can be created with:
69
70 openssl rand -base64 32
71
41f10371
TC
72=back
73
61551101
TC
74=head2 [paths]
75
76Contains various file system paths.
77
78=over
79
80=item downloads
81
82This is where the files uploads with the file wizard are stored. It
83must be writable by the web server user.
84
85=item admin_templates
86
87Directory containing administrative templates. Note: this is not
88completely implemented for now, so assume the default. Default: admin
89directory under $TMPLDIR.
90
91=item templates
92
02d87eea
TC
93Directory base for most templates. This can contain references like
94$(section/key) to other configuration entries. Split on the systems
95PATH separators (run: perl -V:path_sep)
aefcabcb
TC
96
97=item local_templates
98
99Local Directory base for templates. This is searched before the
02d87eea
TC
100templates directory. This can contain references like $(section/key)
101to other configuration entries. Split on the system's PATH separator.
61551101 102
5abe2da5
TC
103=item public_html
104
105Web server document root. Static pages are generated under this
106directory. Default: $CONTENTBASE.
107
ca9aa2bf
TC
108=item images
109
110Where uploaded images are stored. This is not yet completely
111implemented. Default: $IMAGEDIR.
112
331fd099
TC
113=item libraries
114
115Local search path for BSE::Custom, or the class configured by
116C<custom_class> in [basic].
117
3c32512d
TC
118=item siteuser_images
119
120Where uploaded siteuser images are stored. This must be set in the
121config file. The default bse.cfg include an entry to use the current
122values of [paths].downloads
123
efcc5a30
TC
124=item dynamic_cache
125
126Pregenerated dynamic article pages are stored here. This must be
127defined if you site contains any dynamicly generated pages.
128
195977cd
TC
129=item scalecache
130
131The directory where cached versions of scaled thumbnails are stored.
132Defaults to image_dir/scaled. This must be in the document tree. If
133you set this you should also set scalecacheurl.
134
135=item scalecacheurl
136
137The URL to the directory represented by scalecache. Defaults to
138/images/scaled.
139
61551101
TC
140=back
141
142=head2 [extensions]
143
144This section is used by the file wizard to map uploaded file
145extensions to MIME content types. This can be used to extend
146BSE::FileEditor's internal extension map. It cannot override that
147map.
148
149The key for each entry is the extension, without the leading '.'.
150
151eg.
152
153 xls = application/msexcel
154
155=head2 [templates]
156
157Used for translating symbolic template names into full names under the
158template directory.
159
160In each case the default is the name with a C<.tmpl> extension.
161
162=over
163
164=item user/logon
165
166user logon page
167
168=item user/register
169
170user registration page
171
172=back
173
174=head2 [admin templates]
175
176Used for translating the names of administration templates into filenames.
177
178In each case the default is the name with a C<.tmpl> extension.
179
180=over
181
182=item filelist
183
184article file wizard
185
d2730773
TC
186=item catalog
187
188Catalog editor page. Default admin/edit_catalog.tmpl
189
190=item 1
191
192=item 2
193
194=item 3
195
196=item 4
197
198=item 5
199
200Article edit pages. Default admin/edit_<number>.tmpl
201
202=item steps
203
204Step child/parent management page. Default admin/edit_steps.tmpl
205
61551101
TC
206=back
207
208=head2 [html]
209
210Minor html items.
211
212=over
213
214=item charset
215
216The value of the charset keyword when outputting HTML from a script.
217Set to the empty string to suppress the charset keyword. Default:
218iso-8859-1.
219
5af99440
TC
220=item redirect_links
221
222If this is a non-zero number, then all but mailto links are redirected
223to C<nuser.pl/redirect> so you can display a diclaimer. If this
224contained alphabetics it's treated as a comma separated list of url
225schemes that should be handled via C<nuser.pl/redirect>. If 0 or not
226present, no redirection is done.
227
228The redirect URL includes a hash of the url, title and the redirect
229salt to prevent using this mechanism by external sites for cookie
230stealing attacks.
231
232=item redirect_salt
233
234The salt used in generating the has for redirect_links. Default: an
235empty string.
236
8a3b8db8
TC
237=item validate
238
239If non-zero then any HTML output is validated with HTML::Tidy.
240Validation errors and warnings are sent to the audit log. See [html
241tidy].
242
61551101
TC
243=back
244
245=head2 [basic]
246
247=over
248
1fd96ec5 249=item access_control
61551101 250
1fd96ec5
TC
251If this is true then the user/group/permissions database is used to
252control access to the system. Default: False.
61551101 253
1fd96ec5 254=item access_filter_parents
a8ddb0f3 255
1fd96ec5
TC
256If this is true, then the drop-down lists of possible parents on the
257newsletter edit pages are filtered for access control.
258Default: False.
a8ddb0f3 259
1fd96ec5 260=item access_filter_steps
3c8b9c2c 261
1fd96ec5
TC
262If this is true, then the drop-down lists of possible stepparents and
263stepchildren on the article edit pages are filtered for access control.
264Default: False.
3c8b9c2c 265
1fd96ec5 266=item alias_prefix
61551101 267
1fd96ec5
TC
268The prefix applied to articles that use a linkAlias url. This should
269start with a /.
61551101 270
1fd96ec5 271=item alias_recursive
b19047a6 272
1fd96ec5
TC
273If this is non-zero then the link is formed by the C<alias_prefix>,
274followed by slash (C</>) separated aliases from the ancestors starting
275from the section, followed by the C<alias_suffix>. You may need to
276change your redirect handling if you enable this. Default: Off.
b19047a6 277
1fd96ec5 278=item alias_suffix
6e3d2da5 279
1fd96ec5
TC
280If this is non-zero then the title is cleaned up (all but
281alphanumerics removed) and appended to the alias URL generated.
6e3d2da5 282
61eae5af
TC
283=item all_dynamic
284
285If true then all articles are treated as dynamic. Default: false.
286
1fd96ec5 287=item auto_images
ca9aa2bf 288
1fd96ec5
TC
289By default, if the author doesn't use any image tags, BSE will insert
290any unnamed article images into the body text of an article. You can
291disable this on a per-article basis in the image tool, or disable it
292globally by setting C<auto_images> to 0.
ca9aa2bf 293
1fd96ec5
TC
294An alternative is to set C<imagePos> in C<[article defaults]> to
295C<xx> which will default articles to not auto-inserting images.
9168c88c 296
1fd96ec5 297=item cache_templates
9168c88c 298
1fd96ec5
TC
299If true, BSE will cache compiled templates using the configured BSE
300cache, if any. Depending on the configured cache this may slow things
301down. Default: disabled.
147e99e8 302
1fd96ec5 303=item cache_templates_locally
147e99e8 304
1fd96ec5
TC
305If true, BSE will cache compiled templates in memory. This may
306significantly improve performance but may increase memory use.
307Default: disabled.
444957b9 308
1fd96ec5 309=item cache_thumbnails
444957b9 310
1fd96ec5
TC
311If set to zero the results of the thumbimage/gthumbimage body/template
312tags will not be cached. Default: 1 (caching is enabled).
d49f56a6 313
1fd96ec5 314=item cookie_domain
d49f56a6 315
1fd96ec5
TC
316This overrides the domain value set for cookies. This is useful if
317you allow the site to run under both example.com and www.example.com,
318if you set cookie_domain to example.com then a user visiting
319www.example.com will still have their cookies when they visit
320example.com.
9168c88c 321
1fd96ec5
TC
322=item cookie_lifetime
323
324The expiry time for cookies. This should be in the form supported by
325CGI.pm for the -expires parameter. Typically you want a plus ('+'), a
326number, and a time character (s - seconds, m - minutes, h - hours, d -
327days, M - months). Default: +3h
328
329=item cookie_name
330
331This overrides the cookie name used to store the session id. Default:
332sessionid. This is useful when you have 2 sites under the same
333top-level domain, and helps disambiguate the cookie returned by the
334browser.
9168c88c 335
331fd099
TC
336=item custom_class
337
338The name of the custom class for your site. This is currently only
339used for article editing customizations. This class should derive
340from BSE::CustomBase. Default: BSE::Custom.
341
1fd96ec5 342=item default_popupimage
74b21f6d 343
1fd96ec5
TC
344This is the default popup image class for the popimage[] and
345gpopimage[] tags. Default: popup.
74b21f6d 346
1fd96ec5 347=item dynamic_access_filter
195977cd 348
1fd96ec5
TC
349If set to 0, dynamic article iterators will no access control filter
350their results. Default: 1.
195977cd 351
1fd96ec5 352=item http_only_session
b902f9de 353
1fd96ec5
TC
354If this is non-zero, the default, the session cookie sent to the
355browser has the C<HttpOnly> attribute set. This can prevent session
356cookie hijacking. Default: 1.
b902f9de 357
1fd96ec5 358=item htusers
73e6b73a 359
1fd96ec5
TC
360This should be the path to a file to be updated with the list of users
361and crypt() versions of their passwords. If this is set then the
362security system will check for a user set by the browser before
363attempting a form based logon. Default: None.
73e6b73a 364
1fd96ec5 365=item index_file
73e6b73a 366
1fd96ec5
TC
367The name of the file to generate for static articles when the link is
368terminated by "/". Default: C<index.html>.
73e6b73a 369
1fd96ec5 370=item jit_dynamic_pregen
73e6b73a 371
1fd96ec5
TC
372If this is true, then pre-generation for dynamic pages will be delayed
373until the page is displayed to a user. Default: off.
73e6b73a 374
1fd96ec5 375=item link_titles
cddcd8c0 376
1fd96ec5
TC
377If this is true then the links to your articles within BSE will be
378followed by a / and then by a simplified version of the article title.
379The aim is to include at least some title information in the URL
380without modifying the name of the HTML file. Default: False.
cddcd8c0 381
1fd96ec5 382=item make_userid_cookie
8a153d74 383
1fd96ec5
TC
384If this is non-zero, the default, then when the site member logs in, a
385javascript visible cookie, C<userid> will be set that contains the
386login name of the user. BSE's back-end doesn't use this cookie, its
387only use is for Javascript to enable/disable user interface elements.
388Default: 1.
8a153d74 389
1fd96ec5 390=item minpassword
bf909925 391
1fd96ec5 392Minimum password length in characters. Default: 4.
bf909925 393
3f36e485
TC
394=item no_cache_dynamic
395
396If non-zero, the default, dynamic responses will include a
397C<Cache-Control: no-cache> header. This can be overridden for
398articles via , article flags, C<[template >
399I<templatename>C<].no_cache_dynamic> and [article].no_cache_dynamic.
400Default: 1.
401
1fd96ec5 402=item preload_template
80f59f40 403
1fd96ec5
TC
404Preload the named template, searching the template search part. Any
405text that would normally be produced by the preloaded template is
406ignored. This can be useful for common definitions and variables for
407use in many templates. Default: none.
4cf6a60c 408
1fd96ec5 409=item randomdata
4cf6a60c 410
1fd96ec5
TC
411Device to read random data from. This device should not block when it
412runs out of entropy.
4cf6a60c 413
1fd96ec5 414=item redir_to_alias
dbe8a12a 415
1fd96ec5
TC
416If true then page.pl will 301 redirect (Moved Permanently) requests
417for an article by its id to the generated link if the article has a
418link alias. Default: false. Must only be used with use_alias true.
dbe8a12a
TC
419
420=item secure_session
421
422If this is non-zero then the session cookie sent to the browser has
423the C<Secure> attribute set. This means that the cookie will only be
424visible over https. This is only useful when the only URL the site is
425visited over is a https URL. Default: 0.
426
1fd96ec5 427=item server_auth
dbe8a12a 428
1fd96ec5
TC
429Set this to non-zero to enable authentication via server
430authentication (usually Basic Authentication.) You should normally
431set this if you set htusers below. Default: 0 (disabled)
dbe8a12a 432
1fd96ec5 433=item sign
81aa5f57 434
1fd96ec5
TC
435If this is true then the encrypted messages containing the customer's
436credit card number are sent to the shop owner signed. To avoid
437keeping a passphrase and signing key on the server you can set this to
438false (0). This has the effect that anyone could send you an unsigned
439message encrypted with your public key, though this may not be a
440security threat. Default: True.
81aa5f57 441
1fd96ec5 442=item staticajax
981d07ba 443
1fd96ec5 444If true, the ifAjax and ajax tags will be active for static pages.
981d07ba 445
1fd96ec5 446=item static_thumbnails
58f0ca94 447
1fd96ec5
TC
448If true and cache_thumbnails is true then thumbnails for the thumbnail
449cache will be generated when a static page is regenerated, and the
450link from the page will link to the image in the cache rather than to
451C<thumb.pl>. Default: 1 (static thumbnails enabled).
fd5a7c54 452
1fd96ec5 453=item track_uploads
fd5a7c54 454
1fd96ec5
TC
455If this is non-zero, and a cache is configured (see [cache]), file
456uploads are tracked in entries in the cache.
58f0ca94 457
1fd96ec5
TC
458The fileprogress.pl script can be called by Ajax to display file
459upload progress information to the user. The upload state is updated
460a maximum of once a second.
755fd5f3 461
1fd96ec5 462=item use_alias
755fd5f3 463
1fd96ec5
TC
464If this is non-zero then an article with linkAlias set will use an
465alias url instead of the "real" url. You will need to configure a
466RewriteRule or ErrorDocument to page.pl to direct the user to the
467correct URL. Default: 1.
1e60d3c4 468
1fd96ec5 469=item warn_obsolete
1e60d3c4 470
1fd96ec5
TC
471Some obsolete tags will warn to stderr if this is non-zero. Default:
472don't warn.
1e60d3c4 473
b19047a6
TC
474=back
475
476=head2 [mail]
477
35c0719f 478This section controls how BSE sends email.
b19047a6
TC
479
480=over
481
482=item smtp_server
483
484The host or IP address of your mail server. If this is not set
485C<sendmail> will be used instead. If this is set you must also set
486I<helo>.
487
488=item helo
489
490The name that BSE uses to identify itself when sending mail via SMTP.
491Required if I<smtp_server> is set.
492
493=item sendmail
494
495The path to the C<sendmail> binary. Default: /usr/lib/sendmail
496
497=item sendmail_opts
498
499The options supplied to sendmail. Default: -t -oi
500
501You may want to add the -odq option to this if you want mail queued
502rather than sent immediately.
503
67b69296
TC
504=item set_errors_to_from
505
506If true, we add an Errors-To header set to the same as the From
507header. Default: true.
508
0c2e7f7a
TC
509=item html_system_email
510
511If non-zero then emails sent via the compose mail system that aren't
512being sent to a member record, will be sent as HTML, if the HTML
513template is available.
514
295deb8d
TC
515=item inline_css
516
517If this is C<style> (the default) then use CSS::Inliner to attempt to
518inline CSS in mail if the text "<style" is found in the generated
519HTML.
520
521If this is C<force> then we always attempt to inline CSS.
522
523If this is any other value then don't inline CSS.
524
5a892458
TC
525=item inline_css_flags
526
527A comma separated list of flags to supply to CSS::Inliner->new().
528Reasonable flags are C<strip_attrs> to strip C<id> and C<class>
529attributes, and C<leave_style> to leave the HTML style block in place.
530
531Default: no flags.
532
295deb8d
TC
533=item inline_css_report
534
535If this is true and CSS inlining fails, log an error to the audit
536log. This is intended for use in debugging and should be disabled in
537production. Default: false (disabled)
538
61551101
TC
539=back
540
ca9aa2bf 541=head2 [children of I<id>]
721cd24c
TC
542
543Where I<id> is the identifier for an article.
544
545=over
546
547=item template
548
549the name of the default template for children of the given parent
550
551=item template_dirs
552
553a comma-separated list of extra directories under $TMPLDIR to search
554for templates that can be used for children of the given parent article.
555
556=back
557
ca9aa2bf
TC
558=head2 [article I<id>]
559
560Where I<id> is the identifier of an article.
561
562=over
563
564=item template_dirs
565
566A comma-separated list of extra directories under $TMPLDIR to search
567for templates that can be used for children of the given parent
568article.
569
570=item extra_templates
571
572A comma-separated list of extra templates under $TMPLDIR that can be
573used for the given article.
574
575=back
576
caa7299c
TC
577=head2 [level I<level>]
578
579=over
580
581=item template
582
583The default template for this level of article, assuming it hasn't
584been set in the [children of I<article id>] section.
585
586=item template_dirs
587
588A comma-separated list of extra directories under $TMPLDIR to search
589for templates that can be used for articles at the given I<level>.
590
591=back
592
593=head2 [catalogs]
594
595=over
596
597=item template
598
599The default template for catalogs.
600
601=back
602
603=head2 [products]
604
605=over
606
607=item template
608
609The default template for products.
610
d64413ee
TC
611=item extra_templates
612
613A comma separated list of extra templates that can be used for
614products.
615
caa7299c
TC
616=back
617
61551101
TC
618=head2 [messages]
619
620This can be used to control translation of error messages. Each key
621has a prefix identifying the module that uses the error, followed by
622'/' followed by a specific identifier for the message.
623
624Message parameters, expressed as $I<digit>, are replaced with the
625parameters passed to the message. C<$$> is replaced with C<$>.
626
627Each message identifier below is documented with the id, when it
628occurs, the default message, and any parameters.
629
630=over
631
632=item user/needlogon
633
634the user attempted to logon without entering a logon name. Default:
635"Please enter a logon name". No parameters.
636
637=item user/needpass
638
639the user attempted to logon without entering a password. Default:
640"Please enter your password." No parameters.
641
642=item user/baduserpass
643
644the user's logon name or password was not found or did not match.
645Default: "Invalid user or password". No parameters.
646
647=item user/notloggedon
648
649the user attempted to logoff while not logged on. Default: "You
650aren't logged on". No parameters.
651
652=item user/optsoldpass
653
654the user entered a new password on the options page without entering
655their old password. Default: "You need to enter your old password to
656change your password". No parameters.
657
a53374d2
TC
658=item shop/logonrequired
659
660Displayed if the user attempts to checkout when [shop].require_logon
661is true.
662
61551101
TC
663=back
664
2404a911
TC
665=head2 [downloads]
666
667=over
668
669=item must_be_paid
670
671if non-zero, the order must be marked as paid for before the file can
672be downloaded.
673
674=item must_be_filled
675
676if non-zero the order must be marked as filled before the files can be
677downloaded.
678
4afdbb1b
TC
679=item require_logon
680
681if non-zero the user must be registered/logged on to download I<any>
682file.
683
32696f84
TC
684=item log_downufile
685
686if non-zero, downloads of userfiles will be logged. Default: 0
687
688=item log_downufile_maxage
689
690the maximum age of entries in the user file download log, in days.
691Default: 30.
692
2404a911
TC
693=back
694
b19047a6
TC
695=head2 [confirmations]
696
697Control over confirmation emails.
698
699=over
700
701=item subject
702
703The subject of email confirmation emails. Default: Subcription
704Confirmation.
705
706=item from
707
708The from field for the email. Default: $SHOP_FROM
709
710=back
711
531fb3bc
TC
712=head2 [subscriptions]
713
714Control over subscription messages.
715
716=over
717
718=item from
719
720The from field for the email. Default: $SHOP_FROM.
721
d09682dd
TC
722=item testname
723
724Default for the "Test Name" field for sending test subscription
725messages.
726
727=item testemail
728
729Default for the "Test Email" field for sending test subscription
730messages.
731
732=item testtextonly
733
734Set to 1 if you want the "Test Text Only" box checked by default for
735sending test subscription messages.
736
737=item testing
738
739Set to 0 to disable display of the test subscription messages portions
740of the subscriptions send form.
741
99b7cef0
TC
742=item text_link_inline
743
744Set to format links as they appear in the text version of emails.
745C<$1> is replaced with the title, C<$2> with the URL and C<$3> with
746the index. C<$$> is replaced with '$'. Default: C<$1 [$3]>
747
748=item text_link_list
749
750Set to format links as they appear at the footer of the body text. If
751this is set to the empty string then no list appears. C<$1>, C<$2>,
752C<$3>, C<$$> are replaced as for I<text_link_inline> and $n is
753replaced with newline. Default: C<[$3] $2>
754
755=item text_link_list_prefix
756
757A line of text produced above the list of URLs if there is one.
758Default: C<----->. $n in this is replaced with newlines.
759
531fb3bc
TC
760=back
761
99b7cef0
TC
762For example, if the configuration is:
763
764 text_link_inline="$1" ($3)
765 text_link_list_prefix=$n$n-------
766 text_link_list=($3) "$1"$n => $2
767
768and the body text is:
769
770 doclink[3]
771 link[http://www.example.com/|Example]
772
773the result will be:
774
775 "The Shop" (1)
776 "Example" (2)
777
778
779 -------
780 (1) "The Shop"
781 => http://www.yoursite.com/shop/index.html
782 (2) "Example"
783 => http://www.example.com/
784
6e3d2da5
TC
785=head2 [search]
786
787=over
788
789=item highlight_partial
790
791If this is true then partial matches will be highlight in search
792result excerpts. Default: True
793
54c97cf6
TC
794=item keep_inaccessible
795
796If this is true then resulting articles that can't be accessed by the
797user are listed in the search results. Default: false.
798
d401b996
TC
799=item wordre
800
801The default regular expression used to match words in text during
802indexing. Default: \w+
803
804=item wordre_I<fieldname>
805
806The field specific word match regular expression for the built-in
807search indexer. Default: the value of C<wordre>.
808
65ad6c28
TC
809=item indexer
810
811Module used to build the search index. Default: BSE::Index::BSE.
812
813=item index_priority
814
815For C<BSE::Index::BSE>, the optimization priority. The default of
816C<speed> builds the index in memory and is very fast, but can consume
817a lot of memory. Otherwise, set this to C<memory> to reduce memory
818usage.
819
820C<memory> priority index building requires that the DBM::Deep module
821be installed.
822
289f5a78
TC
823=item level
824
825Articles with a higher level than this are indexed as their ancestor.
826Default: C<$SEARCH_LEVEL> which defaults to 5.
827
6e3d2da5
TC
828=back
829
61693c75
TC
830=head2 [search highlight]
831
832Sets the prefix and suffix used for highlighting matches for different
833fields.
834
835These are used by the highlight_result, excerpt, pageTitle, author,
836keywords and matchFile tags.
837
838Each field has a prefix and suffix entry. The key is
839I<fieldname>_prefix or I<fieldname>_suffix. For file fields this is
a9634cc9 840file_I<fieldname>_prefix and file_I<fieldname>_suffix.
61693c75
TC
841
842The default prefix is <b>. The default suffix is </b>.
843
844For example you can do:
845
846 [search highlight]
847 body_prefix=<span class="searchfound">
848 body_suffix=</span>
849
6e3d2da5
TC
850=head2 [shop]
851
852=over
853
7b81711b
TC
854=item enabled
855
856Used by some templates to check if the shop is enabled. Set this to 1
857to enable the shop, or 0 to disable it.
858
57d988af
TC
859=item secureurl_articles
860
861If this is false then shop articles will not use the secureurl as their
862baseurl. Default: True
863
6e3d2da5
TC
864=item register_if_files
865
866If true the customer is required to register before checkout if there
867are any for sale files attached to products in the cart. Default: True
868
869=item require_logon
870
871If true the customer is required to be logged on before checkout,
872whether or not for sale files are attached to products in the cart.
873Default: False.
874
08123550
TC
875=item payment_types
876
877A comma-separated list of acceptable payment types. Default: 0
878
879The possible payment types are:
880
881=over
882
883=item *
884
8850 - the user enters a credit card number, name and expiry date
886
887=item *
888
8891 - the customer will send a cheque
890
891=item *
892
8932 - contact customer for details
894
13a986ee
TC
895=item *
896
40cc2f24 8974 - paypal - see L<paypal.pod>
13a986ee 898
08123550
TC
899=back
900
81f3292d
TC
901Other types can be added by adding entries to the [payment type names]
902and [payment type descs] sections.
903
08123550
TC
904=item address1
905
906=item address2
907
908=item address3
909
910These are used by various shop templates to present an address that a
911cheque payment should be sent to.
912
331fd099
TC
913=item from
914
915From email address for emails sent by the shop. Overides $SHOP_FROM
916in Constants.pm
917
918=item to_name
919
920To name for emailed orders sent by the shop. Overrides $SHOP_TO_NAME
921in Constants.pm
922
923=item to_email
924
925To email for emailed orders sent by the shop. Overrides $SHOP_TO_EMAIL
926in Constants.pm
927
d9a3fa87
TC
928=item bcc_email
929
930BCC email address for order confirmation emails sent to the customer.
931Default: No bcc.
932
d09682dd
TC
933=item noencrypt
934
935If this is true then orders sent to you by the shop will not be
936encrypted. Enabling this disabled acceptance of credit card orders,
937and the default for C<payment_types> will become C<1> instead or C<0>.
938
939Please realize that other potentially commercially sensitive
940information is being sent in the clear to a central location,
941unencrypted.
942
943=item email_order
944
945If true, then the order is email to to_email, possibly with credit
946card information included. Default: $SHOP_EMAIL_ORDER.
947
d49f56a6
TC
948=item display_I<field>
949
950Used to translate the stored order field name into a presentation name
951suitable for error messages.
952
41e7c841
TC
953=item cardprocessor
954
955The name of a class to load to process credit card transactions online.
956
957Currently this can be either DevHelp::Payments::Test or
958DevHelp::Payments::Inpho.
959
26c634af
TC
960=item crypt_module
961
962Name of the encryption module to use. Default: $SHOP_CRYPTO.
963
964=item crypt_signing_id
965
966Id of the key to sign the order email with. If this is non-empty then
967the email is signed even if [basic].sign is false. Default:
968$SHOP_SIGNING_ID.
969
970=item crypt_gpg
971
972Path to the GnuPG program. Default: $SHOP_GPG
973
745a6c13 974=item crypt_passphrase
26c634af
TC
975
976Passphrase of the key used to sign the email. Default:
977$SHOP_PASSPHRASE.
978
745a6c13
TC
979=item show_card_type
980
981If true, request the card type when requesting credit card
982information. Default: False.
983
56f87a80
TC
984=item cart_entry_limit
985
986Maximum number of entries in the cart. This limits the number of
987distinct products (with options) in the cart, not the total
988quantities. Default: Unlimited.
989
d99ed4c4 990=item currency_code
13a986ee
TC
991
992The shop currency as a 3-letter currency code. Default: AUD.
993Currencies other than "AUD" aren't supported by most of the system.
994
40cc2f24
TC
995=item country_code
996
997Set to non-zero if you're using country codes in the order country
998field. If this is set then the delivCountry is supplied as is to
999various parts of the system, otherwise it is translated from a country
1000name to a country code. Default: 0.
1001
c4f18087
TC
1002=item require_fields
1003
1004A comma separated list of extra fields to require during checkout.
1005This is in addition to the usual fields required during checkout.
1006Default: none.
1007
1008=item require_delivery
1009
1010If true, and the C<need_delivery> CGI parameter is true, treat the
94522840
TC
1011following delivery fields as required during checkout: delivFirstName,
1012delivLastName, delivStreet, delivSuburb, delivPostCode and delivCountry.
1013Default: true.
c4f18087
TC
1014
1015=item require_delivery_fields
1016
1017If C<require_delivery> is true, and the C<need_delivery> CGI parameter
1018is true, add the comma separated fields listed here to the required
1019checkout fields list. Default: none.
1020
6e3d2da5
TC
1021=back
1022
bd3a048c
AMS
1023=head2 [shipping]
1024
1025=over
1026
1027=item couriers
1028
1029A space-separated list of modules under Courier::, e.g. "Fastway::Road
1030AustraliaPost::Air". These will be made available as shipping methods
1031on the checkout page.
1032
1033=item sourcepostcode
1034
1035The post code from which products are shipped.
1036
1037=item fastwayfranchisee
1038
1039The name of the Fastway franchisee used to ship products from the
1040sourcepostcode.
1041
1042=item fastwayfranchiseecode
1043
1044The Fastway franchisee code for the customer, if any.
1045
1046=back
1047
41e7c841
TC
1048=head2 [Shop Order Validation]
1049
1050This section can contain extra order validation information, including
1051specifying required fields, display names and extra validation rules.
1052
6e3d2da5
TC
1053=head2 [fields]
1054
1055=over
1056
1057=item title_size
1058
1059The maximum length of the article title field. Default: 255. Should
1060not be set higher than this unless you change the database schema.
1061
1062=back
1063
ee6577c3
TC
1064=head2 [interest]
1065
1066Controls the interest.pl script.
1067
1068=over
1069
1070=item notify
1071
1072Email address that is notified of the interest. Defaults to $SHOP_FROM.
1073
ca9aa2bf 1074=back
ee6577c3 1075
6e3d2da5
TC
1076=head2 [debug]
1077
1078Used for debugging.
1079
1080=over
1081
1082=item logon_cookies
1083
1084When a user logs on, and the site url is different to the secure url
1085BSE attempts to refresh to the other "side" of the site to set the
1086same cookie.
1087
1088BSE does some simple comparisons to attempt to determine whether the
1089logon form was triggered on the secure side of the site (possibly from
1090the shop) or on the insecure side. Since CGI doesn't necessarily give
1091us all the information required, it's possible it will guess wrong.
1092
d2730773
TC
1093Setting this option to 1 will enable debugging information sent to
1094standard error, which will be sent to the error log on Apache. This
1095probably isn't useful on IIS.
1096
1097=item file_unlink
1098
1099Reports errors to STDERR (hence to the error log on Apache) if there
1100is a problem deleting the actual file when an attached file is
1101removed.
1102
1103=item mail_encryption
1104
1105Reports debugging information to standard error while encrypting your
1106mail.
6e3d2da5 1107
2d873eb6
TC
1108=item cookies
1109
1110Reports cookies received from the browser and sent to the browser to
1111STDERR (hence to the error log on Apache.)
1112
4175638b
TC
1113=item dump_session
1114
1115If nonzero the session hash is dumped to STDERR after it is retrived
1116from the database.
1117
af74f0b4
TC
1118=item subscription_expiry
1119
1120If non-zero then subscription expiry date calculations are dumped to
1121STDERR.
1122
efcc5a30
TC
1123=item jit_dynamic_regen
1124
1125If non-zero then information about jit_dynamic_regen is sent to
1126STDERR.
1127
db7d73a7
TC
1128=item ifUserCan
1129
1130If non-zero then the ifUserCan tag will output some trace information
1131to STDERR.
1132
ca9aa2bf
TC
1133=back
1134
1135=head2 [uri]
1136
1137Contains various URIs.
1138
1139This is underused, so don't rely on it yet.
1140
1141=over
1142
1143=item cgi
1144
1145The URI to the CGI directory. Default: /cgi-bin
1146
1147=item images
1148
1149The URI where images are kept. Default: /images
1150
1151=item shop
1152
1153=item articles
1154
9168c88c 1155=back
ca9aa2bf 1156
9168c88c 1157=head2 [articles]
ca9aa2bf 1158
9168c88c
TC
1159This will provide translations from symbolic names to article ids.
1160
1161Currently this is used for converting article ids in the access
1162control code, and for looking up the id of the shop.
6e3d2da5 1163
0b406a07
TC
1164=head2 [printable type]
1165
1166If the user supplies a template name to printable.pl then you can use
1167a different content type by adding an entry to this section. The key
1168is the template name, and the value is the full content type.
1169
918735d1
TC
1170=head2 [search index scores]
1171
1172This section is used when generating the search index to override the
1173default scores for each field in the articles.
1174
1175The default scores are:
1176
74b21f6d
TC
1177 Field Score Notes
1178 ----- ----- -----
1179 title 5
1180 body 3
1181 keyword 4
1182 pageTitle 5
1183 author 4
1184 summary 0
1185 description 0 Products only
1186 product_code 0 Products only
1187 file_displayName 2 displayName for files
1188 file_description 2 description for files
1189 file_notes 1 notes for files
918735d1
TC
1190
1191=head2 [article flags]
1192
1193=head2 [product flags]
1194
1195=head2 [catalog flags]
1196
1197Flags that can be set for articles, products and catalogs
1198respectively. Note that flags for articles are also visible in
1199products and catalogs.
1200
1201All flag Ids are single letters or digits. Uppercase letters are
1202reserved for use by BSE internally, leaving lower-case letters and
1203digits for your own use.
1204
1205Use the id of the flag as the key, and a description of the flag as
1206it's value.
1207
95989433
TC
1208=head2 [article uris]
1209
1210Each key is an article id, the values are base URIs to store the HTML
1211form of those articles and their children under.
1212
1213=head2 [protect link]
1214
1215The keys are ids of articles that shouldn't have their link field
1216overwritten. The value should be a true value, but is otherwise
1217ignored.
1218
d09682dd
TC
1219=head2 [datadump]
1220
1221=over
1222
1223=item to
1224
1225The recipient for the data dump email sent by datadump.pl. Default:
1226$DATA_EMAIL.
1227
1228=item from
1229
1230the From for the data dump email sent by datadump.pl. Default:
1231$SHOP_FROM.
1232
1233=back
1234
2a295ea9
TC
1235=head2 [site users]
1236
1237Configuration for site users.
1238
1239=over
1240
1241=item nopassword
1242
1243If this is set to true then no passwords are required during
1244registration, a confirmation email is sent immediately upon
1245registration and that confirmation email contains a link the user can
1246use to manage their details.
1247
1248This option has some security concerns since it can leave links to the
1249user's information in the browser history. This option is not
1250recommended.
1251
1252You cannot use this to control access to the shop.
1253
1254=item require_name1
1255
1256=item require_name2
1257
b27af108 1258=item require_street
2a295ea9 1259
b27af108 1260=item require_suburb
2a295ea9
TC
1261
1262=item require_state
1263
1264=item require_postcode
1265
1266=item require_telephone
1267
1268=item require_facsimile
1269
1270=item require_country
1271
1272=item require_title
1273
1274=item require_organization
1275
1276Set these to true to require the corresponding field during
1277registration, and to keep it required after modification. Default:
1278false.
1279
1280If you enable any of these, you should enable C<info_on_register> as
1281well, or modify the registration template to include the given fields.
1282
1283=item display_I<field name>
1284
1285Controls how the given field is displayed in error messages. If you
1286change the field names on the registration and/or options forms you
1287should probably change them here too. Default: internal field name
1288with the first character converted to upper-case.
1289
1290=item info_on_register
1291
1292If this is set then the user info is prompted for during user
1293registration. The information still isn't required unless the
1294appropriate require_I<field> option is set. Default: false.
1295
1296=item register_refresh
1297
1298The default URL to refresh to on completing registration if no r
1299parameter is supplied.
1300
1301=item subscribe_all
1302
1303If this is set then the subcription checkboxes are all checked on
1304registration by default. Default: false.
1305
1306The user will only receive the subscriptions if they leave them checked
1307and follow the link in the confirmation email.
1308
1309=item subscribe_I<id>
1310
1311Where I<id> is the number identifying a subscription. If this is set
1312then the subscription checkbox for that subscription will be checked
1313by default on the registration form. Default: false.
1314
1315The user will only receive the subscriptions if they leave it checked
1316and follow the link in the confirmation email.
1317
1318You can get the I<id> of a subcription by looking at the Edit link on the
1319subscriptions management page, the number after "id=" is the id.
1320
9063386f
TC
1321=item billing_on_main_opts
1322
1323If set to zero then user billing options will be managed on a separate
1324page. This is controlled by the user/options_base.tmpl template.
1325
1326=item user_register
1327
1328If set to zero then users cannot register themselves. Default: true,
1329allowing users to register themselves.
1330
cf9f9cbc
TC
1331=item notify_register
1332
1333If true then an email is sent when a new user registers on your site.
1334The email address sent to is the first set of [site
1335users].notify_register_email, [shop].from or $SHOP_FROM from
1336Constants.pm
1337
1338No email is sent if a new user is created from the administration user
1339interface.
1340
1341See also: notify_register_email, notify_register_subject.
1342
1343=item notify_register_email
1344
1345The email to sent the registration notification too. See
1346notify_register above.
1347
1348=item notify_register_subject
1349
1350The subject of the notification email sent when a new user registers.
1351Any {I<field>} is replaced with the given field from the registered
1352user. See notify_register above.
1353
1354Default: New user {userId} registered
1355
6c83a514
TC
1356=item notify_register_customer
1357
1358If non-zero then email id C<notify_register_customer> will be sent to
1359new user on registration. By default this uses template
1360user/email_register, subject "Thank you for registering" which can be
f197f061
TC
1361overridden in [email notify_register_customer] or via the
1362C<set_subject> tag.
1363
1364=item notify_register_customer_admin
1365
1366If non-zero then the behaviour described for
1367C<notify_register_customer> will take place when a new member is added
1368by an administrator. Defaults to the value of
1369C<notify_register_customer>.
6c83a514 1370
2a295ea9
TC
1371=back
1372
81f3292d
TC
1373=head2 [payment type names]
1374
1375This section and [payment type descs] are used to configure new
1376paymeny type ids.
1377
1378The key is the integer representing the payment type. The value is
1379the name used in tags for checking the payment type.
1380
1381You can also add a description (currently unused) to [payment type
1382descs].
1383
1384You should use numbers starting from 10 to avoid conflicts with future
1385BSE payment types.
1386
1387=head2 [payment type descs]
1388
1389See [payment type names].
1390
1391=head2 [payment type required]
1392
1393Set the key given by the payment type id to a value of a
1394comma-separated list of fields required for that payment type.
1395
3ae524f3
TC
1396=head2 [help style I<style-name>]
1397
1398This type of configuration section is used to set values for a style
1399of help icon. Only the C<template> and C<prefix> values are used
1400directly by the code, the others are used by the default helpicon
1401templates.
1402
1403=over
1404
1405=item prefix
1406
1407The URI to the help files for this style. Default: /help/ in style
1408"user", /admin/help/ in style "admin".
1409
1410=item template
1411
1412The template used to produce the icon. Default: helpicon in style
1413user, admin/helpicon in style "admin".
1414
1415=item icon
1416
1417URI to the help icon image. Default: /images/admin/help.gif
1418
1419=item iconwidth
1420
1421The width of the help icon image. Default: 16
1422
1423=item iconheight
1424
1425The height of the help icon image. Default: 16
1426
1427=back
1428
1429If you just want to change the help icon image for user help icons you
1430might do:
1431
1432 [help style user]
1433 icon=/images/help.gif
1434
4175638b
TC
1435=head2 [affiliate]
1436
1437=over
1438
1439=item allowed_referer
1440
1441A semi-colon (;) separated list of referer domains that are allowed to
1442link to the C<a_set> target of L<affiliate.pl>.
1443
1444If the user's browser supplies a referer header then it will be
1445checked against this list.
1446
1447=item require_referer
1448
1449If this is set then the C<a_set> target of L<affiliate.pl> will
1450require that the user's browser supply a Referer header.
1451
1452=item default_refresh
1453
1454If no C<r> parameter is supplied to the C<a_set> target of
1455L<affiliate.pl> then this is used as the default refresh.
1456
1457Default: the site base url.
1458
829c9ed9
TC
1459=item subscription_required
1460
1461This is either the numeric or text of a subscription for which the
1462affiliate must have an active subscription.
1463
fdc2b7a2
TC
1464=item flag_required
1465
1466A single letter flag which the site administrator must set for the
1467affiliate page to be displayed for the given member.
1468
ea646070
TC
1469=item set_cookie
1470
1471If this is set then affiliate.pl will set the named cookie to the
1472affiliate id.
1473
1b5a718f
TC
1474=item other_cookies
1475
1476This is a comma-separated list of other cookies that should be set by
1477the a_set target. The values for the cookies should be passed to the
1478a_set target. For example with:
1479
1480 [affiliate]
1481 other_cookies=alpha,beta
1482
1483if the url:
1484
1485 http://your.site.com/cgi-bin/affiliate.pl?a_set=1&id=someid&alpha=1&beta=2&gamme=3
1486
1487is accessed, then the cookie alpha is set to "1", beta is set to "2".
1488The cookie gamma will not be set since it's not listed.
1489
ea646070
TC
1490=item linkbaseurl
1491
1492Used as the link base URL for the afflink.tmpl side bar template when
1493an affiliate id is set. Default: example.com
1494
1495=item linkbasedesc
1496
1497Used at the text of the link for the afflink.tmpl side bar template
1498when an affiliate id is set. Default: Your Site.
1499
1500=item linkdefurl
1501
1502Used as the link URL for the afflink.tmpl side bar template when an
1503affiliate id is not set. Default: example.com
1504
1505=item linkdefdesc
1506
1507Used as the text of the link for the afflink.tmpl side bar template
1508when an affiliate id is not set. Default: Our site
1509
4175638b
TC
1510=back
1511
3c32512d
TC
1512=head2 [BSE Siteuser Images]
1513
1514Each key is the id of a member image, with a corresponding [BSE
1515Siteuser Image I<image_id>] section. The values are ignored.
1516
1517=head2 [BSE Siteuser Image I<image_id>]
1518
1519Provides information about a single member image "template".
1520
1521=over
1522
1523=item description
1524
1525Short description on the image, like "Logo". Used in error messages.
1526
1527=item help
1528
1529Longer description of the image. Accessible with the member_image tag.
1530
1531=item minwidth
1532
1533=item minheight
1534
1535=item maxwidth
1536
1537=item maxheight
1538
1539The minimum and maximum dimensions of the image.
1540
1541=item widthsmallerror
1542
1543=item heightsmallerror
1544
1545=item widthlargeerror
1546
1547=item heightlargeerror
1548
1549Error messages displayed in the when the image is outside the
1550configured dimensions.
1551
1552=item largeerror
1553
1554=item smallerror
1555
1556Default error messages for the above.
1557
1558=item maxspace
1559
1560Maximum storage the image can use in bytes. Default: 1000000.
1561
1562=item spaceerror
1563
1564Error message displayed if the image uses too much storage.
1565
1566=back
1567
ab2cd916
TC
1568=head2 [editor]
1569
1570Various editor settings.
1571
1572=over
1573
1574=item allow_thumb
1575
1576If this is non-zero the system will attempt to load the configured
1577thumbnail class, and put thumbnail images on the image manager page
1578rather than full-size images. Default: off
1579
1580=item thumbs_class
1581
1582The name of a perl class that implement's BSE's thumbnail API. At
1583this point the only class that implements that is BSE::Thumb::Imager,
1584supplied with BSE. Default: None
1585
1586=item default_thumbnail
1587
1588URI to the default thumbnail image. This is presented when the
1589runtime production of a thumbnail image fails.
1590
1591=item default_thumbnail_width
1592
1593=item default_thumbnail_height
1594
1595Dimensions of the default thumbnail image.
1596
1597=item default_thumbnail_alt
1598
1599Alt text for the default thumbnail image.
1600
1761af79
TC
1601=item check_modified
1602
1603If this is true then BSE will check the value of the lastModified
1604parameter passed against the value in the article. If these don't
1605match the article isn't saved and is redisplayed with an error
1606message. This provides simple protection against one user saving
1607changes over those made by another.
1608
ab2cd916
TC
1609=back
1610
1611=head2 [thumbnails]
1612
1613=over
1614
1615=item max_width
1616
1617=item max_height
1618
1619=item max_pixels
1620
1621Default values for the thumbimage tag.
1622
1623=back
1624
829c9ed9
TC
1625=head2 [includes]
1626
1627Each value is used as the relative or absolute name of a file or
1628directory to load more configuration data from.
1629
1630The keywords must remain unique.
1631
1632Only the [includes] section from bse.cfg itself is used to locate more
1633configuration data.
1634
1635If the value references a directory, all files with an extension of
1636C<.cfg> are read for configuration data.
1637
1638The order the files are read (which later files overriding older
1639files) is:
1640
1641=over
1642
1643=item 1.
1644
1645bse.cfg is read
1646
1647=item 2.
1648
1649the entries in [includes] are sorted alphabetically (or rather
1650asciily), so an entry with key "A" is read before one with key "B",
1651one with key "01" is read before "02", but key "10" would be read
1652I<before> key "2".
1653
a9634cc9 1654=item 3.
829c9ed9
TC
1655
1656if an entry is a file then that is read and the values merged.
1657
a9634cc9 1658=item 4.
829c9ed9
TC
1659
1660if an entry is a directory, then that is scanned and the files found
1661read alphabetically as above.
1662
1663=back
1664
6a8a6ac5
TC
1665=head2 [error_img]
1666
1667This is used to configure the error icon displayed next to fields that
1668fail validation.
1669
1670=over
1671
1672=item image
1673
1674URI to the image file.
1675
1676=item width
1677
1678=item height
1679
1680The width and height of the error icon image.
1681
1682=back
1683
fdc2b7a2
TC
1684=head2 [site user flags]
1685
1686Flags that can be set for site users.
1687
1688All flag Ids are single letters or digits. Uppercase letters are
1689reserved for use by BSE internally, leaving lower-case letters and
1690digits for your own use.
1691
1692Use the id of the flag as the key, and a description of the flag as
1693it's value.
1694
deae2a52
TC
1695=head2 [article defaults]
1696
1697=head2 [catalog defaults]
1698
1699=head2 [product defaults]
1700
1701These sections contain defaults values for the corresponding article
1702types.
1703
1704Each key is the name of a column for the article type.
1705
1706If an entry is not found in [catalog defaults] then [article defaults]
1707is also checked.
1708
1709If an entry is not found in [product defaults] then [article defaults]
1710is also checked.
1711
1712These sections are checked B<after> the C<[children of >I<id>C<]> and
1713C<[level >I<level>C<]> sections.
1714
1715These defaults are used when creating an article where no value is
1716supplied, they can also be accessed via the <:default I<name>:> tag.
1717
1c3e5303
TC
1718=head2 [newsletter filters]
1719
1720Contains C<criteria>I<index> entries starting from C<criteria1>, then
1721C<criteria2>, etc.
1722
1723Each entry consists of a filter class name, followed by a ; followed
1724by data passed to that filter.
1725
1726 ; user the original SQL based filter, configured from
1727 ; section [foo]
1728 criteria1=BSE::NLFilter::SQL;foo
1729
1730See the documentation for each filter to configure the filters.
1731
c2096d67
TC
1732=head2 [Query Groups]
1733
1734The key of each entry is the numeric identifier of a query group, the
1735values are the name of the query group. For example:
1736
1737 [query groups]
1738 1=some name
1739
1740 [query group some name]
b27af108 1741 sql=select id from bse_siteusers where id = ? and name1 like '%some%'
c2096d67
TC
1742
1743Each entry also has a corresponding [Query Group I<name>] section.
1744
1745=head2 [query group I<name>]
1746
1747This section corresponds to an entry in [Query Groups].
1748
1749=over
1750
1751=item sql
1752
1753This is an SQL statement. One placeholder is required and is passed
1754the siteuser id (primary key) of the user to be checked. If this
1755query returns I<any> rows then the user is considered part of the
1756group.
1757
1758=back
1759
16901a2a
TC
1760=head2 [template types]
1761
1762Each key is a template name, the value is the content type to be used
1763when displaying the template dynamically.
1764
fea96500
TC
1765=head2 [template descriptions]
1766
1767Each key is a template name, the value is a description used in the
1768template dropdown for that template.
1769
8f84f3f1
TC
1770=head2 [body class]
1771
1772This section defines CSS class names for BSE's body text link tags.
1773The key is the tag name, the value is the CSS class to be used.
1774
1775By default the class used is the same as the name of the tag, but you
1776can switch this off by adding an entry setting the class to the empty
1777string, for example:
1778
1779 ; no class attribute for any of the links
1780 [body class]
1781 link=
1782 poplink=
1783 doclink=
1784 popdoclink=
1785
1786You can set p here too to set the class for paragraphs generated as
1787body text. By default no class is set.
1788
def1a923
TC
1789=head2 [popimage]
1790
1791Controls the behaviour of the window displayed by the popimage[] body
1792text tag. If the Javascript for this has been customized then this
1793may not apply.
1794
1795=over
1796
1797=item extrawidth
1798
1799=item extraheight
1800
1801Extra width and height for the window beyond the size of the image.
1802Default: no extra width or height.
1803
1804=item popmiddle
1805
1806If set to non-zero popimage[] will attempt to centre the popup within
1807the current window. Default: 0.
1808
1809=back
1810
1811=over
1812
1813=back
1814
41e7c841
TC
1815=head2 [inpho]
1816
1817This is used to configure the DevHelp::Payments::Inpho module.
1818
1819=over
1820
1821=item test
1822
1823If this is set then the test parameters are used instead of the
1824product values.
1825
1826=item url
1827
1828The URL to process requests through.
1829
1830Default: https://extranet.inpho.com.au/cc_ssl/process
1831
1832=item user
1833
1834Inpho supplied user name.
1835
1836=item password
1837
1838Inpho supplied password.
1839
1840=item test_url
1841
1842The URL to process test requests through.
1843
1844=item test_user
1845
1846The user to supply to test requests.
1847
1848=item test_password
1849
1850The password to supply to test requests.
1851
1852=back
1853
f2bf0d11
TC
1854=head2 [custom]
1855
1856This section controls whether some custom class methods are called:
1857
1858=over
1859
1860=item saveopts
1861
1862If this is non-zero then siteuser_saveopts is called.
1863
1864=back
1865
0a66f55c
AO
1866=head2 [levelI<level> menus]
1867
1868Where I<level> is the article level at which the defined menu options will be available.
1869Configure each menu value and description as I<key> and I<value>.
1870
1871=over
1872
1873For example:
1874
1875 [level1 menus]
1876 0=Default
1877 1=Sidebar
1878 2=Footer
1879
1880To create a menus using such values, use the "allkids_of" iterator "filter" option.
1881
1882For example:
1883
1884 <:iterator begin allkids_of -1 filter: [menu] == 2 :>
1885
1886=back
1887
37726cc9
AO
1888=head2 [title alias]
1889
1890Enable the "titleAlias" article field and set which level it will be available.
1891
1892=over
1893
1894=item levelI<level>
1895
1896Where I<level> is the article "level" for which the "titleAlias" field should be enabled. To enable
1897set the value to non-zero.
1898
1899For example:
1900
1901 [title alias]
1902 level1=1
1903
1904The "titleAlias" can be used as an alternate "short" title for the given article, especially useful
1905for space critical iterated menus. A template conditional can be used to display the "titleAlias"
1906in place of the article "title" when appropriate.
1907
1908=back
1909
195977cd
TC
1910=head2 [thumb geometries]
1911
1912Each key represents a geometry identifier for use by the thumbimage[],
1913gthumbimage[] body text tags and the <:thumbimage ...:>, <:gthumbimage
b864cc90 1914...:>, <:dthumbimage ...:> template tags.
195977cd
TC
1915
1916The key is the geometry identifier, the value is the geometry string
1917as follows.
1918
1919The geometry string consists of:
1920
1921=over
1922
1923=item *
1924
1925dimensions
1926
1927=item *
1928
1929crop flag - if present
1930
1931=item *
1932
1933optional fill
1934
1935=back
1936
1937The dimensions can be in any of the following forms:
1938
1939=over
1940
1941=item *
1942
1943<width>x<height> - the desired maximum width and height. eg 200x150
1944
1945=item *
1946
1947<width>x - the desired width, with the height calculated
1948proportionally based on the source image size
1949
1950=item *
1951
1952x<height> - the designed height, with the width calculated
1953proportionally based on the source image size.
1954
1955=item *
1956
1957<size> - the desired maximum size in both directions. so "200" is
1958equivalent to "200x200"
1959
1960=back
1961
1962The crop flag is a single letter "c", if present then the image should
1963be scaled so the smaller dimension matches the requested size, and the
1964longer dimension will be cropped to fit.
1965
1966The fill if present is: fill(color) where color is a color recognized
1967by the underlying graphics implementation. This should be at least
1968hex web colors without the #, eg fill(FF0000) will fill with red.
1969
b864cc90
TC
1970=head2 [thumb classes]
1971
1972Each key represents a geometry identifier for use by the thumbimage[],
1973gthumbimage[] body text tags and the <:thumbimage ...:>, <:gthumbimage
1974...:>, <:dthumbimage ...:> template tags.
1975
1976The value is used as the class for the generated img tag.
1977
510a9ee7
TC
1978=head2 [targets]
1979
1980Each value represents a handler or script name for the <:dyntarget
1981I<script> I<target> ...:> tag.
1982
1983Each key has a TARGET version and a no-TARGET version, with the key
1984suffixed with C<_n>.
1985
1986The default C<nuser> target is C</cgi-bin/nuser.pl/user/TARGET>. The
1987default no-target C<nuser> is C</cgi-bin/nuser.pl/user>.
1988
1989For other targets the default is
1990C</cgi-bin/>I<script>C<.pl?a_TARGET=1> and
1991C</cgi-bin/>I<script>C<.pl>.
1992
1993The string C<TARGET> is replaced with the target specified in the
1994dyntarget tag.
1995
1996This, along with dyntarget is intended to allow a more "Web 2.0" type
1997of access to BSE. eg. you might set:
1998
1999 [targets]
2000 shop=/xshop/TARGET
2001 shop_x=/xshop/
2002
2003and have a rewrite rule:
2004
2005 RewriteRule ^/xshop/(.*)$ /cgi-bin/nuser.pl/shop/$1 [PT]
2006
8a153d74
TC
2007=head2 [popimage class I<classname>]
2008
2009This defines the settings for a class of images generated by the
2010popimage[] and gpopimage[] body text markup tags. For example, the
2011settings for C<popimage[imageid|foo]> can be found in section
2012C<[popimage class foo]>.
2013
2014=over
2015
2016=item html
2017
2018The html generated for this class. Tags of the form
2019C<{>I<identifier>C<}> are replaced, where I<identifier> can be
2020C<inline_> or C<outline_> followed by an image field name, for example
2021C<inline_src> is the URL to the inline image.
2022
2023Default: <a href="{outline_src}" rel="lightbox[id]" target="_blank"><img src="{inline_src}" alt="{inline_alt}" width="{inline_width}" height="{inline_height}" border="0" /></a>
2024
2025The default may be tuned as needed.
2026
2027=item inline
2028
2029The inline image geometry. Default: editor (the value used for
2030thumbnails on the admin side)
2031
2032=item outline
2033
2034The outline image geometry. If no value is supplied then the original
2035image values are used.
2036
2037=back
2038
0c2e7f7a
TC
2039=head2 [mail resources]
2040
2041Each key is the identifier of a file that can be attached to
2042BSE::ComposeMail emails. The value is comma separated filename,
2043content type, inline status.
2044
2045The files are searched for through the template search mechanism, so
2046the filename can be relative to either the master or local templates
2047directories.
2048
2049If the content type is not supplied, if the filename end in gif, png
2050or jpg the appropriate content type is used, otherwise
2051application/octet-stream.
2052
2053If the inline status is not supplied then images are considered
2054inline, and other files arent.
2055
a53374d2
TC
2056=head2 [shop registration]
2057
2058Each key represents a message id from attempts to checkout. Except
2059the all key which covers all cases.
2060
2061If the C<all> key or the message id key is non-zero then the checkout
2062page will redirect to registration instead of login if the cart or
2063configuration requires that the user be logged in.
2064
3f36e485
TC
2065=head2 [template I<template-name>]
2066
2067Settings for articles based on a particular template.
2068
2069=over
2070
2071=item no_cache_dynamic
2072
2073Controls whether a cache-control: no-cache header will be produced.
2074Can be overridden with the A and B article flags. If not set the
2075value of [article].no_cache_dynamic is used.
2076
2077=back
2078
2079=head2 [article]
2080
2081Global settings for articles.
2082
2083=over
2084
2085=item no_cache_dynamic
2086
2087Controls whether a cache-control: no-cache header will be produced.
2088Can be overridden with the A and B article flags or [template
2089I<template-name>].no_cache_dynamic. If not set the value of
2090[basic].no_cache_dynamic is used.
2091
2092=back
2093
c6fc339f
TC
2094=head2 [recaptcha]
2095
2096For the <:recaptcha:> tag currently only used for fmail.pl.
2097
2098=over
2099
2100=item api_public_key
2101
2102=item api_private_key
2103
2104The public and private key you receive when you register with reCAPTCHA.
2105
2106=item error_I<error_code>
2107
2108Replace the error message for the given I<error_code> where
2109I<error_code> is the reCAPTCHA error code
2110(eg. "incorrect-captcha-sol") with dash replaced by underscore.
2111
2112eg.
2113
2114 error_incorrect_captch_sol=VERY BAD INPUT
2115
2116=back
2117
36e373a9
TC
2118=head2 [global file metadata]
2119
2120Each key represents an item of metadata for files attached to
2121articles.
2122
2123The values are ignored.
2124
2125For each key, extra information is defined in the [file metadata
2126I<name>] section.
2127
2128=head2 [file metadata I<name>]
2129
2130Definition for the file metadata item I<name>.
2131
2132=over
2133
2134=item *
2135
2136title - descriptive name of the metadata. Defaults to I<name>.
2137
2138=item *
2139
2140rules - validation rules, separated by ;. Custom rules can be defined
2141in [file metadata validation].
2142
2143=item *
2144
2145ro - if non-zero the metadata cannot be modified directly by the admin
2146(applications can still generate it). Default: writable.
2147
2148=item *
2149
2150type - the data type of the metadata, any of string, text, enum,
2151integer, real, image. If this is enum values must be defined and
2152labels should be. Default: string.
2153
2154The types are:
2155
2156=over
2157
2158=item *
2159
2160string - single line of text
2161
2162=item *
2163
2164text - one or more lines of text
2165
2166=item *
2167
2168integer - whole number
2169
2170=item *
2171
2172real - number with decimal points
2173
2174=item *
2175
2176enum - select from a list of possible values.
2177
2178=item *
2179
2180image - image file.
2181
2182=back
2183
2184=item *
2185
2186values - semi-colon separated list of values for this metadata.
2187
2188=item *
2189
2190labels - semi-colon separated list of labels for the values
2191
2192=item *
2193
2194help - help html to display for the metadata
2195
2196=item *
2197
2198data_name - (images only) the key to use to store the image data.
2199Default: I<name>_data.
2200
2201=item *
2202
2203width_name - (images only) the key to use to store the image width.
2204Default: I<name>_width.
2205
2206=item *
2207
2208height_name - (images only) the key to use to store the image height.
2209Default: I<name>_height.
2210
2211=item *
2212
2213cond - a perl expression indicating whether the metadata should be
2214prompted for, for this file. $file is the file object. Default: 1.
2215
2216=item *
2217
2218unit - text displayed after the entry box for the metadata. Default:
2219empty. Useful for including a unit ("pixels") or format help
2220("hh:mm").
2221
2222=back
2223
bede67d9
TC
2224=head2 [session cleanup]
2225
2226Controls the processing of the bse_session_clean.pl script.
2227
2228=over
2229
2230=item *
2231
2232days - the minimum age in days of sessions to be removed. Default: 30.
2233
2234=item *
2235
2236per - the number of records to remove per SQL delete request.
2237Default: 1000.
2238
2239=item *
2240
2241count - the number of SQL delete requests to perform, maximum.
2242Default: 1000.
2243
2244=item *
2245
2246optimize - whether to perform a table optimization after deleting
2247records. Default: 1 (set to 0 to skip optimization)
2248
2249=back
2250
2251=head2 [nightly work]
2252
2253Controls the bse_nightly.pl script.
2254
2255=over
2256
2257=item *
2258
2259jobs - a comma separated list of BSE background processes to run when
2260bse_nightly.pl is run. Default: bse_session_clean
2261
b249abcb
TC
2262=item *
2263
2264I<other keys> - each key is a sort key, and the value is a single
2265background task name. This allows add-ons to setup extra tasks
2266without overwriting each other. The sugessted key format is:
2267
2268 99 - two digit priority - 00 is executed first, 99 last
2269 package-name - name of package the task is for
2270 unique - extra text to make the key unique, if necessary
2271
bede67d9
TC
2272=back
2273
4cf6a60c
TC
2274=head2 [cache]
2275
2276Parameters controlling where cached information - eg. file upload
2277progress is stored.
2278
2279=over
2280
2281=item *
2282
2283class - the BSE::Cache compatible cache class. See the documentation
2284of BSE::Cache::Cache, BSE::Cache::CHI or BSE::Cache::Memcached.
2285
2286=back
2287
a9634cc9
TC
2288=head2 [db]
2289
2290Database connection parameters. These override the settings in
2291Constants.pm which are deprecated.
2292
2293=over
2294
2295=item *
2296
2297dsn - the DBI dsn used to connect to the database. Default:
2298$Constants::DSN.
2299
2300=item *
2301
2302user - the logon to the database. Default: $Constants::UN
2303
2304=item *
2305
2306password - the password for the user. Default: $Constants::PW.
2307
2308=item *
2309
2310dbopts - a perl expression that should evaluate to a hash reference.
2311Default: $Constants::DBOPTs, or an empty hashref.
2312
2313=item *
2314
2315class - the database wrapper class to use. Default: BSE::DB::Mysql.
2316No other values are currently supported.
2317
2318=back
2319
fea96500
TC
2320=head2 [extra a_config]
2321
2322Defines extra configuration to be returned from the BSE system
2323configuration.
2324
2325Each key is the keyword in the returned JSON object. If the key
2326already exists it is not overwritten.
2327
2328Each value is the name of a section in the BSE configuration. The
2329strings "{level}", "{generator}", "{parentid}", "{template}" are
2330replaced with their values from the article that config is being
2331requested for.
2332
2333So:
2334
2335 [extra a_config]
2336 menu=level{level} menu
2337
2338 [level1 menu]
2339 alpha=One
2340 beta=Two
2341
2342will include:
2343
2344 menu: { alpha: "One", beta: "Two" }
2345
2346in the returned configuration
2347
dbe8a12a
TC
2348=head2 [cookie names]
2349
2350This section maps BSE's default cookie names to alternate names. This
2351can be useful if you have two BSE sites under the same domain and need
2352to ensure they use different cookies.
2353
2354eg.
2355
2356 [cookie names]
2357 userid=altuserid
2358
5abe2da5 2359=head2 [siteuser updates]
f0483c00
TC
2360
2361Each key identifies an update specification for userupdate.pl, the
2362value is a description of the specification.
2363
2364See L<<[siteuser update I<specid>]>> for the rest of the import
2365specification.
2366
5abe2da5 2367
f0483c00
TC
2368=head2 [siteuser update I<specid>]
2369
2370Currently contains only a single key:
2371
2372=over
2373
2374=item *
2375
2376fields - a semi-colon separated list of fields to import. Must
2377contain one of C<id> or C<userId> which is used as a key to identify
2378the user to update. An C<x> entry is a field to ignore. Some fields,
2379such as C<confirmed> may not appear in this list.
2380
2381=back
dbe8a12a 2382
40cc2f24
TC
2383=head2 [paypal]
2384
2385Configuration for BSE's PayPal integration.
2386
2387It shouldn't be necessary to change any of the URLs.
2388
2389=over
2390
2391=item *
2392
2393test - if true, then the PayPal sandbox is used, and the configuration
2394entries starting in C<test_> are used. If false, PayPal is live, and
2395configuration entries starting in C<live_> are used. Default: 1.
2396
2397=item *
2398
2399test_api_username, test_api_password, test_api_signature - API
2400credentials for test mode. Required in test mode.
2401
2402=item *
2403
2404live_api_username, live_api_password, live_api_signature - API
2405credentials for live mode. Required for live mode.
2406
2407=item *
2408
2409test_ws_url - URL to make NVP requests through in test mode. Default:
2410https://api-3t.sandbox.paypal.com/nvp
2411
2412=item *
2413
2414test_refresh_url - PayPal URL to refresh to in test mode. Default:
2415https://www.sandbox.paypal.com/webscr
2416
2417=item *
2418
2419live_ws_url - URL to make NVP requests through in live mode. Default:
2420https://api-3t.paypal.com/nvp
2421
2422=item *
2423
2424live_refresh_url - PayPal URL to refresh to in live mode. Default:
2425https://www.paypal.com/cgibin/webscr
2426
2427=back
2428
2429=head2 [paypal custom]
2430
2431Extra parameters supplied to the SetExpressCheckout API. See the
2432Express Checkout Advanced Features Guide (from PayPal) for details.
2433
2434Some settings that may be useful:
2435
2436=over
2437
2438=item *
2439
2440PAGESTYLE - the style of payment page to use from those listed in your
2441account profile.
2442
2443=item *
2444
2445HDRIMG - https URL to an image to use in the payment page header.
2446
2447=item *
2448
2449HDRBACKCOLOR - a 6 hex digit color to use as the background of the
2450payment page header.
2451
2452=item *
2453
2454HDRBORDERCOLOR - a 6 hex digit color to use as the border of the
2455payment page header.
2456
2457=back
2458
86972656
TC
2459=head2 [audit log]
2460
2461=over
2462
2463=item *
2464
2465mail - if non-zero any emails sent through BSE::ComposeMail are logged
2466in the audit log. Default: 0.
2467
2468=item *
2469
2470mail_max_dump - if non-zero this is the size limit of the dump stored
2471in the audit log when [audit log].mail is enabled.
2472
2473=back
2474
ea69cb09
TC
2475=head2 [audit log I<facility>]
2476
2477Most commonly C<[audit log bse]>. Controls whether given events or
2478families of events are logged.
2479
2480The key is one of:
2481
2482=over
2483
2484=item I<component>
2485
2486=item I<component>C<:>I<module>
2487
2488=item I<component>C<:>I<module>C<:>I<function>
2489
2490=back
2491
2492with the longer keys overriding the shorter keys, and defaulting to
2493all actions being logged.
2494
b374e526
TC
2495=head2 [mail audit log]
2496
2497This enables sent when an event is logged in the audit log. Warning:
2498for common events this will result in large amounts of email.
2499
2500=over
2501
2502=item *
2503
2504to - the email address to send the email to
2505
2506=item *
2507
2508emerg, alert, crit, error, warning, notice, info, debug - if present
2509and true then events at these levels result in an email. If the value
2510contains an C<@> then the value is used as the recipient address.
2511
2512=item *
2513
2514I<facility>-I<component>
2515
2516=item *
2517
2518I<facility>-I<component>-I<module>
2519
2520=item *
2521
2522I<facility>-I<component>-I<module>-I<function>
2523
2524Controls sending an email for specific events or families of events.
2525If the value is true, send an email for that event. If the value
2526contains an C<@> then the value is used as the recipient address.
2527
8a3b8db8
TC
2528=back
2529
2530with the longer keys overriding the shorter keys, and defaulting to
2531all actions being logged.
2532
2533=head2 [html tidy]
2534
2535Contains options to pass to HTML::Tidy. Anything not listed below is
2536passed directly to HTML::Tidy->new.
2537
2538=over
2539
2540=item *
2541
2542ignore_types - types of message to ignore separated by commas, any,
2543all or none of info, warning, error.
2544
2545=item *
2546
2547ignore_text_I<key> - messages to ignore, I<key> is not used, just the
2548value.
2549
2550
b374e526
TC
2551=back
2552
a9cee650
TC
2553=head2 [email I<token>]
2554
07301b75 2555Controls emails sent via F<cgi-bin/admin/sendemail.pl>.
a9cee650
TC
2556
2557=over
2558
2559=item *
2560
2561template - plain text template
2562
2563=item *
2564
2565html_template - HTML template (defaults to the value of I<template>
2566followed by C<_html>
2567
2568=item *
2569
2570subject - subject of the email, can be overridden with the
2571C<set_subject> tag.
2572
2573=item *
2574
2575from - from email address, defaults to the shop from address
2576
2577=item *
2578
2579from_name - from name
2580
2581=item *
2582
2583allow_html - controls whether HTML is allowed. By default this is
2584based on the user's settings.
2585
2586=back
2587
93be4a7b
TC
2588=head2 [lost password]
2589
2590=over
2591
2592=item *
2593
2594daily_limit - the number of recovery attempts permitted per day.
2595Default: 3.
2596
2597=item *
2598
2599age_limit - the id included in the email is valid for this many days.
2600Default: 7.
2601
2602=back
2603
852e69d6
TC
2604=head2 [link replacement]
2605
2606For formatted text, this is a list of URL prefixes to replace.
2607
2608The key is a sort key, replacements are checked in alphabetical order.
2609
2610The value is the original prefix, followed by ";", followed by the
2611replacement.
2612
2613Replacement is performed case-insenitively. Regexp metacharacters
2614
dbfbfb12
TC
2615=head2 [article categories]
2616
2617=over
2618
2619=item *
2620
2621ids - a comma separated list of category ids. There are (currently)
2622no restrictions on the contents of these ids, but alphanumerics are
2623recommended to simplify templates.
2624
2625=item *
2626
2627I<id> - a description for a particular category id. Overridden by the
2628C<name> key in C<< [article category I<id>] >>. Default: ucfirst of
2629the id.
2630
2631=back
2632
2633=head2 [article category I<id>]
2634
2635=over
2636
2637=item *
2638
2639name - name of the article category.
2640
2641=back
2642
2643Other keys may be used as desired, eg. to make it simpler to configure
2644article behaviour based on the category.
2645
5f1832bb
TC
2646=head2 [article menu]
2647
2648This section can be used to add new menu items to the menu displayed
2649on article edit pages.
2650
2651The keys are used for sorting only.
2652
2653The value is comma-separated:
2654
2655=over
2656
2657=item *
2658
2659target script name
2660
2661=item *
2662
2663target identifier, to be set to 1 on making a request to the script.
2664
2665=item *
2666
2667the label for the item in the menu.
2668
2669=back
2670
2671eg.
2672
2673 sample,a_foo,Sample Item
2674
2675will generate a link like:
2676
2677 <a href="/cgi-bin/admin/sample.pl?id=10&amp;a_foo=1">Sample Item</a>
2678
2679where 10 is the id of the article being edited.
2680
2681Keys with a prefix of C<bse_> are reserved for BSE internal use.
2682
fd737137
TC
2683=head2 [undeletable articles]
2684
2685Keys are the ids of articles that may not be deleted.
2686
2687This applies if the value of the entry is a true perl value.
2688
2689 [undeletable articles]
2690 1=home page
2691 2=more home page
2692 ; article 3 is deletable
2693 3=
2694
6f0799a4
TC
2695=head2 [dummy shipping methods]
2696
2697Configures extra shipping methods only selectable from the order
2698detail page.
2699
2700Entries are sorted by value.
2701
2702If the value contains a comma the text up to the comma is removed and
2703the remains used as the label, otherwise the key is used as the label.
2704
61551101
TC
2705=head1 AUTHOR
2706
2707Tony Cook <tony@develop-help.com>
2708
2709=cut