[docs] xmldocs - docelic modified 4 files
docs at icdevgroup.org
docs at icdevgroup.org
Tue Sep 21 05:28:29 EDT 2004
User: docelic
Date: 2004-09-21 09:28:29 GMT
Modified: . TODO
Modified: guides iccattut.xml
Modified: docbook docbookxi.dtd common.xsl
Log:
- guides/iccattut.xml:
- wording/spelling fixes
- adding proper tagging (<literal>s, <mv>s)
- adding some more descriptions and footnotes
- general improvements
- docbook/*: introduced the new <mv> tag to identify form variables (mv_*)
- TODO: temporary items (to be cleared soon)
Revision Changes Path
1.17 +5 -0 xmldocs/TODO
rev 1.17, prev_rev 1.16
Index: TODO
===================================================================
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- TODO 18 Sep 2004 22:23:35 -0000 1.16
+++ TODO 21 Sep 2004 09:28:28 -0000 1.17
@@ -28,6 +28,8 @@
and "etc/profiles.order" and 2 sections after it and below
- at the top where describing IC, mention it's built on Perl and ITL
- replace [area search] in phase5 with better (file and directory)
+ - replace <tag> with <code> where putting tag alone in the source would work.
+ - explain syntax accepted in profile files
DOCUMENTATION SYSTEM:
@@ -103,3 +105,6 @@
----
+guibutton
+mv
+literal for values
1.18 +45 -42 xmldocs/guides/iccattut.xml
rev 1.18, prev_rev 1.17
Index: iccattut.xml
===================================================================
RCS file: /var/cvs/xmldocs/guides/iccattut.xml,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- iccattut.xml 20 Sep 2004 17:23:44 -0000 1.17
+++ iccattut.xml 21 Sep 2004 09:28:28 -0000 1.18
@@ -99,9 +99,9 @@
<sect2 id='Introduction'>
<title>Introduction</title>
<para>
- Welcome to the &IC; Catalog Building Tutorial. Interchange originally started as an electronic cart and database display system, but over time it developed into a general application server.
+ Welcome to the &IC; Catalog Building Tutorial. Interchange originally started as an electronic cart and database display system focused on e-commerce, but over time it developed into a general application server.
</para> <para>
- The simple Interchange <firstterm>catalog</firstterm> that we will create during this tutorial should give you a feel of the basic Interchange system. It should also be considered a stepping stone to a more complete and functional Interchange-enabled website. The tutorial will rely as much as possible on default settings to accentuate ideas instead of implementation. It will use as few of Interchange's capabilities as possible, while still building a usable website (an on-line store in our example). <emphasis>The resulting site will be simple but usable</emphasis>. The value of this tutorial is in the explanations of the general Interchange ideas and small <emphasis>ready to use</emphasis> examples to get you up to speed.
+ The simple Interchange <firstterm>catalog</firstterm> that we will create during this tutorial should give you a feel of the basic Interchange system. It should also be considered a stepping stone to a more complete and functional Interchange-enabled website. The tutorial will rely as much as possible on default settings to accentuate ideas instead of implementation. It will use as few of Interchange capabilities as possible, while still building a usable website (an on-line store in our example). <emphasis>The resulting site will be simple but usable</emphasis>. The value of this tutorial is in the explanations of the general Interchange ideas and small <emphasis>ready to use</emphasis> examples to get you up to speed.
</para> <para>
It is recommended that you create the files used in this tutorial yourself. You will learn more by creating the directory structure and using your favorite text editor to create files in the proper places on your own system as they are discussed.
</para> <para>
@@ -317,7 +317,7 @@
So the basic <filename>/var/lib/interchange/catalogs/tutorial/catalog.cfg</filename> config file should look like this:
</para> <para>
<programlisting>
-<xi:include parse='text' href='../files/tutorial-phase1/catalog.cfg'></xi:include>
+<xi:include parse='text' href='../files/tutorial-phase1/catalog.cfg'/>
</programlisting>
</para>
</sect2>
@@ -327,7 +327,7 @@
<para>
The <database class='table'>products</database> database we mentioned, kept in <filename>products/products.txt</filename>, will serve two purposes. It will provide Interchange with the layout of the products database table and it will also provide the data. When Interchange comes around to parse the products.txt file, it will expect the first line to contain the names of the fields for the database table (the <database class='field'>sku</database>, <database class='field'>description</database> and <database class='field'>price</database> fields are mandatory for a products database, but you can add arbitrary other fields as you see fit). The first field in the list is expected to be the primary key (unique identifier) for the row. In most cases you are going to use the <firstterm>SKU</firstterm> ("Stock Keeping Unit") as the unique identifier for each product. The simple store that we are going to build will sell tests. You can choose another sample product line, but it is recommended that you keep it simple. Create the file <filename>products/products.txt</filename>, separating fields <emphasis>with a single TAB</emphasis>:
<programlisting>
-<xi:include parse='text' href='../files/tutorial-phase1/products/products.txt'></xi:include>
+<xi:include parse='text' href='../files/tutorial-phase1/products/products.txt'/>
</programlisting>
</para> <para>
You may notice that the columns don't line up in your text editor. This is the nature of tab-delimited files. Do not try to fix these.
@@ -379,7 +379,7 @@
<title>CATROOT/top</title>
<para>
<programlisting>
-<xi:include parse='text' href='../files/tutorial-phase1/top'></xi:include>
+<xi:include parse='text' href='../files/tutorial-phase1/top'/>
</programlisting>
</para>
</sect2>
@@ -388,7 +388,7 @@
<title>CATROOT/left</title>
<para>
<programlisting>
-<xi:include parse='text' href='../files/tutorial-phase1/left'></xi:include>
+<xi:include parse='text' href='../files/tutorial-phase1/left'/>
</programlisting>
</para>
</sect2>
@@ -397,7 +397,7 @@
<title>CATROOT/bottom</title>
<para>
<programlisting>
-<xi:include parse='text' href='../files/tutorial-phase1/bottom'></xi:include>
+<xi:include parse='text' href='../files/tutorial-phase1/bottom'/>
</programlisting>
</para>
</sect2>
@@ -426,7 +426,7 @@
<para>
Tags can span multiple lines which helps readability when the tags have a large number of (long) options. There's a whole lot of tags available (around 200 in Interchange 5.2), but in this tutorial very few will be addressed. For a complete listing of the ITL tags, see the <!-- XXX <olink targetdoc='ictags' targetptr='ictags'>-->Interchange Tags Reference<!--</olink>-->.
</para> <para>
- The first tag we'll use is going to be the <tag>include</tag> tag; it reads the specified file (relative to the catalog directory - CATROOT), reparses it for any Interchange tags, and puts the final result in place of the tag. We'll demonstrate that now on the next page you'll need to create.
+ The first tag we'll use is going to be the <tag>include</tag> tag; it reads the specified file (relative to the catalog directory - CATROOT), re-parses it for any Interchange tags, and puts the final result in place of the tag. We'll demonstrate that now on the next page you'll need to create.
</para>
</sect2>
@@ -437,7 +437,7 @@
</para> <para>
Save the following text as <filename>pages/index.html</filename>. This will create a page to test that everything works so far.
<programlisting>
-<xi:include parse='text' href='../files/tutorial-phase1/pages/index.html'></xi:include>
+<xi:include parse='text' href='../files/tutorial-phase1/pages/index.html'/>
</programlisting>
</para> <para>
Interchange pages in the <filename class='directory'>pages/</filename> directory (or elsewhere) must have the .html suffix. You can omit the suffix in both your URLs when accessing pages, and in the tags you call (such as <tag>page</tag>), but the files on the disk must be properly named.
@@ -566,7 +566,7 @@
</para> <para>
Your finished <filename>pages/index.html</filename> page should look like this:
<programlisting>
-<xi:include parse='text' href='../files/tutorial-phase2/pages/index.html'></xi:include>
+<xi:include parse='text' href='../files/tutorial-phase2/pages/index.html'/>
</programlisting>
</para> <para>
Test it by simply refreshing the <filename>index.html</filename> page in your browser.
@@ -580,7 +580,7 @@
</para> <para>
For example, if you request the <filename>0198.html</filename> page, Interchange first checks if that specific page exists (<filename class='directory'>pages/0198.html</filename>). If one is not found, it searches the products database table for a product with that ID 0198. If successful, it then creates that product page <emphasis>on the fly</emphasis> using <filename>pages/flypage.html</filename>. When constructing the flypage, the entire product record for the requested product is available through the <tag>item-field</tag> tag (similar to the <tag>loop-field</tag> tag). To create a fly page, type the following code and save it as <filename>pages/flypage.html</filename>.
<programlisting>
-<xi:include parse='text' href='../files/tutorial-phase2/pages/flypage.html'></xi:include>
+<xi:include parse='text' href='../files/tutorial-phase2/pages/flypage.html'/>
</programlisting>
</para>
</sect2>
@@ -592,7 +592,7 @@
</para> <para>
It is a good idea to display an error page when Interchange is asked for an unknown page. To create a missing page for display, type the following and save it as <filename>special_pages/missing.html</filename>.
<programlisting>
-<xi:include parse='text' href='../files/tutorial-phase2/special_pages/missing.html'></xi:include>
+<xi:include parse='text' href='../files/tutorial-phase2/special_pages/missing.html'/>
</programlisting>
</para> <para>
The addition of this page ensures that users see your error message instead of a mysterious server error if they mistype the URL.
@@ -645,7 +645,7 @@
</para> <para>
The standard demo catalog has a full-featured shopping basket available for use, but this tutorial teaches you to build your own simple one. The shopping basket items can be accessed using a set of tags that have an <tag>item</tag> prefix. Put the following code in the new <filename>pages/ord/basket.html</filename> file. The section that follows explains the tags used.
<programlisting>
-<xi:include parse='text' href='../files/tutorial-phase3/pages/ord/basket.html'></xi:include>
+<xi:include parse='text' href='../files/tutorial-phase3/pages/ord/basket.html'/>
</programlisting>
</para> <para>
The basket items can be accessed one at a time by using the <tag>item-list</tag> tag. So we will create a table by iterating through the basket items. The text within the <tag>item-list</tag> <tag>/item-list</tag> tags is repeated for each item in the list.
@@ -697,41 +697,44 @@
<para>
The site can now be completed by adding the ability to check out with the shopping cart and finalize the order. To do this the customer needs to provide a shipping address (which, for the sake of this tutorial, we will assume is the same as the billing address), and payment information. We will process the order by verifying the customer's payment information and sending an e-mail to the merchant (ourselves) detailing the order.
</para> <para>
- We first need to create a checkout page. The checkout page consists of a form that receives order information from the customer and performs a simple credit card number check. In this tutorial we will use a built-in test that only checks to see if a given credit card number <emphasis>could</emphasis> be valid. If the information is acceptable the customer will move to the next phase of the order process. If it is not, an error page will be displayed.
+ We first need to create the checkout page. It will consist of a form whose verifying routine will receive order information from the customer and perform a simple credit card number check. In this tutorial we will use a built-in test that only checks to see if a given credit card number <emphasis>could</emphasis> be valid. If the information is acceptable the customer will move to the next phase of the order process. If it is not, an error page will be displayed.
</para> <para>
- To create the checkout page, type the following code and save it as <filename>pages/checkout.html</filename>. The section that follows explains the code.
+ To create the page, type the following code and save it as <filename>pages/checkout.html</filename>. The section that follows explains the code.
<programlisting>
-<xi:include parse='text' href='../files/tutorial-phase4/pages/checkout.html'></xi:include>
+<xi:include parse='text' href='../files/tutorial-phase4/pages/checkout.html'/>
</programlisting>
</para> <para>
- The HTML form begins with a method of 'post' (which sends the form data as its own stream, as opposed to the 'get' method which encodes the data as part of the URL). The <tag>process</tag> tag creates a special URL for form processing. Interchange has a built-in form processor that is configured by submitting certain fields in the form. The Finalize button will invoke this form processor and link the user to the <filename>special_pages/receipt.html</filename> page, which is described later.
+ The HTML form begins with a "POST" method which sends the form data in its own stream (as opposed to "GET", where the data is encoded in the URL). The <tag>process</tag> tag creates a special URL to process the form. Interchange has a built-in form processor that is configured by submitting certain fields in the form (along with the data, of course). The <guibutton>Finalize!</guibutton> button will invoke this form processor and take the user to the <filename>special_pages/receipt.html</filename> page, which is described later.
</para> <para>
- You are submitting some hidden form values that will tell Interchange how to process this form. The first value, mv_todo was set as submit. This causes the form to be submitted for validation. The second value, mv_order_profile was set as order_profile. This determines the validation process for the form. It is explained further in the next section.
+ You are submitting some hidden form values that will tell Interchange how to process this form. The first value, <mv>mv_todo</mv> was set as submit. This will plainly cause the form to be submitted. The second value, <mv>mv_order_profile</mv>, was set to a profile named <literal>order_profile</literal> (that selects the form validation process routine). It will be explained further in the next section.
</para> <para>
- The last value, mv_cyber_mode, was set to be minivend_test. The mv_cyber_mode value determines what method will be used to charge a credit card. The value of minivend_test uses the internal test method, which calculates a simple checksum against the card to determine if it is a valid number.
+ The last value, <mv>mv_cyber_mode</mv>, was set to be <literal>minivend_test</literal><footnote><para>Note that &IC; was originally named MiniVend, before it was joined with Akopia's Tallyman to form Interchange.</para></footnote>. The <mv>mv_cyber_mode</mv> value determines what method will be used to charge a credit card. The special <literal>minivend_test</literal> type uses the internal test method, which only calculates a simple checksum against the card number to determine if it is a valid.
</para> <para>
- When preparing an order for processing, Interchange looks for certain named fields in the form to obtain name, address, and credit card information. We are using all expected (default) field names in this form so that no translation needs to take place.
+ When preparing an order for processing, Interchange looks for certain fields in the form to obtain name, address, credit card and other information. We are using all the expected (default) field names in this form so no translation (mapping) will need to take place.
</para> <para>
- View the checkout page in your browser. The "Finalize!" link has not been enabled, but the page should display properly.
+ View the checkout page in your browser. The <guibutton>Finalize!</guibutton> link has not been enabled, but the page should display properly.
</para>
</sect2>
<sect2 id='etc_profiles_order'>
<title>etc/profiles.order</title>
<para>
- You need to set up verification for the order form by defining an order profile for the form. An order profile determines what fields are necessary for the form to be accepted. Create an order profile verification page by typing the following and saving it as <filename>etc/profiles.order</filename>. The section that follows explains the code used:
+ Just above, we said we used the <mv>mv_order_profile</mv> form variable to specify the form validation routine. Now what there's left to it is to actually create that profile.
+ </para>
+ <para>
+ An <firstterm>order profile</firstterm> determines things like fields (and types of their values) which are necessary for the form to be accepted. Create an order profile verification page by typing the following and saving it as <filename>etc/profiles.order</filename>. The section that follows explains the code used:
<programlisting>
-<xi:include parse='text' href='../files/tutorial-phase4/etc/profiles.order'></xi:include>
+<xi:include parse='text' href='../files/tutorial-phase4/etc/profiles.order'/>
</programlisting>
</para> <para>
- A single file can contain multiple profile definitions. First the profile is named using the <pragma>__NAME__</pragma> pragma (but this is unrelated to the <varname>__VARIABLE__</varname> syntax seen elsewhere in Interchange). Then in the profile there is a list of the form fields that are required. The &fatal setting indicates that validation will fail if any of the requirements are not met. &final indicates that this form will complete the ordering process. This setting is helpful if you have a multi-page ordering process and you want to validate each page individually. The <pragma>__END__</pragma> pragma signals the end of this profile, after which you can begin another one.
+ A single file can contain multiple profile definitions. First, the profile is named using the <literal>__NAME__</literal> token (but this is unrelated to the <varname>__VARIABLE__</varname> syntax seen elsewhere in Interchange). Then in the profile there is a list of the form fields that are required. The &fatal setting indicates that validation will fail if any of the requirements are not met. &final indicates that this form will complete the ordering process. This setting is helpful if you have a multi-page ordering process and you want to validate each page individually. The <literal>__END__</literal> token signals the end of this profile, after which you can begin another one.
</para> <para>
In order to activate your order profile, add the <option>OrderProfile</option> directive to the <filename>catalog.cfg</filename>:
<programlisting>
OrderProfile etc/profiles.order
</programlisting>
</para> <para>
- Watch for white space in front of the <pragma>__NAME__</pragma> pragma, it can cause your profile to be ignored. Remember to reconfigure the catalog or simply restart Interchange altogether after modifying <filename>catalog.cfg</filename> or the profiles.
+ Watch for white space in front of <literal>__NAME__</literal> as it can cause your profile to be ignored. Remember to reconfigure the catalog (or simply restart Interchange altogether) after modifying <filename>catalog.cfg</filename> or the profiles.
</para>
</sect2>
@@ -740,10 +743,10 @@
<para>
If the submitted form lacks a required field, Interchange will display an error page. The default location is <filename>special_pages/needfield.html</filename>. Here's the code for the page:
<programlisting>
-<xi:include parse='text' href='../files/tutorial-phase4/special_pages/needfield.html'></xi:include>
+<xi:include parse='text' href='../files/tutorial-phase4/special_pages/needfield.html'/>
</programlisting>
</para> <para>
- The <tag>error</tag> tag is the most important tag on this page. The 'all' parameter tells the tag to iterate through all of the errors reported from the failed verification, and the 'show_var' parameter indicates that the failed variable name should be displayed. For example, if the first name was left empty, 'fname' would be shown. The 'show_error' parameter displays the actual error for the variable. The joiner parameter inserts an HTML <br> tag between each error message, so each error is displayed on its own line. In more complex configurations, the <tag>error</tag> tag can be even more expressive.
+ The <tag>error</tag> tag is the most important tag on this page. The <literal>all</literal> parameter tells the tag to iterate through all of the errors reported from the failed verification, and the <literal>show_var</literal> parameter indicates that the failed variable name should be displayed. For example, if the first name was left empty, <mv>fname</mv> would be shown. The <literal>show_error</literal> parameter displays the actual error for the variable. The joiner parameter inserts an HTML <br> tag between each error message, so each error gets displayed on its own line. In more complex configurations, the <tag>error</tag> tag can be even more expressive.
</para>
</sect2>
@@ -759,9 +762,9 @@
</para> <para>
This issues two instructions to the credit card system.
</para> <para>
- The first option, standard, uses the standard built-in encryption algorithm to encrypt the credit card number and erases the unencrypted copy from memory. We are using the standard option not to encrypt the number but to run the checksum verification on the number to verify that it is a potentially correct number. We will not be checking with a real payment processor to see if it actually is a valid card number. For testing purposes, you can use the card number 4111 1111 1111 1111, which will pass the checksum test.
+ The first option, <literal>standard</literal>, uses the standard built-in encryption algorithm to encrypt the credit card number and erases the unencrypted copy from memory. We are using the standard option not to encrypt the number but to run the checksum verification on the number to verify that it is a potentially correct number. We will not be checking with a real payment processor to see if it actually is a valid card number. For testing purposes, you can use the card number <literal>4111 1111 1111 1111</literal>, which will pass the checksum test.
</para> <para>
- The second option, keep, keeps the credit card number from getting removed from memory. We want to keep the number in memory so that it is available when it is mailed as part of the order.
+ The second option, <literal>keep</literal>, keeps the credit card number from getting removed from memory. We want to keep the number in memory so that it is available when it is mailed as part of the order.
</para> <para>
If the credit card number passes and all of the required fields are present, the customer will be sent to the final page. Interchange then sends an e-mail to the store owner (you).
</para>
@@ -774,15 +777,15 @@
</para> <para>
The report should include at least the customer's name, address, and the items they ordered. The following is a simple report template; save it as <filename>etc/report</filename>:
<programlisting>
-<xi:include parse='text' href='../files/tutorial-phase4/etc/report'></xi:include>
+<xi:include parse='text' href='../files/tutorial-phase4/etc/report'/>
</programlisting>
</para> <para>
This file is in plain text format where, unlike HTML, white space is relevant. It is fairly straightforward, except that the <tag>if</tag> tag was added to only include the optional second address line if the customer filled it in.
</para> <para>
- One of the special properties of the mv_credit_card_number field is that Interchange specifically precludes the credit card number from being saved. This makes it unavailable to you in the <tag>value</tag> tag. The <tag>cgi</tag> tag is used to circumvent this important security measure in order to get the value submitted from the last form.
+ One of the special properties of the <mv>mv_credit_card_number</mv> field is that Interchange specifically precludes the credit card number from being saved. This makes it unavailable to you in the <tag>value</tag> tag. The <tag>cgi</tag> tag, which you can use to access the form variables only directly after form submission, is used to circumvent this important security measure and get the credit card number submitted.
</para>
<warning><para>
- Obviously it is a bad idea to send a real credit card number over an insecure channel like e-mail. In a real configuration, you would encrypt the number securely before e-mailing or storing it.
+ Obviously, it is a bad idea to send a real credit card number over an insecure channel like e-mail. In a real configuration, you would encrypt the number securely before e-mailing or storing it.
</para></warning>
</sect2>
@@ -791,12 +794,12 @@
<para>
Once the report has been run, Interchange will finish the order process on the customer side by displaying a success screen containing a receipt. The default location for this page is <filename>special_pages/receipt.html</filename>. To create a receipt page, type the following code and save it as <filename>special_pages/receipt.html</filename>.
<programlisting>
-<xi:include parse='text' href='../files/tutorial-phase4/special_pages/receipt.html'></xi:include>
+<xi:include parse='text' href='../files/tutorial-phase4/special_pages/receipt.html'/>
</programlisting>
</para> <para>
Once the order is processed, the customer's shopping cart is emptied.
</para> <para>
- At this point you have a more-or-less functional store. Congratulations once again ;)
+ At this point you have a more or less functional store. Congratulations once again ;)
</para>
</sect2>
@@ -831,7 +834,7 @@
<para>
You may have noticed that the product prices aren't formatted as prices usually are. The way to correct this is with an Interchange feature called <firstterm>price pictures</firstterm>.
</para> <para>
- There are several properties to price pictures: the currency symbol, the thousands separator, the decimal point, the number of digits to show behind the decimal, and so on. Most Unix systems have U.S. currency and the English language as the default locale, which is called en_US. The only thing you need to do on such a system is specify the currency symbol, which, in this case, is the dollar sign. To do this, add the following line to your <filename>catalog.cfg</filename> file:
+ There are several properties to price pictures: the currency symbol, the thousands separator, the decimal point, the number of digits to show behind the decimal, and so on. Most Unix systems have U.S. currency and the English language as the default locale, which is called <literal>en_US</literal>. The only thing you need to do on such a system is specify the currency symbol which, in this case, is the dollar sign. To do this, add the following line to your <filename>catalog.cfg</filename> file:
</para> <para>
<programlisting>
Locale en_US currency_symbol $
@@ -1008,7 +1011,7 @@
</para> <para>
In the first set of <select> </select> HTML tags a list is generated of the months to choose from. This is accomplished by using a <tag>loop</tag> tag. In this case we are looping over an explicit list. The list is provided in the list parameter. Use caution when typing this, as it is sensitive to formatting (which may not be reflected in this document). Make sure that the numbers are the first characters on each new line and that the single tab separates them from the rest of the line text. Since the columns in this list are not named, the first element can be accessed using <tag>loop-code</tag> or <code>[loop-pos 0]</code> with subsequent elements being accessed by <code>[loop-pos N]</code> where N is the number of the column you want. Notice that the elements are zero-indexed. Each time through this loop Interchange generates a select <option> with a number as the value and the name of the month as the text for the select menu.
</para> <para>
- For the next set of <select> </select> tags embedded Perl is used to generate the list which is iterated over. Perl code can be embedded in Interchange pages in order to extend the abilities of the system. Make sure you type back-ticks (grave accents) after "list=" and before the closing bracket (and <command>not apostrophes</command>). This code generates an entry for seven years in addition to the current year. It is not necessary at this point for you to understand this Perl code.
+ For the next set of <select> </select> tags embedded Perl is used to generate the list which is iterated over. Perl code can be embedded in Interchange pages in order to extend the abilities of the system. Make sure you type back-ticks (grave accents) after <literal>list=</literal> and before the closing bracket (and <command>not apostrophes</command>). This code generates an entry for seven years in addition to the current year. It is not necessary at this point for you to understand this Perl code.
</para>
</sect2>
@@ -1023,7 +1026,7 @@
"]
</programlisting>
</para> <para>
- You will recall that 'ra' stands for 'return all' and 'fi' stands for file. Let's add the search parameter 'tf', which specifies the sort field. You can specify the field either by name or by number (starting with 0), with names and order as given in the first line of <filename>products/products.txt</filename>). Make the following change in <filename>pages/index.html</filename>:
+ You will recall that <mv>ra</mv> stands for "return all" and <mv>fi</mv> stands for "file". Let's add the search parameter <mv>tf</mv>, which specifies the sort field. You can specify the field either by name or by number (starting with 0), with names and order as given in the first line of <filename>products/products.txt</filename>). Make the following change in <filename>pages/index.html</filename>:
<programlisting>
[loop search="
ra=yes
@@ -1042,7 +1045,7 @@
"]
</programlisting>
</para> <para>
- Refresh your browser. Now try reversing the sort order by adding 'r' to the 'to' setting:
+ Refresh your browser. Now try reversing the sort order by adding <literal>r</literal> to the <mv>to</mv> setting:
<programlisting>
[loop search="
ra=yes
@@ -1063,7 +1066,7 @@
"]
</programlisting>
</para> <para>
- Now let's try narrowing the search down a bit. Instead of returning all, we'll give 'se', the search parameter, and and use 'su', which allows substring matches. To search only for products that have the word "test" in one of their fields, and sort the results by description, type:
+ Now let's try narrowing the search down a bit. Instead of returning all, we'll give <mv>se</mv>, the search parameter, and use <mv>su</mv>, which allows substring matches. To search only for products that have the word "test" in one of their fields, and sort the results by description, type:
<programlisting>
[loop search="
se=test
@@ -1107,14 +1110,14 @@
<td align="center">
]]></programlisting>
</para> <para>
- This is a simple HTML form with a single input box for text. The action goes to a special Interchange processor called 'search' that will perform the search and pass the results to a page called <filename>pages/results.html</filename> (that has not been created yet). The search will be case-insensitive, but will only match complete words, not substrings.
+ This is a simple HTML form with a single input box for text. The action goes to a special Interchange processor called "search" that will perform the search and pass the results to a page called <filename>pages/results.html</filename> (that has not been created yet). The search will be case-insensitive, but will only match complete words, not substrings.
</para> <para>
- The <code>[set testname]...[/set]</code> tags set an Interchange scratch variable that will be (in this case, of course) used as a predefined search profile. We specify all the search parameters except the one the user will enter, 'mv_searchspec' (the long name for 'se'). We then tell Interchange we want to use this search profile in a hidden form variable named 'mv_profile'.
+ The <code>[set testname]...[/set]</code> tags set an Interchange scratch variable that will be (in this case, of course) used as a predefined search profile. We specify all the search parameters except the one the user will enter, <mv>mv_searchspec</mv> (the long name for <mv>se</mv>). We then tell Interchange we want to use this search profile in a hidden form variable named <mv>mv_profile</mv>.
</para> <para>
The search box will now appear on all catalog pages, but you still need to create the search results page. To create the search results page, type the following code and save it as <filename>pages/results.html</filename>.
</para> <para>
<programlisting>
-<xi:include parse='text' href='../files/tutorial-phase5/pages/results.html'></xi:include>
+<xi:include parse='text' href='../files/tutorial-phase5/pages/results.html'/>
</programlisting>
</para> <para>
The search results will be contained in the <tag>search-region</tag> <tag>/search-region</tag> tags. The text in the <tag>on-match</tag> <tag>/on-match</tag> container will be displayed only if matches were found for the search. The text in the <tag>no-match</tag> <tag>/no-match</tag> container will be displayed only if no matches were found. The <tag>search-list</tag> <tag>/search-list</tag> container functions just like <tag>loop</tag> <tag>/loop</tag>, iterating over its contents for each item in the search results list.
1.10 +23 -0 xmldocs/docbook/docbookxi.dtd
rev 1.10, prev_rev 1.9
Index: docbookxi.dtd
===================================================================
RCS file: /var/cvs/xmldocs/docbook/docbookxi.dtd,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- docbookxi.dtd 29 Aug 2004 20:55:36 -0000 1.9
+++ docbookxi.dtd 21 Sep 2004 09:28:28 -0000 1.10
@@ -143,3 +143,26 @@
>
<!--end of pragma.attlist-->]]>
<!--end of pragma.module-->]]>
+
+<!-- mv element -->
+<!ENTITY % mv.module "INCLUDE">
+<![%mv.module;[
+<!ENTITY % local.mv.attrib "">
+<!ENTITY % mv.role.attrib "%role.attrib;">
+
+<!ENTITY % mv.element "INCLUDE">
+<![%mv.element;[
+<!ELEMENT mv %ho; (%para.char.mix;|%para.mix;)*>
+<!--end of mv.element-->]]>
+
+<!ENTITY % mv.attlist "INCLUDE">
+<![%mv.attlist;[
+<!ATTLIST mv
+ %moreinfo.attrib;
+ %common.attrib;
+ %mv.role.attrib;
+ %local.mv.attrib;
+>
+<!--end of mv.attlist-->]]>
+<!--end of mv.module-->]]>
+
1.9 +1 -0 xmldocs/docbook/common.xsl
rev 1.9, prev_rev 1.8
Index: common.xsl
===================================================================
RCS file: /var/cvs/xmldocs/docbook/common.xsl,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- common.xsl 13 Aug 2004 21:09:15 -0000 1.8
+++ common.xsl 21 Sep 2004 09:28:28 -0000 1.9
@@ -24,6 +24,7 @@
<!--<xsl:template match="tag"><xsl:text>[</xsl:text><xsl:call-template name="inline.monoseq"/><xsl:text>]</xsl:text></xsl:template>-->
<xsl:template match="tag">[<xsl:call-template name="inline.monoseq"/>]</xsl:template>
<xsl:template match="pragma"><xsl:call-template name="inline.monoseq"/></xsl:template>
+ <xsl:template match="mv"><xsl:call-template name="inline.monoseq"/></xsl:template>
<xsl:param name="local.l10n.xml" select="document('')"/>
<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">
More information about the docs
mailing list