Test Page for the "DOWNLOAD" macro

The page demonstrates (and documents) how the "dlcntr.ih" header file can be used. This header file allows you to easily create informative download links on your site and utilise free download counters from http://www.downloadcounter.com/ (see the "DLCNTR.IH" Q & A page). You do not need to do anything special for new downloads, this header will automatically create new counters online as required, for this reason do not do the "spidering" that the site might suggest! You will be told if a download does not exist. The only manual component is a once off online registration to obtain a user id (and configuration involving all of your counters). The use of download counters is optional, they can be turned off globally or selectively.

The header allows for a lot of flexibility in how things are formatted, in the order they are displayed and how they are positioned. This hopefully covers most requirements. I recommend that you not change the header files allowing you to easily use any newer versions that might appear (due to bug fixes or enhancements). If you can't make the change without hacking the header let me know and I'll update the header so you can.

If you don't get tooltips you are using an older browser that does not support "TITLE" on the "A" tag (or Netscape before version 6). Most people should see these tips. The tooltip will contain whatever you wish but by default it contains the date, time, and size of the download plus more. If you wish you can also display this as text (in or out of the hypertext link) as demonstrated in one of the tests below.


Note that downloads will of course not actually work as some details were not "correctly" specified for the purposes of this sample (No clicking!). Also note, for the purposes of this sample I have defined a new file as being less than "9,999" days old! This ensures that if you take the code and build it (at any future time) you will get the new tags displayed.

