User: docelic
Date: 2005-08-12 22:33:41 GMT
Modified: guides faq.xml
Modified: refs CookieName ImageDir
Added: refs HostnameLookups HotDBI ImageDirInternal
Added: ImageDirSecure SecureURL
Log:
- small fixes
- five new
Revision Changes Path
1.5 +25 -31 xmldocs/guides/faq.xml
rev 1.5, prev_rev 1.4
Index: faq.xml
===================================================================
RCS file: /var/cvs/xmldocs/guides/faq.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- faq.xml 9 Aug 2005 17:01:01 -0000 1.4
+++ faq.xml 12 Aug 2005 22:33:40 -0000 1.5
@@ -1975,36 +1975,40 @@
</answer></qandaentry>
<!--
-
<qandaentry>
<question><para>Optimizing lists</para></question>
<answer><para>
-
-<para>
-
&IC; has powerful search capabilities that allow you to produce
lists of items for use in category lists, product lists, indexes, and other
navigation tools.
+</para><para>
These are a two-edged sword, though. Lists of hundreds or thousands of entries
can be returned, and techniques that work well displaying only a few items may
slow to a crawl when a large list is returned.
+</para><para>
In general, when you are returning one item (i.e. a flypage) or a small list
-(i.e. a shopping cart) you can be pretty carefree in your use of [if ...]
-and [calc] and [perl] tags. When there are hundreds of items, though, you cannot;
-each complex test or embedded &PERL; snippet causes the Safe module to have to
-evaluate code, and each ITL tag requires parsing and argument building.
-
-The Safe module is pretty fast considering what it does, but it can only generate
-a few thousand instances per second even on a fast system. And the ITL tag
+(i.e. a shopping cart) you can be pretty carefree in your use of &tag-if;,
+&tag-calc; and &tag-perl; tags. When there are hundreds of items, though,
+you cannot;
+each complex test or embedded &PERL; snippet causes the
+<classname>Safe</classname> module to have to
+evaluate code, and each &glos-ITL; tag requires parsing and argument building.
+</para><para>
+
+The <classname>Safe</classname> module is pretty fast considering what it does, but it can only generate
+a few thousand instances per second even on a fast system. And the
+&glos-ITL; tag
parser can likewise only parse thousands of tags per CPU second.
+</para><para>
What to do? You want to provide complex conditional tests but you don't want
your system to slow to a crawl. Luckily, there are techniques which can speed
up complex lists by orders of magnitude.
+</para><para>
-H3: Benchmarking
+Benchmarking
A non-precise benchmark of different iteration options can be done
with the following global UserTag. Place this in a file in the
@@ -2320,7 +2324,7 @@
You can also compile routines at the time of the list execution
with [item-sub routine] CODE [/item-sub]. This means only one
-Safe evaluation is done - every time the [loop-exec routine]
+<classname>Safe</classname> evaluation is done - every time the [loop-exec routine]
is called, it is done fast as a call to the routine. This can be
10 times or more faster than separate [calc] calls, or 5 times
faster than separate [PREFIX-calc] calls.
@@ -2431,14 +2435,13 @@
</para>
</qandaentry>
-
<qandaentry>
- <question><para>Using &ic; with oracle</para></question>
+ <question><para>Using Interchange with Oracle</para></question>
<answer><para>
-<para>
-
-N:Question: should we be using the DBI ChopBlanks setting for Oracle or is &IC; trimming trailing space from CHAR fields itself?
+should we be using the DBI ChopBlanks setting for Oracle or is &IC;
+trimming trailing space from CHAR fields itself?
+</para><para>
IC daemon user should have environment &glos-variable;s ORACLE_HOME and
possibly NLS_LANG set.
@@ -2552,25 +2555,16 @@
</para>
</qandaentry>
+</qandadiv>
-
-<qandaentry>
- <question><para>&PERL;/&ic; faq</para></question>
-<answer><para>
-
-<para>
-
-</para>
-</answer></qandaentry>
+<qandadiv><title>Perl/Interchange FAQ</title>
<qandaentry>
<question><para>Cameron Prince's local &PERL; installation how-to</para></question>
<answer><para>
-<para>
-
-+Login as user. In this example, we'll call the user bob. Bob's home directory is /home/bob.
+Login as user. In this example, we'll call the user bob. Bob's home directory is /home/bob.
+Get the perl tarball and extract it in /home/bob. (tar -xzvf perl-5.6.0.tar.gz)
@@ -2646,7 +2640,7 @@
SQL::Statement is up to date.
Storable is up to date.
DBI is up to date.
-Safe::Hole is up to date.
+<classname>Safe</classname>::Hole is up to date.
You may need to get the modules via ftp and install them by hand. For instance, during the test used to create this document, I had to get URI and LWP and install by hand before everything reported that it was up to date. To do this, follow these steps:
1.4 +3 -5 xmldocs/refs/CookieName
rev 1.4, prev_rev 1.3
Index: CookieName
===================================================================
RCS file: /var/cvs/xmldocs/refs/CookieName,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- CookieName 12 Aug 2005 12:41:51 -0000 1.3
+++ CookieName 12 Aug 2005 22:33:40 -0000 1.4
@@ -28,6 +28,9 @@
By default, &IC; cookie planted in user's browser consists of
a session ID followed by a colon followed by an IP address, username
or domain name.
+</para><para>
+If the cookie is generated by another program and &conf-CookieName;
+is set appropriately, &IC; will take it over without modification.
__END__
__NAME__ example: Defining CookieName
@@ -36,8 +39,3 @@
</programlisting>
__END__
-
-THE THING HERE is that IC will respect the cookie it finds if
-CookieName is set, and won't override it with a new one like it
-does in standard setup when you provide the cookie but IC doesn't like
-it because it's say, expired.
1.2 +60 -22 xmldocs/refs/ImageDir
rev 1.2, prev_rev 1.1
Index: ImageDir
===================================================================
RCS file: /var/cvs/xmldocs/refs/ImageDir,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- ImageDir 11 Jun 2005 08:29:00 -0000 1.1
+++ ImageDir 12 Aug 2005 22:33:40 -0000 1.2
@@ -1,31 +1,69 @@
+__NAME__ purpose
+specify base location for all IMG and INPUT src= files
+__END__
-__NAME__ example: Setting PageDir depending on current locale
-To use a different page directory for different locales, say French and
-English, help yourself with the robust &conf-Locale; directive:
-<programlisting>
-# Establish the default at startup
-PageDir english
-# Establish locale-dependent directories
-Locale fr_FR PageDir francais
-Locale en_US PageDir english
-</programlisting>
-To fully understand the example and implicitly presented &IC; features, make
-sure you're familiar with &glos-internationalization; and &glos-locale;
-glossary
-entries.
+__NAME__ see also
+ImageDir, ImageDirSecure, VendURL, SecureURL,no_image_rewrite
__END__
+__NAME__ synopsis
+<group choice='req'>
+ <arg choice='plain'><replaceable>location</replaceable></arg>
+</group>
+__END__
+
+
+__NAME__ description
+&conf-ImageDir; is one of quite basic settings in every &ccf;.
+</para><para>
+The directive specifies a base location, accessible over the web,
+where &IC; should look for IMG and INPUT &glos-HTML;
+<literal>src=</literal> file specifications.
+To be precise, actually, this setting applies to image locations mentioned
+in <![CDATA[
+<img src="">, <input src="">, <body background="">, <table background=""> and table subelements (<th>, <tr> and <td>).]]>
+</para><para>
+As you might know, &IC; keeps its pages in a special directory
+<filename class='directory'>pages/</filename> (which is a subdirectory of
+your catalog's &glos-CATROOT;). That directory can be readable only by the
+&IC; user, and contents in it cannot be accessed by the web server without
+&IC; mediating the connection. This directory is generally supposed to
+only contain directories and Interchange-enabled &glos-HTML; pages,
+and nothing else.
+</para><para>
+It is therefore obvious that an alternative way has to be provided
+to serve images. When you define &conf-ImageDir;, &IC; will appropriately
+and transparently prefix all &lt;img src=...&gt; &glos-HTML; tags with
+your value.
+</para><para>
+For example, if the &glos-link-program; and images are kept on the same
+server, and images are found in your web server's document root,
+in the <filename class='directory'>images/</filename> subdirectory, then
+you would set &conf-ImageDir; to <literal>/images/</literal>.
+With this setting in effect, a link such as &lt;img src="order.png"&gt;
+would be changed to &lt;img src="/images/order.png"&gt;.
+__END__
-LI1: ImageDir
+__NAME_ notes
+<emphasis role='bold'>In most setups, you want to include the
+trailing "<literal>/</literal>" at the end to achieve the intended behavior.
+</emphasis>
+</para><para>
+As with all directives, &conf-ImageDir; can be made locale-dependent to
+elegantly allow for multilingual setups.
+__END__
-.To use a different image directory for different locales, set the C<ImageDir> key. To have two separate language button sets, French and English, set:
+__NAME__ example: Setting ImageDir
+<programlisting>
+ImageDir /images/
+</programlisting>
+__END__
-!block example; listitem=2
-# Establish the default at startup
-ImageDir /images/english/
-Locale fr_FR ImageDir /images/francais/
-Locale en_US ImageDir /images/english/
-!endblock
+__NAME__ example: Setting ImageDir using full URL specification
+<programlisting>
+ImageDir http://images.&def-domain;/images/
+</programlisting>
+__END__
1.1 xmldocs/refs/HostnameLookups
rev 1.1, prev_rev 1.0
Index: HostnameLookups
===================================================================
__NAME__ purpose
perform hostname lookups (DNS resolving)?
__END__
__NAME__ synopsis
<group choice='req'>
<arg choice='plain'>No</arg>
<arg choice='plain'>Yes</arg>
</group>
__END__
__NAME__ description
The directive specifies whether to perform DNS lookups to resolve
remote users' hostname from their IP address. Hostnames are required
for some facilities, such as &conf-RobotHost; (use &conf-RobotIP; if you
want to keep DNS lookups off).
</para><para>
If the web server is configured to perform hostname lookups itself, then
this directive should remain disabled.
__END__
__NAME__ example: Enabling HostnameLookups
Put the following in &gcf;:
<programlisting>
HostnameLookups Yes
</programlisting>
__END__
1.1 xmldocs/refs/HotDBI
rev 1.1, prev_rev 1.0
Index: HotDBI
===================================================================
__NAME__ purpose
specify catalogs that should use persistant database connections
__END__
__NAME__ synopsis
<group choice='req'>
<arg choice='plain' rep='repeat'><replaceable>catalog</replaceable></arg>
</group>
__END__
__NAME__ description
Specify catalogs that should use persistent database connections.
When a connection is persistent, it will be maintained and cached without
reconnecting for every page request.
__END__
__NAME__ example: Specifying HotDBI
<programlisting>
HotDBI tutorial1
</programlisting>
__END__
TODO: so what exactly happens? Where is the connection cached?
In IC instance? In user session? Why wouldn't all people want this?
1.1 xmldocs/refs/ImageDirInternal
rev 1.1, prev_rev 1.0
Index: ImageDirInternal
===================================================================
__NAME__ purpose
(obsolete)
__END__
1.1 xmldocs/refs/ImageDirSecure
rev 1.1, prev_rev 1.0
Index: ImageDirSecure
===================================================================
__NAME__ purpose
specify base location for all IMG and INPUT src= files served over HTTPS
__END__
__NAME__ see also
ImageDir, ImageDirSecure, VendURL, SecureURL,no_image_rewrite
__END__
__NAME__ synopsis
<group choice='req'>
<arg choice='plain'><replaceable>location</replaceable></arg>
</group>
__END__
__NAME__ description
The directive specifies a base location, accessible over the web,
where &IC; should look for IMG and INPUT &glos-HTML;
<literal>src=</literal> file specifications,
<emphasis role='bold'>when the originating page is being served
over a secure connection (HTTPS)</emphasis>.
To be precise, actually, this setting applies to image locations mentioned in <![CDATA[ <img src="">, <input src="">, <body background="">, <table background=""> and table subelements (<th>, <tr> and <td>).]]>
</para><para>
This is useful if you are using separate HTTPS and HTTP servers, and cannot
make the image directory path heads match. If &conf-ImageDirSecure; is
unspecified, it defaults to &conf-ImageDir;.
__END__
__NAME_ notes
<emphasis role='bold'>In most setups, you want to include the
trailing "<literal>/</literal>" at the end to achieve the intended behavior.
</emphasis>
</para><para>
As with all directives, &conf-ImageDirSecure; can be made locale-dependent to
elegantly allow for multilingual setups.
</para><para>
If you count on &conf-ImageDirSecure; being unspecified and falling back
to &conf-ImageDir;, then you don't want to have your &conf-ImageDir;
location starting with "<literal>http://</literal>".
__END__
__NAME__ example: Setting ImageDirSecure
<programlisting>
ImageDir /images.ssl/
</programlisting>
__END__
1.1 xmldocs/refs/SecureURL
rev 1.1, prev_rev 1.0
Index: SecureURL
===================================================================
__NAME__ purpose
specify base URL of the Interchange catalog link program, when pages are served over HTTPS
__END__
__NAME__ see also
VendURL, ImageDirSecure
__END__
__NAME__ synopsis
<group choice='req'>
<arg choice='plain'><replaceable>URL</replaceable></arg>
</group>
__END__
__NAME__ description
The directive specifies a base catalog URL, that is, it's entry point
(usually a cgi-bin link program), <emphasis role='bold'>when pages
are served over a secure connection (HTTPS)</emphasis>.
__END__
__NAME__ notes
&conf-SecureURL; value can also be a relative path, with or without the
protocol and hostname specification.
__END__
__NAME__ example: Setting SecureURL
Put the following lines in &ccf;:
<programlisting>
SecureURL https://&def-hostname;/cgi-bin/ic/tutorial
</programlisting>
__END__