|
CSV2file Copyright 2003 - 2005, Stuart Udall
version 2.01: October 2, 2005
|
CSV2file generates a series of files from a template, an INI file, and a Comma-Separated-Value (CSV) file. One file per row in the CSV file is generated. The template determines what each file contains. The CSV data is inserted in each file at the points specified by the template. The software can generate text files of any format, including HTML, XML, Javascript, and PHP - it simply parses whatever is in the template. CSV2file can also substitute values in the template for static strings. CSV2file can also generate an index, which hyperlinks to each of the pages it generates. The index is fully customisable. CSV2file can upload all the files it generates to an FTP server. CSV2file detects whether an item in the previous index has been dropped from the current index. If so, it will remove the file from the FTP server. CSV2file generates a logfile, so its activity can be examined later.
[1] Note: The datadesc line is essentially a list of the titles or labels of each column in the CSV. These names must match the variables you use in the template. Example: Your CSV, a product database, has rows and columns of data in it. Each row contains the data for each product, while each column contains a different type of data. Say the first column is the product code, the second is the product description, and the third is the price of the product. You arbitrarily label these prodcode, proddesc, and prodval, and construct your template so it says something like: product description: $$proddesc Now, as you've used $$proddesc in the template, the generator needs to know which column of CSV data this corresponds to. You tell it which columns are what by using the datadesc line, which is a comma-delimited string which lists the column titles/variable names, as you used them in the template, and also, in the order they are listed in the CSV. As you used them in the template means that the variablenames must be spelled identically. The program looks for an exact match between the variablenames used in the template, and the variablenames listed in the datadesc line. In the order they are listed in the CSV means that the variablenames listed on the datadesc line must occur in the same sequence as the CSV columns they refer to. For example, if the first column of your CSV contained the data item product code, the second column, product description, and the third, product price, you might use a datadesc line like this: datadesc=prodcode,proddesc,prodval Correct coding of the datadesc line is crucial to correct operation of the program. Note: do not use leading $$ signs on the datadesc line. Although the datadesc line does contain variablenames, the only location these variablenames are prefixed with $$ is in the template. [2] Note: The indexby line selects which column of CSV data is used as the link text in the index. The link text is what is displayed in the index for the user to click on. If indexby is left blank, indexing is turned off. [3] Note: The linkleadHTML line defines any HTML to be inserted immediately before the filename in the link to each page on the index. To understand this more clearly, consider a sample link in the index: <a href=filename.htm>link text</a> If you set linkleadHTML to ABCDEF, you'll see this in the index: <a href=ABCDEFfilename.htm>link text</a> Similarly, if you set linktrailHTML to XYZ, you'll see this in the index: <a href=filename.htmXYZ>link text</a> These settings are both optional; to disable, simply leave them blank. They are primarily useful when inserting Javascript into the anchor tag. [4] Note: The togglefield is a field in the CSV data which contains a binary string, example: 01010101010. These strings can be used to compactly represent YES or NO variables in a CSV. CSV2file supports a single togglefield, currently 32 toggles wide. CSV2file is told which column in the CSV is the togglefield with the togglecolumn setting (give the name of the column - CSV columnnames are defined by the datadesc= line in the INI file). Each individual toggle in the togglefield (either a 1 or a 0) is given a name using the toggletitles setting. If there is no togglefield, simply leave the togglecolumn setting blank. Note: toggletitles are read left-to-right, eg, a togglefield of 1,0,0 with toggletitles defined as A,B,C would have values assigned as A=1, B=0, C=0. The toggletitles setting is defined in a similar manner to datadesc. For example, if your togglefield was 0101, with the first column denoting colour screen, the second denoting inbuilt LAN, the third, onboard sound, and the fourth, Firewire capability, then your toggletitles line might be defined like this: toggletitles=colour,LAN,sound,firewire This done, these names can be then referred to as if they were names for other columns of CSV data. That is, to use the individual toggles in the template, simply use their columnnames (defined by toggletitles) as $$variables. When CSV2file detects a togglefield being used, it does NOT simply replace the variablename with the value of the toggle (which is either a 1 or a 0). Rather, it tests the value of the toggle, and substitutes prespecified text depending on whether the value is a 1 or a 0. If no substitution text is supplied, the toggle is ignored entirely. Substitution is detailed below. [5] Note: Up to 200 substitute commands may be supplied in a single module. These commands essentially replace a variable in the template with data supplied in the INI file, instead of the CSV. The first parameter on the substitute= line is the name of the variable to replace. This variable must be listed in either datadesc or toggletitles (ie. the data to replace must be in the CSV). The second parameter is the text to replace the variable with. If the variablename is found in toggletitles, the second parameter is only inserted if the value of the variable (as defined by the togglefield coming out of the CSV for this particular row of CSV data) is 1. Otherwise, the third parameter is inserted instead (ie. when the value of the toggle in the CSV is 0). If the variable is not a toggle (ie. it was not found in toggletitles), the third parameter, if supplied, is ignored. [6] Note: The nameby line selects which column of CSV data is used as the filename for each file generated. If nameby is left blank, a randomly-generated filename is used. [7] Note: The indexwith line denotes which togglecolumns, if any, are indexed alongside each index entry. This feature is used to create an index comprised of a table of the CSV data. For example, if the source CSV contains a product name and a togglefield, the product name can be used as the index entry (defined with indexby); next to each name can be the fields you specify in indexwith. If the value of the specified togglecolumn(s) is false, the text supplied in the indexfalse line is inserted into the index. If the value is true, the text supplied in the indextrue is inserted instead. The togglefields are output in the order specified by the indexwith setting. The indexcellfalse and indexcelltrue settings can HTML to be inserted into the <TD> tag of the cell holding the above text. This feature is to allow the above text to be aligned and styled. [8] Note: The ftpdummyfile line specifies a file to download and discard. This is required in order to remove orphaned files from the FTP server. The file is not itself deleted; the FTP module does not permit a delete operation without a filename also being supplied, however. The file is simply downloaded and ignored. As a download can take time, select a file which is small - perhaps robots.txt, which should be in the root of your webspace..? This is indeed a "kludge".. unfortunate, but necessary! [9] Note: The ftpindexname line specifies a file to hold the generated index on the FTP server. When a set of pages is generated, the index is named "index.htm" on the local system. However uploading this file to a webserver may overwrite some other index file. Therefore, this setting allows the name of the file on the server to be specified. If this setting is left blank, no index is uploaded at all. [10] Note: The indexleadHTML line defines any HTML to be inserted immediately before the table cell containing each index item. To understand this more clearly, consider a sample table cell in the index: <td>cell data</td> If you set indexleadHTML to ABCDEF, you'll see this in the index: ABCDEF<td>cell data</td> Similarly, if you set indextrailHTML to XYZ, you'll see this in the index: <td>cell data</td>XYZ These settings are both optional; to disable, simply leave them blank. They are primarily useful when inserting Javascript into the table. [11] Note: The linkcellHTML line denotes defines any HTML to be inserted inside the <TD> tag of the each cell in the index containing a link to the indexed subpages. To understand this more clearly, consider a sample table cell in the index: <td>cell data</td> If you set linkcellHTML to class=linkcell, you'll see this in the index: <td class=linkcell>cell data</td> This setting is optional; to disable, simply leave it blank. It is primarily useful when inserting CSS into the table. Note: You may use semicolons to add comments (which are not interpreted) to the main section of the INI file (which is at the very top of the file, before any [modules]). Simply insert a semicolon and everything on that line after the semicolon will be ignored. Example: ; this is a comment. However you may NOT use comments in any [module] (where each module is defined). This is because semicolons may be used in the INI data itself (for example, if Javascript is used).
|