Some tests (most settings can be seen in the tooltip):

  1. dlc_samp.it This download is not more than 9999 days old (1508 days old at 13 Jun 2005)
    All defaults... By defaults I mean that no parameters were passed to override globally set defaults.

    The download macro would normally be called like this with minimal parameters as the parameters either specify values (such as download name) or override global settings you have set or allowed to default (and which would typically apply to all downloads). Following tests do overrode some global defaults.

  2. dlc_new.gif This download is not more than 9999 days old (1588 days old at 13 Jun 2005)
    The time does not contain the seconds.

  3. dlcntr.ih This download is not more than 9999 days old (0 days old at 13 Jun 2005)
    No seconds and set 24 hour clock.

  4. [poor man's image] This download is not more than 9999 days old (1508 days old at 13 Jun 2005)
    A name/description was set for this counter. Note that any valid html can be used for the link including one or more images.

  5. dlcntr.ih (29,527 bytes Mon Jun 13 2005 1:17:07pm) This download is not more than 9999 days old (0 days old at 13 Jun 2005)
    File size, date, time etc within link, any "new" tags outside.

  6. dlcntr.ih This download is not more than 9999 days old (0 days old at 13 Jun 2005)
    No tooltip.

  7. dlcntr.ih This download is not more than 9999 days old (0 days old at 13 Jun 2005)
    Simple tooltip with just the download size. It is possible to obtain information about the last download processed (for example this download was 29,527 bytes long and dated Mon Jun 13 2005 at 1:17:07pm). This gives you more control over how you format your download links.

  8. dlc_samp.it This download is not more than 9999 days old (1508 days old at 13 Jun 2005)
    All defaults except that it does not use a download counter for this download (it's a direct link).

Some of this pages SOURCE CODE

I have included SOME of this pages source code ("dlc_samp.it") below so you can get an idea of what your source might look like.

The setup of the counter support with it's default options:

    ;--- Set up defaults and load download counter support ----------------------
    #define  DLCNTR_WEB_PATH           http://www.labyrinth.net.au/~dbareis/MyDownloads/
    #define  DLCNTR_DEFAULT_USER_NAME  AsSpecifiedDuringRegistration
    #define  DLCNTR_AGE_NEW_DAYS       9999    ;;Stupid but ensures YOU will get "new" icon now matter when you build this!
    #define  DLCNTR_AGE_NEW_IMGTAG     <?space><img src="dlc_new.gif"         \
                                                border="0"                    \
                                                width="23" height="14"        \
                                                ALT="<$NEW_IMAGE_TOOLTIP>"    \
                                                TITLE="<$NEW_IMAGE_TOOLTIP>">
    #include "dlcntr.ih"
    
    
    ;--- Some more (commented out) possibilities (put before #include above!) ---
    ;#define  DLCNTR_COUNTER_MEMPATH   out\DLGROUP     ;;Directory where information about a counter can be stored (allows reporting)
    ;#define  DLCNTR_DONT_USE_DOWNLOAD_COUNTER         ;;If you don't wish to use download counters (just the rest)
    ;#define  DLCNTR_AGE_NEW_IMGTAG     <?space>[new]  ;;If this is not defined then no files are marked as new!
    ;#define  DLCNTR_AGE_NEW_DAYS       14             ;;define "new" as 2 weeks
    ;#define  DLCNTR_FIND_PATH         .;c:\tmp;c:\downloads;
    ;#define  DLCNTR_AFTER_LINK \
    ;         <?Space><font size="-1">({SIZE} {DATE} {TIME}{NEW})</font>
    ;#define  DLCNTR_TOOLTIP                         ;;No tooltip
    ;#define  DLCNTR_TOOLTIP                         ;;Pass empty for none!  \
    ;         Length {SIZE}.                                                 \
    ;         ({TTNAME})
    ;#define  DLCNTR_CANT_ACCESS_COUNTER_SITE_COUNTER_VALUE "?unknown?"
    
    
    ;--- Define the tooltip for the NEW IMAGE (note "ALT" incorrectly used, should be "", to support older browsers) ---
    #define  NEW_IMAGE_TOOLTIP         This download is not more than <$DLCNTR_AGE_NEW_DAYS> days old ({AGE} days old at {CDATE})

Using the "Download" macro (this will match exactly with the html code above):

    <p><li><$download FILE="dlc_samp.it">
    <BR>
    All defaults...
    By defaults I mean that no parameters were passed to override globally
    set defaults.
    
    <p>The download macro would normally be called like this with minimal
    parameters as the parameters either specify values (such as download name)
    or override global settings you have set or allowed to default (and which
    would typically apply to all downloads).
    Following tests do overrode some global defaults.
    
    
    ;--- TEST -------------------------------------------------------------------
    <p><li><$download FILE="dlc_new.gif" SS="N">
    <BR>
    The time does not contain the seconds.

As you can see there is very little setup involved, in most sites a common setup defined once will do the trick and no overriding of parameters (why present downloads in multiple ways?).

Some DOCUMENTATION

After numerous emails Jonathan Worthington and I have produced a system which makes his download counters much easier to use for anyone who hand codes their html (ie no manual setup and cut/paste of generated html). Following simple rules you can now automatically create counters or counter groups.

PPWIZARD or the "DLCCNTR.IH" header are not required for this, but it does make it easier not only to manage the download counter but to manage the download links and any associated information you wish to display. If you haven't already done so hover (place your mouse) over all of the links above as well as one of the "new" icons. You should notice that a lot of information can be displayed in tooltips (unless you have an older browser!) and that new icons are automatically added as required. You may wish to have a look at the "DLCNTR.IH" Q & A page that I have created.

The Download Macro

The simplest way to use the download macro is as follows:

<p>Please download <$download FILE="dlcntr.zip">.

While there are many options most will never be required by you unless you vary the way the downloads look within a single html page, an exception to this is the capability of "grouping" counters. By default a counter name is automatically created from the name of the download (without path), in the example above "dlcntr.zip" will be the counter name and this will be what is displayed on any download counter reports. You can set a value yourself (all downloads with the same name will update the same counter).

<p>Please download the
<$download FILE="dlcntr_os2.zip" NAME="Download Counter Header" VISIBLE="os2">.
or
<$download FILE="dlcntr_w32.zip" NAME="Download Counter Header" VISIBLE="windows">.
versions of the download counter header.

The above used the "NAME" attribute to specify a group, both downloads will update the same counter. I also used the "VISIBLE" attribute to specify what is displayed in the link (by default the download name without path), this could be any html or image.

Preparation for using the Download Macro

You will typically want downloads to look the same within a single page (or more likely within any page of your site). To make use of the download macro you must include the supporting header file, to do this you would #include the header somewhere before the first use of the macro (typically near the top of the code) as follows:

#include "dlcntr.ih"

Note that if you are already using ppwizard you have probably already created a common header file of your own in which case you would simply add the command to your common header. This is the recommended approach as then you will have one only place to make future changes no matter how large your site becomes. If some options need to vary on some pages the bulk can go into the common headers and the overrides where required. In this case, rather than directly using "#define?" yourself it would probably be better to make it more "generic" by defining "styles" of downloads/counters and then conditionally generating correct code (#if etc) based on this in your header since again this allows these changes to be centralised in one location.

Now the header file is very configurable, if included as above you are allowing all options to default (can be overriden on each use of the "Download" macro but it is better to set it up correctly in the first place).

If you look in the header file you will notice many lines near the top which begin with "#define?", these are conditional define commands (the value is only set if none already exists). For example the header includes the line:

#define? DLCNTR_AGE_NEW_DAYS  62  ;;If less than 2 months old a file is new

If you wish a file to be marked as "new" then you might wish "new" to mean less than 2 weeks old in which case you could load the header file like:

#define? DLCNTR_AGE_NEW_DAYS  14  ;;Override the default value
#include "dlcntr.ih"

So basically you define all options before loading the header. In the above example files will not be marked as new as you have not indicated how this should be done, you also need to define "DLCNTR_AGE_NEW_IMGTAG" to contain whatever HTML you wish (usually an "IMG" tag). This sample's source code (dlc_samp.it) demonstrates this well.

There is one "complication" which you must understand. The header needs to know 2 things to be able to do all this magic:

  1. Where the download file exists on the local filesystem (relative to the current directory). The "DLCNTR_FIND_PATH" definition controls this. You can specify multiple search locations, the default is just to look in the current directory. The PPWIZARD "FindFileInPath()" routine is used for the search so you can look at the doco for this to find out how to specify search paths.

    If a match can not be found using the exact "FILE" name passed on the "Download" macro then the search is repeated looking for the file without any path component attached.

  2. Where the download file exists relative to the html page being viewed in the browser. The "DLCNTR_WEB_PATH" definition controls this. By default it is assumed that the downloads are in the same directory as the generated html (not typical in larger sites).

    The value would normally have a terminating slash as the exact "FILE" name passed on the "Download" macro is appended to this!

User Variables (used in some text options)

Some of the text options you can set can contain markers of the form "{VariableName}", in which case all valid "VariableName" text will be replaced with the values they represent this are:

Note that "{Size}" and "{SIZE}" are equally valid as the case of a variable name is ignored.

More details can be obtained by further examination of the header file if you have any issues or would like more configurable options, let me (Dennis Bareis) know!


Where can PPWIZARD & It's Headers be found?

In case you got here via a search engine or a link from another site you can download the header file used in this sample page ("DLCNTR.IH") and ppwizard itself (my free html preprocessor) from the ppwizard download page at:

PPWIZARD can be thought of as a "Super SSI", it can include external files and do most of the things that server side includes can (and heaps more) but do them in a simpler manner and have no impact or requirements on the server.

PPWIZARD is the most powerful mechanism available for code reuse and automation of common tasks. See the PPWIZARD pages for more details.


Monday June 13 2005 at 1:23pm
(This is the generated output from sample PPWIZARD based source code making use of the "DLCNTR.IH" header file)