support template generated metadata
[bse.git] / site / docs / config.pod
CommitLineData
61551101
TC
1=head1 NAME
2
3config.pod - documents BSE configuration file options
4
5=head1 DESCRIPTION
6
7BSE historically used Constants.pm to keep most configuration
8information. The plan is to make sure any new configuration is kept
9in bse.cfg, and to slowly move most configuration information into
10bse.cfg.
11
12Keeping configuration information in Constants.pm makes it difficult
13to perform upgrades and makes it impossible to use tools such as
14mod_perl, at least if you want more than one site on the machine.
15
16=head1 CONFIGURATION ENTRIES
17
41f10371
TC
18=head2 [site]
19
20Contains URL configuration for the site.
21
22=over
23
24=item url
25
26The normal URL for the non-secure parts of the site.
27
28=item secureurl
29
30The secure URL for the shop, products and other portions of the site
31that should use SSL. This isn't checked to make sure it is https.
32
33=item name
34
35Used as the site "name" in a few places.
36
37=item adminurl
38
39If set, this is used as the base URL for accessing the administrative
40functions of your site.
41
42=item secureadmin
43
44Ignored if C<adminurl> is set.
45
46If this is true then C<secureurl> is used as the base URL for
47accessing the administrative functions of your site, otherwise C<url>
48is used as the base URL. Default: false (C<url>'s value is used)
49
c5f849c7
TC
50=item forward_from
51
52Configure the IP address of one or more front-end proxies. This can
53be a regular expression except that C<.> is translated to C<\.> and
54C<*> is tranlated to C<.*> to give more glob() like matching.
55
56If the reqesting host matches then admin site URL matching is done
57against HTTP_X_FORWARDED_SERVER instead of SERVER_NAME.
58
59Default: no front-end server configured.
60
41f10371
TC
61=back
62
61551101
TC
63=head2 [paths]
64
65Contains various file system paths.
66
67=over
68
69=item downloads
70
71This is where the files uploads with the file wizard are stored. It
72must be writable by the web server user.
73
74=item admin_templates
75
76Directory containing administrative templates. Note: this is not
77completely implemented for now, so assume the default. Default: admin
78directory under $TMPLDIR.
79
80=item templates
81
aefcabcb
TC
82Directory base for most templates.
83
84=item local_templates
85
86Local Directory base for templates. This is searched before the
87templates directory.
61551101 88
ca9aa2bf
TC
89=item images
90
91Where uploaded images are stored. This is not yet completely
92implemented. Default: $IMAGEDIR.
93
331fd099
TC
94=item libraries
95
96Local search path for BSE::Custom, or the class configured by
97C<custom_class> in [basic].
98
3c32512d
TC
99=item siteuser_images
100
101Where uploaded siteuser images are stored. This must be set in the
102config file. The default bse.cfg include an entry to use the current
103values of [paths].downloads
104
efcc5a30
TC
105=item dynamic_cache
106
107Pregenerated dynamic article pages are stored here. This must be
108defined if you site contains any dynamicly generated pages.
109
195977cd
TC
110=item scalecache
111
112The directory where cached versions of scaled thumbnails are stored.
113Defaults to image_dir/scaled. This must be in the document tree. If
114you set this you should also set scalecacheurl.
115
116=item scalecacheurl
117
118The URL to the directory represented by scalecache. Defaults to
119/images/scaled.
120
61551101
TC
121=back
122
123=head2 [extensions]
124
125This section is used by the file wizard to map uploaded file
126extensions to MIME content types. This can be used to extend
127BSE::FileEditor's internal extension map. It cannot override that
128map.
129
130The key for each entry is the extension, without the leading '.'.
131
132eg.
133
134 xls = application/msexcel
135
136=head2 [templates]
137
138Used for translating symbolic template names into full names under the
139template directory.
140
141In each case the default is the name with a C<.tmpl> extension.
142
143=over
144
145=item user/logon
146
147user logon page
148
149=item user/register
150
151user registration page
152
153=back
154
155=head2 [admin templates]
156
157Used for translating the names of administration templates into filenames.
158
159In each case the default is the name with a C<.tmpl> extension.
160
161=over
162
163=item filelist
164
165article file wizard
166
d2730773
TC
167=item catalog
168
169Catalog editor page. Default admin/edit_catalog.tmpl
170
171=item 1
172
173=item 2
174
175=item 3
176
177=item 4
178
179=item 5
180
181Article edit pages. Default admin/edit_<number>.tmpl
182
183=item steps
184
185Step child/parent management page. Default admin/edit_steps.tmpl
186
61551101
TC
187=back
188
189=head2 [html]
190
191Minor html items.
192
193=over
194
195=item charset
196
197The value of the charset keyword when outputting HTML from a script.
198Set to the empty string to suppress the charset keyword. Default:
199iso-8859-1.
200
5af99440
TC
201=item redirect_links
202
203If this is a non-zero number, then all but mailto links are redirected
204to C<nuser.pl/redirect> so you can display a diclaimer. If this
205contained alphabetics it's treated as a comma separated list of url
206schemes that should be handled via C<nuser.pl/redirect>. If 0 or not
207present, no redirection is done.
208
209The redirect URL includes a hash of the url, title and the redirect
210salt to prevent using this mechanism by external sites for cookie
211stealing attacks.
212
213=item redirect_salt
214
215The salt used in generating the has for redirect_links. Default: an
216empty string.
217
61551101
TC
218=back
219
220=head2 [basic]
221
222=over
223
224=item cookie_lifetime
225
226The expiry time for cookies. This should be in the form supported by
227CGI.pm for the -expires parameter. Typically you want a plus ('+'), a
228number, and a time character (s - seconds, m - minutes, h - hours, d -
229days, M - months). Default: +3h
230
a8ddb0f3
TC
231=item cookie_domain
232
233This overrides the domain value set for cookies. This is useful if
234you allow the site to run under both example.com and www.example.com,
235if you set cookie_domain to example.com then a user visiting
236www.example.com will still have their cookies when they visit
237example.com.
238
3c8b9c2c
TC
239=item cookie_name
240
241This overrides the cookie name used to store the session id. Default:
242sessionid. This is useful when you have 2 sites under the same
243top-level domain, and helps disambiguate the cookie returned by the
244browser.
245
61551101
TC
246=item minpassword
247
248Minimum password length in characters. Default: 4.
249
b19047a6
TC
250=item randomdata
251
252Device to read random data from. This device should not block when it
253runs out of entropy.
254
6e3d2da5
TC
255=item sign
256
257If this is true then the encrypted messages containing the customer's
258credit card number are sent to the shop owner signed. To avoid
259keeping a passphrase and signing key on the server you can set this to
260false (0). This has the effect that anyone could send you an unsigned
261message encrypted with your public key, though this may not be a
262security threat. Default: True.
263
ca9aa2bf
TC
264=item link_titles
265
266If this is true then the links to your articles within BSE will be
267followed by a / and then by a simplified version of the article title.
268The aim is to include at least some title information in the URL
269without modifying the name of the HTML file. Default: False.
270
9168c88c
TC
271=item access_control
272
273If this is true then the user/group/permissions database is used to
274control access to the system. Default: False.
275
147e99e8
TC
276=item access_filter_steps
277
278If this is true, then the drop-down lists of possible stepparents and
279stepchildren on the article edit pages are filtered for access control.
280Default: False.
281
444957b9
TC
282=item access_filter_parents
283
284If this is true, then the drop-down lists of possible parents on the
285newsletter edit pages are filtered for access control.
286Default: False.
287
d49f56a6
TC
288=item server_auth
289
290Set this to non-zero to enable authentication via server
291authentication (usually Basic Authentication.) You should normally
292set this if you set htusers below. Default: 0 (disabled)
293
9168c88c
TC
294=item htusers
295
296This should be the path to a file to be updated with the list of users
297and crypt() versions of their passwords. If this is set then the
298security system will check for a user set by the browser before
299attempting a form based logon. Default: None.
300
331fd099
TC
301=item custom_class
302
303The name of the custom class for your site. This is currently only
304used for article editing customizations. This class should derive
305from BSE::CustomBase. Default: BSE::Custom.
306
671a9877 307=item jit_dynamic_pregen
efcc5a30
TC
308
309If this is true, then pre-generation for dynamic pages will be delayed
310until the page is displayed to a user. Default: off.
311
74b21f6d
TC
312=item staticajax
313
314If true, the ifAjax and ajax tags will be active for static pages.
315
195977cd
TC
316=item cache_thumbnails
317
318If set to zero the results of the thumbimage/gthumbimage body/template
319tags will not be cached. Default: 1 (caching is enabled).
320
b902f9de
TC
321=item static_thumbnails
322
323If true and cache_thumbnails is true then thumbnails for the thumbnail
324cache will be generated when a static page is regenerated, and the
325link from the page will link to the image in the cache rather than to
326C<thumb.pl>. Default: 1 (static thumbnails enabled).
327
73e6b73a
TC
328=item alias_prefix
329
330The prefix applied to articles that use a linkAlias url. This should
331start with a /.
332
333=item use_alias
334
335If this is non-zero then an article with linkAlias set will use an
336alias url instead of the "real" url. You will need to configure a
337RewriteRule or ErrorDocument to page.pl to direct the user to the
338correct URL. Default: 1.
339
340=item alias_suffix
341
342If this is non-zero then the title is cleaned up (all but
343alphanumerics removed) and appended to the alias URL generated.
344
8a153d74
TC
345=item default_popupimage
346
347This is the default popup image class for the popimage[] and
348gpopimage[] tags. Default: popup.
349
bf909925
TC
350=item warn_obsolete
351
352Some obsolete tags will warn to stderr if this is non-zero. Default:
353don't warn.
354
3f36e485
TC
355=item no_cache_dynamic
356
357If non-zero, the default, dynamic responses will include a
358C<Cache-Control: no-cache> header. This can be overridden for
359articles via , article flags, C<[template >
360I<templatename>C<].no_cache_dynamic> and [article].no_cache_dynamic.
361Default: 1.
362
b19047a6
TC
363=back
364
365=head2 [mail]
366
35c0719f 367This section controls how BSE sends email.
b19047a6
TC
368
369=over
370
371=item smtp_server
372
373The host or IP address of your mail server. If this is not set
374C<sendmail> will be used instead. If this is set you must also set
375I<helo>.
376
377=item helo
378
379The name that BSE uses to identify itself when sending mail via SMTP.
380Required if I<smtp_server> is set.
381
382=item sendmail
383
384The path to the C<sendmail> binary. Default: /usr/lib/sendmail
385
386=item sendmail_opts
387
388The options supplied to sendmail. Default: -t -oi
389
390You may want to add the -odq option to this if you want mail queued
391rather than sent immediately.
392
67b69296
TC
393=item set_errors_to_from
394
395If true, we add an Errors-To header set to the same as the From
396header. Default: true.
397
0c2e7f7a
TC
398=item html_system_email
399
400If non-zero then emails sent via the compose mail system that aren't
401being sent to a member record, will be sent as HTML, if the HTML
402template is available.
403
61551101
TC
404=back
405
ca9aa2bf 406=head2 [children of I<id>]
721cd24c
TC
407
408Where I<id> is the identifier for an article.
409
410=over
411
412=item template
413
414the name of the default template for children of the given parent
415
416=item template_dirs
417
418a comma-separated list of extra directories under $TMPLDIR to search
419for templates that can be used for children of the given parent article.
420
421=back
422
ca9aa2bf
TC
423=head2 [article I<id>]
424
425Where I<id> is the identifier of an article.
426
427=over
428
429=item template_dirs
430
431A comma-separated list of extra directories under $TMPLDIR to search
432for templates that can be used for children of the given parent
433article.
434
435=item extra_templates
436
437A comma-separated list of extra templates under $TMPLDIR that can be
438used for the given article.
439
440=back
441
caa7299c
TC
442=head2 [level I<level>]
443
444=over
445
446=item template
447
448The default template for this level of article, assuming it hasn't
449been set in the [children of I<article id>] section.
450
451=item template_dirs
452
453A comma-separated list of extra directories under $TMPLDIR to search
454for templates that can be used for articles at the given I<level>.
455
456=back
457
458=head2 [catalogs]
459
460=over
461
462=item template
463
464The default template for catalogs.
465
466=back
467
468=head2 [products]
469
470=over
471
472=item template
473
474The default template for products.
475
d64413ee
TC
476=item extra_templates
477
478A comma separated list of extra templates that can be used for
479products.
480
caa7299c
TC
481=back
482
61551101
TC
483=head2 [messages]
484
485This can be used to control translation of error messages. Each key
486has a prefix identifying the module that uses the error, followed by
487'/' followed by a specific identifier for the message.
488
489Message parameters, expressed as $I<digit>, are replaced with the
490parameters passed to the message. C<$$> is replaced with C<$>.
491
492Each message identifier below is documented with the id, when it
493occurs, the default message, and any parameters.
494
495=over
496
497=item user/needlogon
498
499the user attempted to logon without entering a logon name. Default:
500"Please enter a logon name". No parameters.
501
502=item user/needpass
503
504the user attempted to logon without entering a password. Default:
505"Please enter your password." No parameters.
506
507=item user/baduserpass
508
509the user's logon name or password was not found or did not match.
510Default: "Invalid user or password". No parameters.
511
512=item user/notloggedon
513
514the user attempted to logoff while not logged on. Default: "You
515aren't logged on". No parameters.
516
517=item user/optsoldpass
518
519the user entered a new password on the options page without entering
520their old password. Default: "You need to enter your old password to
521change your password". No parameters.
522
a53374d2
TC
523=item shop/logonrequired
524
525Displayed if the user attempts to checkout when [shop].require_logon
526is true.
527
61551101
TC
528=back
529
2404a911
TC
530=head2 [downloads]
531
532=over
533
534=item must_be_paid
535
536if non-zero, the order must be marked as paid for before the file can
537be downloaded.
538
539=item must_be_filled
540
541if non-zero the order must be marked as filled before the files can be
542downloaded.
543
4afdbb1b
TC
544=item require_logon
545
546if non-zero the user must be registered/logged on to download I<any>
547file.
548
32696f84
TC
549=item log_downufile
550
551if non-zero, downloads of userfiles will be logged. Default: 0
552
553=item log_downufile_maxage
554
555the maximum age of entries in the user file download log, in days.
556Default: 30.
557
2404a911
TC
558=back
559
b19047a6
TC
560=head2 [confirmations]
561
562Control over confirmation emails.
563
564=over
565
566=item subject
567
568The subject of email confirmation emails. Default: Subcription
569Confirmation.
570
571=item from
572
573The from field for the email. Default: $SHOP_FROM
574
575=back
576
531fb3bc
TC
577=head2 [subscriptions]
578
579Control over subscription messages.
580
581=over
582
583=item from
584
585The from field for the email. Default: $SHOP_FROM.
586
d09682dd
TC
587=item testname
588
589Default for the "Test Name" field for sending test subscription
590messages.
591
592=item testemail
593
594Default for the "Test Email" field for sending test subscription
595messages.
596
597=item testtextonly
598
599Set to 1 if you want the "Test Text Only" box checked by default for
600sending test subscription messages.
601
602=item testing
603
604Set to 0 to disable display of the test subscription messages portions
605of the subscriptions send form.
606
99b7cef0
TC
607=item text_link_inline
608
609Set to format links as they appear in the text version of emails.
610C<$1> is replaced with the title, C<$2> with the URL and C<$3> with
611the index. C<$$> is replaced with '$'. Default: C<$1 [$3]>
612
613=item text_link_list
614
615Set to format links as they appear at the footer of the body text. If
616this is set to the empty string then no list appears. C<$1>, C<$2>,
617C<$3>, C<$$> are replaced as for I<text_link_inline> and $n is
618replaced with newline. Default: C<[$3] $2>
619
620=item text_link_list_prefix
621
622A line of text produced above the list of URLs if there is one.
623Default: C<----->. $n in this is replaced with newlines.
624
531fb3bc
TC
625=back
626
99b7cef0
TC
627For example, if the configuration is:
628
629 text_link_inline="$1" ($3)
630 text_link_list_prefix=$n$n-------
631 text_link_list=($3) "$1"$n => $2
632
633and the body text is:
634
635 doclink[3]
636 link[http://www.example.com/|Example]
637
638the result will be:
639
640 "The Shop" (1)
641 "Example" (2)
642
643
644 -------
645 (1) "The Shop"
646 => http://www.yoursite.com/shop/index.html
647 (2) "Example"
648 => http://www.example.com/
649
6e3d2da5
TC
650=head2 [search]
651
652=over
653
654=item highlight_partial
655
656If this is true then partial matches will be highlight in search
657result excerpts. Default: True
658
54c97cf6
TC
659=item keep_inaccessible
660
661If this is true then resulting articles that can't be accessed by the
662user are listed in the search results. Default: false.
663
d401b996
TC
664=item wordre
665
666The default regular expression used to match words in text during
667indexing. Default: \w+
668
669=item wordre_I<fieldname>
670
671The field specific word match regular expression for the built-in
672search indexer. Default: the value of C<wordre>.
673
6e3d2da5
TC
674=back
675
61693c75
TC
676=head2 [search highlight]
677
678Sets the prefix and suffix used for highlighting matches for different
679fields.
680
681These are used by the highlight_result, excerpt, pageTitle, author,
682keywords and matchFile tags.
683
684Each field has a prefix and suffix entry. The key is
685I<fieldname>_prefix or I<fieldname>_suffix. For file fields this is
686file_I<fieldname}_prefix and file_I<fieldname}_suffix.
687
688The default prefix is <b>. The default suffix is </b>.
689
690For example you can do:
691
692 [search highlight]
693 body_prefix=<span class="searchfound">
694 body_suffix=</span>
695
6e3d2da5
TC
696=head2 [shop]
697
698=over
699
7b81711b
TC
700=item enabled
701
702Used by some templates to check if the shop is enabled. Set this to 1
703to enable the shop, or 0 to disable it.
704
57d988af
TC
705=item secureurl_articles
706
707If this is false then shop articles will not use the secureurl as their
708baseurl. Default: True
709
6e3d2da5
TC
710=item register_if_files
711
712If true the customer is required to register before checkout if there
713are any for sale files attached to products in the cart. Default: True
714
715=item require_logon
716
717If true the customer is required to be logged on before checkout,
718whether or not for sale files are attached to products in the cart.
719Default: False.
720
08123550
TC
721=item payment_types
722
723A comma-separated list of acceptable payment types. Default: 0
724
725The possible payment types are:
726
727=over
728
729=item *
730
7310 - the user enters a credit card number, name and expiry date
732
733=item *
734
7351 - the customer will send a cheque
736
737=item *
738
7392 - contact customer for details
740
741=back
742
81f3292d
TC
743Other types can be added by adding entries to the [payment type names]
744and [payment type descs] sections.
745
08123550
TC
746=item address1
747
748=item address2
749
750=item address3
751
752These are used by various shop templates to present an address that a
753cheque payment should be sent to.
754
331fd099
TC
755=item from
756
757From email address for emails sent by the shop. Overides $SHOP_FROM
758in Constants.pm
759
760=item to_name
761
762To name for emailed orders sent by the shop. Overrides $SHOP_TO_NAME
763in Constants.pm
764
765=item to_email
766
767To email for emailed orders sent by the shop. Overrides $SHOP_TO_EMAIL
768in Constants.pm
769
d09682dd
TC
770=item noencrypt
771
772If this is true then orders sent to you by the shop will not be
773encrypted. Enabling this disabled acceptance of credit card orders,
774and the default for C<payment_types> will become C<1> instead or C<0>.
775
776Please realize that other potentially commercially sensitive
777information is being sent in the clear to a central location,
778unencrypted.
779
780=item email_order
781
782If true, then the order is email to to_email, possibly with credit
783card information included. Default: $SHOP_EMAIL_ORDER.
784
d49f56a6
TC
785=item display_I<field>
786
787Used to translate the stored order field name into a presentation name
788suitable for error messages.
789
41e7c841
TC
790=item cardprocessor
791
792The name of a class to load to process credit card transactions online.
793
794Currently this can be either DevHelp::Payments::Test or
795DevHelp::Payments::Inpho.
796
26c634af
TC
797=item crypt_module
798
799Name of the encryption module to use. Default: $SHOP_CRYPTO.
800
801=item crypt_signing_id
802
803Id of the key to sign the order email with. If this is non-empty then
804the email is signed even if [basic].sign is false. Default:
805$SHOP_SIGNING_ID.
806
807=item crypt_gpg
808
809Path to the GnuPG program. Default: $SHOP_GPG
810
745a6c13 811=item crypt_passphrase
26c634af
TC
812
813Passphrase of the key used to sign the email. Default:
814$SHOP_PASSPHRASE.
815
745a6c13
TC
816=item show_card_type
817
818If true, request the card type when requesting credit card
819information. Default: False.
820
56f87a80
TC
821=item cart_entry_limit
822
823Maximum number of entries in the cart. This limits the number of
824distinct products (with options) in the cart, not the total
825quantities. Default: Unlimited.
826
6e3d2da5
TC
827=back
828
bd3a048c
AMS
829=head2 [shipping]
830
831=over
832
833=item couriers
834
835A space-separated list of modules under Courier::, e.g. "Fastway::Road
836AustraliaPost::Air". These will be made available as shipping methods
837on the checkout page.
838
839=item sourcepostcode
840
841The post code from which products are shipped.
842
843=item fastwayfranchisee
844
845The name of the Fastway franchisee used to ship products from the
846sourcepostcode.
847
848=item fastwayfranchiseecode
849
850The Fastway franchisee code for the customer, if any.
851
852=back
853
41e7c841
TC
854=head2 [Shop Order Validation]
855
856This section can contain extra order validation information, including
857specifying required fields, display names and extra validation rules.
858
6e3d2da5
TC
859=head2 [fields]
860
861=over
862
863=item title_size
864
865The maximum length of the article title field. Default: 255. Should
866not be set higher than this unless you change the database schema.
867
868=back
869
ee6577c3
TC
870=head2 [interest]
871
872Controls the interest.pl script.
873
874=over
875
876=item notify
877
878Email address that is notified of the interest. Defaults to $SHOP_FROM.
879
ca9aa2bf 880=back
ee6577c3 881
6e3d2da5
TC
882=head2 [debug]
883
884Used for debugging.
885
886=over
887
888=item logon_cookies
889
890When a user logs on, and the site url is different to the secure url
891BSE attempts to refresh to the other "side" of the site to set the
892same cookie.
893
894BSE does some simple comparisons to attempt to determine whether the
895logon form was triggered on the secure side of the site (possibly from
896the shop) or on the insecure side. Since CGI doesn't necessarily give
897us all the information required, it's possible it will guess wrong.
898
d2730773
TC
899Setting this option to 1 will enable debugging information sent to
900standard error, which will be sent to the error log on Apache. This
901probably isn't useful on IIS.
902
903=item file_unlink
904
905Reports errors to STDERR (hence to the error log on Apache) if there
906is a problem deleting the actual file when an attached file is
907removed.
908
909=item mail_encryption
910
911Reports debugging information to standard error while encrypting your
912mail.
6e3d2da5 913
2d873eb6
TC
914=item cookies
915
916Reports cookies received from the browser and sent to the browser to
917STDERR (hence to the error log on Apache.)
918
4175638b
TC
919=item dump_session
920
921If nonzero the session hash is dumped to STDERR after it is retrived
922from the database.
923
af74f0b4
TC
924=item subscription_expiry
925
926If non-zero then subscription expiry date calculations are dumped to
927STDERR.
928
efcc5a30
TC
929=item jit_dynamic_regen
930
931If non-zero then information about jit_dynamic_regen is sent to
932STDERR.
933
db7d73a7
TC
934=item ifUserCan
935
936If non-zero then the ifUserCan tag will output some trace information
937to STDERR.
938
ca9aa2bf
TC
939=back
940
941=head2 [uri]
942
943Contains various URIs.
944
945This is underused, so don't rely on it yet.
946
947=over
948
949=item cgi
950
951The URI to the CGI directory. Default: /cgi-bin
952
953=item images
954
955The URI where images are kept. Default: /images
956
957=item shop
958
959=item articles
960
9168c88c 961=back
ca9aa2bf 962
9168c88c 963=head2 [articles]
ca9aa2bf 964
9168c88c
TC
965This will provide translations from symbolic names to article ids.
966
967Currently this is used for converting article ids in the access
968control code, and for looking up the id of the shop.
6e3d2da5 969
0b406a07
TC
970=head2 [printable type]
971
972If the user supplies a template name to printable.pl then you can use
973a different content type by adding an entry to this section. The key
974is the template name, and the value is the full content type.
975
918735d1
TC
976=head2 [search index scores]
977
978This section is used when generating the search index to override the
979default scores for each field in the articles.
980
981The default scores are:
982
74b21f6d
TC
983 Field Score Notes
984 ----- ----- -----
985 title 5
986 body 3
987 keyword 4
988 pageTitle 5
989 author 4
990 summary 0
991 description 0 Products only
992 product_code 0 Products only
993 file_displayName 2 displayName for files
994 file_description 2 description for files
995 file_notes 1 notes for files
918735d1
TC
996
997=head2 [article flags]
998
999=head2 [product flags]
1000
1001=head2 [catalog flags]
1002
1003Flags that can be set for articles, products and catalogs
1004respectively. Note that flags for articles are also visible in
1005products and catalogs.
1006
1007All flag Ids are single letters or digits. Uppercase letters are
1008reserved for use by BSE internally, leaving lower-case letters and
1009digits for your own use.
1010
1011Use the id of the flag as the key, and a description of the flag as
1012it's value.
1013
95989433
TC
1014=head2 [article uris]
1015
1016Each key is an article id, the values are base URIs to store the HTML
1017form of those articles and their children under.
1018
1019=head2 [protect link]
1020
1021The keys are ids of articles that shouldn't have their link field
1022overwritten. The value should be a true value, but is otherwise
1023ignored.
1024
d09682dd
TC
1025=head2 [datadump]
1026
1027=over
1028
1029=item to
1030
1031The recipient for the data dump email sent by datadump.pl. Default:
1032$DATA_EMAIL.
1033
1034=item from
1035
1036the From for the data dump email sent by datadump.pl. Default:
1037$SHOP_FROM.
1038
1039=back
1040
2a295ea9
TC
1041=head2 [site users]
1042
1043Configuration for site users.
1044
1045=over
1046
1047=item nopassword
1048
1049If this is set to true then no passwords are required during
1050registration, a confirmation email is sent immediately upon
1051registration and that confirmation email contains a link the user can
1052use to manage their details.
1053
1054This option has some security concerns since it can leave links to the
1055user's information in the browser history. This option is not
1056recommended.
1057
1058You cannot use this to control access to the shop.
1059
1060=item require_name1
1061
1062=item require_name2
1063
1064=item require_address
1065
1066=item require_city
1067
1068=item require_state
1069
1070=item require_postcode
1071
1072=item require_telephone
1073
1074=item require_facsimile
1075
1076=item require_country
1077
1078=item require_title
1079
1080=item require_organization
1081
1082Set these to true to require the corresponding field during
1083registration, and to keep it required after modification. Default:
1084false.
1085
1086If you enable any of these, you should enable C<info_on_register> as
1087well, or modify the registration template to include the given fields.
1088
1089=item display_I<field name>
1090
1091Controls how the given field is displayed in error messages. If you
1092change the field names on the registration and/or options forms you
1093should probably change them here too. Default: internal field name
1094with the first character converted to upper-case.
1095
1096=item info_on_register
1097
1098If this is set then the user info is prompted for during user
1099registration. The information still isn't required unless the
1100appropriate require_I<field> option is set. Default: false.
1101
1102=item register_refresh
1103
1104The default URL to refresh to on completing registration if no r
1105parameter is supplied.
1106
1107=item subscribe_all
1108
1109If this is set then the subcription checkboxes are all checked on
1110registration by default. Default: false.
1111
1112The user will only receive the subscriptions if they leave them checked
1113and follow the link in the confirmation email.
1114
1115=item subscribe_I<id>
1116
1117Where I<id> is the number identifying a subscription. If this is set
1118then the subscription checkbox for that subscription will be checked
1119by default on the registration form. Default: false.
1120
1121The user will only receive the subscriptions if they leave it checked
1122and follow the link in the confirmation email.
1123
1124You can get the I<id> of a subcription by looking at the Edit link on the
1125subscriptions management page, the number after "id=" is the id.
1126
9063386f
TC
1127=item billing_on_main_opts
1128
1129If set to zero then user billing options will be managed on a separate
1130page. This is controlled by the user/options_base.tmpl template.
1131
1132=item user_register
1133
1134If set to zero then users cannot register themselves. Default: true,
1135allowing users to register themselves.
1136
cf9f9cbc
TC
1137=item notify_register
1138
1139If true then an email is sent when a new user registers on your site.
1140The email address sent to is the first set of [site
1141users].notify_register_email, [shop].from or $SHOP_FROM from
1142Constants.pm
1143
1144No email is sent if a new user is created from the administration user
1145interface.
1146
1147See also: notify_register_email, notify_register_subject.
1148
1149=item notify_register_email
1150
1151The email to sent the registration notification too. See
1152notify_register above.
1153
1154=item notify_register_subject
1155
1156The subject of the notification email sent when a new user registers.
1157Any {I<field>} is replaced with the given field from the registered
1158user. See notify_register above.
1159
1160Default: New user {userId} registered
1161
6c83a514
TC
1162=item notify_register_customer
1163
1164If non-zero then email id C<notify_register_customer> will be sent to
1165new user on registration. By default this uses template
1166user/email_register, subject "Thank you for registering" which can be
1167overridden in [email notify_register_customer]
1168
2a295ea9
TC
1169=back
1170
81f3292d
TC
1171=head2 [payment type names]
1172
1173This section and [payment type descs] are used to configure new
1174paymeny type ids.
1175
1176The key is the integer representing the payment type. The value is
1177the name used in tags for checking the payment type.
1178
1179You can also add a description (currently unused) to [payment type
1180descs].
1181
1182You should use numbers starting from 10 to avoid conflicts with future
1183BSE payment types.
1184
1185=head2 [payment type descs]
1186
1187See [payment type names].
1188
1189=head2 [payment type required]
1190
1191Set the key given by the payment type id to a value of a
1192comma-separated list of fields required for that payment type.
1193
3ae524f3
TC
1194=head2 [help style I<style-name>]
1195
1196This type of configuration section is used to set values for a style
1197of help icon. Only the C<template> and C<prefix> values are used
1198directly by the code, the others are used by the default helpicon
1199templates.
1200
1201=over
1202
1203=item prefix
1204
1205The URI to the help files for this style. Default: /help/ in style
1206"user", /admin/help/ in style "admin".
1207
1208=item template
1209
1210The template used to produce the icon. Default: helpicon in style
1211user, admin/helpicon in style "admin".
1212
1213=item icon
1214
1215URI to the help icon image. Default: /images/admin/help.gif
1216
1217=item iconwidth
1218
1219The width of the help icon image. Default: 16
1220
1221=item iconheight
1222
1223The height of the help icon image. Default: 16
1224
1225=back
1226
1227If you just want to change the help icon image for user help icons you
1228might do:
1229
1230 [help style user]
1231 icon=/images/help.gif
1232
4175638b
TC
1233=head2 [affiliate]
1234
1235=over
1236
1237=item allowed_referer
1238
1239A semi-colon (;) separated list of referer domains that are allowed to
1240link to the C<a_set> target of L<affiliate.pl>.
1241
1242If the user's browser supplies a referer header then it will be
1243checked against this list.
1244
1245=item require_referer
1246
1247If this is set then the C<a_set> target of L<affiliate.pl> will
1248require that the user's browser supply a Referer header.
1249
1250=item default_refresh
1251
1252If no C<r> parameter is supplied to the C<a_set> target of
1253L<affiliate.pl> then this is used as the default refresh.
1254
1255Default: the site base url.
1256
829c9ed9
TC
1257=item subscription_required
1258
1259This is either the numeric or text of a subscription for which the
1260affiliate must have an active subscription.
1261
fdc2b7a2
TC
1262=item flag_required
1263
1264A single letter flag which the site administrator must set for the
1265affiliate page to be displayed for the given member.
1266
ea646070
TC
1267=item set_cookie
1268
1269If this is set then affiliate.pl will set the named cookie to the
1270affiliate id.
1271
1b5a718f
TC
1272=item other_cookies
1273
1274This is a comma-separated list of other cookies that should be set by
1275the a_set target. The values for the cookies should be passed to the
1276a_set target. For example with:
1277
1278 [affiliate]
1279 other_cookies=alpha,beta
1280
1281if the url:
1282
1283 http://your.site.com/cgi-bin/affiliate.pl?a_set=1&id=someid&alpha=1&beta=2&gamme=3
1284
1285is accessed, then the cookie alpha is set to "1", beta is set to "2".
1286The cookie gamma will not be set since it's not listed.
1287
ea646070
TC
1288=item linkbaseurl
1289
1290Used as the link base URL for the afflink.tmpl side bar template when
1291an affiliate id is set. Default: example.com
1292
1293=item linkbasedesc
1294
1295Used at the text of the link for the afflink.tmpl side bar template
1296when an affiliate id is set. Default: Your Site.
1297
1298=item linkdefurl
1299
1300Used as the link URL for the afflink.tmpl side bar template when an
1301affiliate id is not set. Default: example.com
1302
1303=item linkdefdesc
1304
1305Used as the text of the link for the afflink.tmpl side bar template
1306when an affiliate id is not set. Default: Our site
1307
4175638b
TC
1308=back
1309
3c32512d
TC
1310=head2 [BSE Siteuser Images]
1311
1312Each key is the id of a member image, with a corresponding [BSE
1313Siteuser Image I<image_id>] section. The values are ignored.
1314
1315=head2 [BSE Siteuser Image I<image_id>]
1316
1317Provides information about a single member image "template".
1318
1319=over
1320
1321=item description
1322
1323Short description on the image, like "Logo". Used in error messages.
1324
1325=item help
1326
1327Longer description of the image. Accessible with the member_image tag.
1328
1329=item minwidth
1330
1331=item minheight
1332
1333=item maxwidth
1334
1335=item maxheight
1336
1337The minimum and maximum dimensions of the image.
1338
1339=item widthsmallerror
1340
1341=item heightsmallerror
1342
1343=item widthlargeerror
1344
1345=item heightlargeerror
1346
1347Error messages displayed in the when the image is outside the
1348configured dimensions.
1349
1350=item largeerror
1351
1352=item smallerror
1353
1354Default error messages for the above.
1355
1356=item maxspace
1357
1358Maximum storage the image can use in bytes. Default: 1000000.
1359
1360=item spaceerror
1361
1362Error message displayed if the image uses too much storage.
1363
1364=back
1365
ab2cd916
TC
1366=head2 [editor]
1367
1368Various editor settings.
1369
1370=over
1371
1372=item allow_thumb
1373
1374If this is non-zero the system will attempt to load the configured
1375thumbnail class, and put thumbnail images on the image manager page
1376rather than full-size images. Default: off
1377
1378=item thumbs_class
1379
1380The name of a perl class that implement's BSE's thumbnail API. At
1381this point the only class that implements that is BSE::Thumb::Imager,
1382supplied with BSE. Default: None
1383
1384=item default_thumbnail
1385
1386URI to the default thumbnail image. This is presented when the
1387runtime production of a thumbnail image fails.
1388
1389=item default_thumbnail_width
1390
1391=item default_thumbnail_height
1392
1393Dimensions of the default thumbnail image.
1394
1395=item default_thumbnail_alt
1396
1397Alt text for the default thumbnail image.
1398
1761af79
TC
1399=item check_modified
1400
1401If this is true then BSE will check the value of the lastModified
1402parameter passed against the value in the article. If these don't
1403match the article isn't saved and is redisplayed with an error
1404message. This provides simple protection against one user saving
1405changes over those made by another.
1406
ab2cd916
TC
1407=back
1408
1409=head2 [thumbnails]
1410
1411=over
1412
1413=item max_width
1414
1415=item max_height
1416
1417=item max_pixels
1418
1419Default values for the thumbimage tag.
1420
1421=back
1422
829c9ed9
TC
1423=head2 [includes]
1424
1425Each value is used as the relative or absolute name of a file or
1426directory to load more configuration data from.
1427
1428The keywords must remain unique.
1429
1430Only the [includes] section from bse.cfg itself is used to locate more
1431configuration data.
1432
1433If the value references a directory, all files with an extension of
1434C<.cfg> are read for configuration data.
1435
1436The order the files are read (which later files overriding older
1437files) is:
1438
1439=over
1440
1441=item 1.
1442
1443bse.cfg is read
1444
1445=item 2.
1446
1447the entries in [includes] are sorted alphabetically (or rather
1448asciily), so an entry with key "A" is read before one with key "B",
1449one with key "01" is read before "02", but key "10" would be read
1450I<before> key "2".
1451
1452=item *
1453
1454if an entry is a file then that is read and the values merged.
1455
1456=item *
1457
1458if an entry is a directory, then that is scanned and the files found
1459read alphabetically as above.
1460
1461=back
1462
6a8a6ac5
TC
1463=head2 [error_img]
1464
1465This is used to configure the error icon displayed next to fields that
1466fail validation.
1467
1468=over
1469
1470=item image
1471
1472URI to the image file.
1473
1474=item width
1475
1476=item height
1477
1478The width and height of the error icon image.
1479
1480=back
1481
fdc2b7a2
TC
1482=head2 [site user flags]
1483
1484Flags that can be set for site users.
1485
1486All flag Ids are single letters or digits. Uppercase letters are
1487reserved for use by BSE internally, leaving lower-case letters and
1488digits for your own use.
1489
1490Use the id of the flag as the key, and a description of the flag as
1491it's value.
1492
deae2a52
TC
1493=head2 [article defaults]
1494
1495=head2 [catalog defaults]
1496
1497=head2 [product defaults]
1498
1499These sections contain defaults values for the corresponding article
1500types.
1501
1502Each key is the name of a column for the article type.
1503
1504If an entry is not found in [catalog defaults] then [article defaults]
1505is also checked.
1506
1507If an entry is not found in [product defaults] then [article defaults]
1508is also checked.
1509
1510These sections are checked B<after> the C<[children of >I<id>C<]> and
1511C<[level >I<level>C<]> sections.
1512
1513These defaults are used when creating an article where no value is
1514supplied, they can also be accessed via the <:default I<name>:> tag.
1515
1c3e5303
TC
1516=head2 [newsletter filters]
1517
1518Contains C<criteria>I<index> entries starting from C<criteria1>, then
1519C<criteria2>, etc.
1520
1521Each entry consists of a filter class name, followed by a ; followed
1522by data passed to that filter.
1523
1524 ; user the original SQL based filter, configured from
1525 ; section [foo]
1526 criteria1=BSE::NLFilter::SQL;foo
1527
1528See the documentation for each filter to configure the filters.
1529
c2096d67
TC
1530=head2 [Query Groups]
1531
1532The key of each entry is the numeric identifier of a query group, the
1533values are the name of the query group. For example:
1534
1535 [query groups]
1536 1=some name
1537
1538 [query group some name]
1539 sql=select id from site_users where id = ? and name1 like '%some%'
1540
1541Each entry also has a corresponding [Query Group I<name>] section.
1542
1543=head2 [query group I<name>]
1544
1545This section corresponds to an entry in [Query Groups].
1546
1547=over
1548
1549=item sql
1550
1551This is an SQL statement. One placeholder is required and is passed
1552the siteuser id (primary key) of the user to be checked. If this
1553query returns I<any> rows then the user is considered part of the
1554group.
1555
1556=back
1557
16901a2a
TC
1558=head2 [template types]
1559
1560Each key is a template name, the value is the content type to be used
1561when displaying the template dynamically.
1562
8f84f3f1
TC
1563=head2 [body class]
1564
1565This section defines CSS class names for BSE's body text link tags.
1566The key is the tag name, the value is the CSS class to be used.
1567
1568By default the class used is the same as the name of the tag, but you
1569can switch this off by adding an entry setting the class to the empty
1570string, for example:
1571
1572 ; no class attribute for any of the links
1573 [body class]
1574 link=
1575 poplink=
1576 doclink=
1577 popdoclink=
1578
1579You can set p here too to set the class for paragraphs generated as
1580body text. By default no class is set.
1581
def1a923
TC
1582=head2 [popimage]
1583
1584Controls the behaviour of the window displayed by the popimage[] body
1585text tag. If the Javascript for this has been customized then this
1586may not apply.
1587
1588=over
1589
1590=item extrawidth
1591
1592=item extraheight
1593
1594Extra width and height for the window beyond the size of the image.
1595Default: no extra width or height.
1596
1597=item popmiddle
1598
1599If set to non-zero popimage[] will attempt to centre the popup within
1600the current window. Default: 0.
1601
1602=back
1603
1604=over
1605
1606=back
1607
41e7c841
TC
1608=head2 [inpho]
1609
1610This is used to configure the DevHelp::Payments::Inpho module.
1611
1612=over
1613
1614=item test
1615
1616If this is set then the test parameters are used instead of the
1617product values.
1618
1619=item url
1620
1621The URL to process requests through.
1622
1623Default: https://extranet.inpho.com.au/cc_ssl/process
1624
1625=item user
1626
1627Inpho supplied user name.
1628
1629=item password
1630
1631Inpho supplied password.
1632
1633=item test_url
1634
1635The URL to process test requests through.
1636
1637=item test_user
1638
1639The user to supply to test requests.
1640
1641=item test_password
1642
1643The password to supply to test requests.
1644
1645=back
1646
f2bf0d11
TC
1647=head2 [custom]
1648
1649This section controls whether some custom class methods are called:
1650
1651=over
1652
1653=item saveopts
1654
1655If this is non-zero then siteuser_saveopts is called.
1656
1657=back
1658
0a66f55c
AO
1659=head2 [levelI<level> menus]
1660
1661Where I<level> is the article level at which the defined menu options will be available.
1662Configure each menu value and description as I<key> and I<value>.
1663
1664=over
1665
1666For example:
1667
1668 [level1 menus]
1669 0=Default
1670 1=Sidebar
1671 2=Footer
1672
1673To create a menus using such values, use the "allkids_of" iterator "filter" option.
1674
1675For example:
1676
1677 <:iterator begin allkids_of -1 filter: [menu] == 2 :>
1678
1679=back
1680
37726cc9
AO
1681=head2 [title alias]
1682
1683Enable the "titleAlias" article field and set which level it will be available.
1684
1685=over
1686
1687=item levelI<level>
1688
1689Where I<level> is the article "level" for which the "titleAlias" field should be enabled. To enable
1690set the value to non-zero.
1691
1692For example:
1693
1694 [title alias]
1695 level1=1
1696
1697The "titleAlias" can be used as an alternate "short" title for the given article, especially useful
1698for space critical iterated menus. A template conditional can be used to display the "titleAlias"
1699in place of the article "title" when appropriate.
1700
1701=back
1702
195977cd
TC
1703=head2 [thumb geometries]
1704
1705Each key represents a geometry identifier for use by the thumbimage[],
1706gthumbimage[] body text tags and the <:thumbimage ...:>, <:gthumbimage
b864cc90 1707...:>, <:dthumbimage ...:> template tags.
195977cd
TC
1708
1709The key is the geometry identifier, the value is the geometry string
1710as follows.
1711
1712The geometry string consists of:
1713
1714=over
1715
1716=item *
1717
1718dimensions
1719
1720=item *
1721
1722crop flag - if present
1723
1724=item *
1725
1726optional fill
1727
1728=back
1729
1730The dimensions can be in any of the following forms:
1731
1732=over
1733
1734=item *
1735
1736<width>x<height> - the desired maximum width and height. eg 200x150
1737
1738=item *
1739
1740<width>x - the desired width, with the height calculated
1741proportionally based on the source image size
1742
1743=item *
1744
1745x<height> - the designed height, with the width calculated
1746proportionally based on the source image size.
1747
1748=item *
1749
1750<size> - the desired maximum size in both directions. so "200" is
1751equivalent to "200x200"
1752
1753=back
1754
1755The crop flag is a single letter "c", if present then the image should
1756be scaled so the smaller dimension matches the requested size, and the
1757longer dimension will be cropped to fit.
1758
1759The fill if present is: fill(color) where color is a color recognized
1760by the underlying graphics implementation. This should be at least
1761hex web colors without the #, eg fill(FF0000) will fill with red.
1762
b864cc90
TC
1763=head2 [thumb classes]
1764
1765Each key represents a geometry identifier for use by the thumbimage[],
1766gthumbimage[] body text tags and the <:thumbimage ...:>, <:gthumbimage
1767...:>, <:dthumbimage ...:> template tags.
1768
1769The value is used as the class for the generated img tag.
1770
510a9ee7
TC
1771=head2 [targets]
1772
1773Each value represents a handler or script name for the <:dyntarget
1774I<script> I<target> ...:> tag.
1775
1776Each key has a TARGET version and a no-TARGET version, with the key
1777suffixed with C<_n>.
1778
1779The default C<nuser> target is C</cgi-bin/nuser.pl/user/TARGET>. The
1780default no-target C<nuser> is C</cgi-bin/nuser.pl/user>.
1781
1782For other targets the default is
1783C</cgi-bin/>I<script>C<.pl?a_TARGET=1> and
1784C</cgi-bin/>I<script>C<.pl>.
1785
1786The string C<TARGET> is replaced with the target specified in the
1787dyntarget tag.
1788
1789This, along with dyntarget is intended to allow a more "Web 2.0" type
1790of access to BSE. eg. you might set:
1791
1792 [targets]
1793 shop=/xshop/TARGET
1794 shop_x=/xshop/
1795
1796and have a rewrite rule:
1797
1798 RewriteRule ^/xshop/(.*)$ /cgi-bin/nuser.pl/shop/$1 [PT]
1799
8a153d74
TC
1800=head2 [popimage class I<classname>]
1801
1802This defines the settings for a class of images generated by the
1803popimage[] and gpopimage[] body text markup tags. For example, the
1804settings for C<popimage[imageid|foo]> can be found in section
1805C<[popimage class foo]>.
1806
1807=over
1808
1809=item html
1810
1811The html generated for this class. Tags of the form
1812C<{>I<identifier>C<}> are replaced, where I<identifier> can be
1813C<inline_> or C<outline_> followed by an image field name, for example
1814C<inline_src> is the URL to the inline image.
1815
1816Default: <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>
1817
1818The default may be tuned as needed.
1819
1820=item inline
1821
1822The inline image geometry. Default: editor (the value used for
1823thumbnails on the admin side)
1824
1825=item outline
1826
1827The outline image geometry. If no value is supplied then the original
1828image values are used.
1829
1830=back
1831
0c2e7f7a
TC
1832=head2 [mail resources]
1833
1834Each key is the identifier of a file that can be attached to
1835BSE::ComposeMail emails. The value is comma separated filename,
1836content type, inline status.
1837
1838The files are searched for through the template search mechanism, so
1839the filename can be relative to either the master or local templates
1840directories.
1841
1842If the content type is not supplied, if the filename end in gif, png
1843or jpg the appropriate content type is used, otherwise
1844application/octet-stream.
1845
1846If the inline status is not supplied then images are considered
1847inline, and other files arent.
1848
a53374d2
TC
1849=head2 [shop registration]
1850
1851Each key represents a message id from attempts to checkout. Except
1852the all key which covers all cases.
1853
1854If the C<all> key or the message id key is non-zero then the checkout
1855page will redirect to registration instead of login if the cart or
1856configuration requires that the user be logged in.
1857
3f36e485
TC
1858=head2 [template I<template-name>]
1859
1860Settings for articles based on a particular template.
1861
1862=over
1863
1864=item no_cache_dynamic
1865
1866Controls whether a cache-control: no-cache header will be produced.
1867Can be overridden with the A and B article flags. If not set the
1868value of [article].no_cache_dynamic is used.
1869
1870=back
1871
1872=head2 [article]
1873
1874Global settings for articles.
1875
1876=over
1877
1878=item no_cache_dynamic
1879
1880Controls whether a cache-control: no-cache header will be produced.
1881Can be overridden with the A and B article flags or [template
1882I<template-name>].no_cache_dynamic. If not set the value of
1883[basic].no_cache_dynamic is used.
1884
1885=back
1886
c6fc339f
TC
1887=head2 [recaptcha]
1888
1889For the <:recaptcha:> tag currently only used for fmail.pl.
1890
1891=over
1892
1893=item api_public_key
1894
1895=item api_private_key
1896
1897The public and private key you receive when you register with reCAPTCHA.
1898
1899=item error_I<error_code>
1900
1901Replace the error message for the given I<error_code> where
1902I<error_code> is the reCAPTCHA error code
1903(eg. "incorrect-captcha-sol") with dash replaced by underscore.
1904
1905eg.
1906
1907 error_incorrect_captch_sol=VERY BAD INPUT
1908
1909=back
1910
61551101
TC
1911=head1 AUTHOR
1912
1913Tony Cook <tony@develop-help.com>
1914
1915=cut