255 lines
9.6 KiB
Plaintext
255 lines
9.6 KiB
Plaintext
Content Rotator Component
|
|
=========================
|
|
|
|
|
|
Table of Contents
|
|
=================
|
|
|
|
Overview
|
|
Installation
|
|
File List
|
|
Sample ASP
|
|
Build Notes
|
|
Support
|
|
Data Format
|
|
Discussion of the Design
|
|
Change Notes
|
|
|
|
|
|
Overview
|
|
========
|
|
|
|
The Content Rotator Component is an Active Server Pages component that
|
|
yields random selections of HTML from a data file. It can be used for
|
|
such diverse applications as:
|
|
* a tip-of-the-day generator
|
|
* a random advertisement billboard
|
|
* a poor man's load-balancing scheme for selecting email names of
|
|
Tech Support people.
|
|
|
|
|
|
Installation
|
|
============
|
|
|
|
In order to use this component you must register it. This will allow Active
|
|
Server Pages (ASP) Scripting Languages and other languages to make use of
|
|
the component. ASP uses either the Server.CreateObject("ObjectName") syntax
|
|
or the <object id="myName" progid="ObjectName" runat="server"> syntax to
|
|
gain access to an object. New objects can be made ready for use by
|
|
installing a new component. Note: One component may contain more than one
|
|
object definition.
|
|
|
|
The following directions are to help you register the component for use:
|
|
1. Use the Start menu, Programs option to start a Command Prompt
|
|
2. Type the following:
|
|
cd \InetPub\ASPSamp\Components\ContRot\DLL\i386
|
|
3. Type:
|
|
regsvr32 ContRot.dll
|
|
Note: you must register the component on each IIS server where you intend
|
|
to use it.
|
|
|
|
If you have trouble registering components, you may be using the wrong
|
|
version of RegSvr32.exe. Please use the version installed by default in
|
|
the directory <InstallDir>\ASP\Cmpnts. On Windows NT, the default
|
|
installation directory is \winnt\System32\Inetsrv. On Windows 95, it is
|
|
\Program Files\WebSvr\System.
|
|
|
|
(If you rebuild the source code, the makefile will automatically reregister
|
|
the component for you.)
|
|
|
|
The following directions are to help you test the registered component:
|
|
1. Use the Windows Explorer to copy all of the Sample files except
|
|
global.asa from \InetPub\ASPSamp\Components\ContRot\Samples
|
|
to \InetPub\ASPSamp\Samples.
|
|
2. Copy global.asa to \InetPub\ASPSamp. (Note: global.asa *must* be in a
|
|
virtual root directory; the other files need not be.)
|
|
3. In your browser, open http://localhost/ASPSamp/Samples/ContRot.htm
|
|
You must copy the sample files to a virtual directory; if you attempt to
|
|
examine them with a browser in the ContRot\Samples directory, ASP will not
|
|
execute the script.
|
|
|
|
|
|
File List
|
|
=========
|
|
|
|
File Description
|
|
---- -----------
|
|
|
|
.\Source
|
|
|
|
RotObj.cpp the C++ source code for the content rotator component
|
|
RotObj.h declarations for CContentRotator
|
|
ContRot.idl declaration of IContentRotator, the IDispatch-based interface
|
|
Makefile a makefile that can be used with nmake
|
|
ContRot.mak the Developer Studio makefile
|
|
debug.cpp useful debugging stubs
|
|
debug.h useful debugging macros and declarations for debug.cpp
|
|
ContRot.cpp )
|
|
ContRot.def )
|
|
ContRot.mdp )
|
|
ContRot.rc )
|
|
ContRtPS.def } Generated by the ATL COM AppWizard
|
|
ContRtPS.mak )
|
|
Resource.h )
|
|
StdAfx.cpp )
|
|
StdAfx.h )
|
|
|
|
.\Samples
|
|
|
|
ContRot.htm Explains how to use the Content Rotator
|
|
global.asa session object setup
|
|
fortunes.asp session-level object demonstration; refreshes automatically
|
|
fortunes.txt sample Content Schedule File for fortunes.asp
|
|
ufortune.txt Unicode version of fortunes.txt
|
|
techsupp.asp page-level object ChooseContent demonstration
|
|
techsupp.txt another sample Content Schedule File
|
|
cr-proof.asp demonstration of GetAllContent for proof-reading
|
|
|
|
|
|
Samples
|
|
=======
|
|
|
|
You will need to copy the sample files to a virtual directory on an
|
|
IIS Server. Note that global.asa (and hence fortunes.asp and
|
|
techsupp.asp) will not work unless global.asa is in a virtual root.
|
|
|
|
There are two examples of using ChooseContent: one as a page-level
|
|
object (techsupp.asp) and one as a session-level object
|
|
(fortunes.asp). Note that if you repeatedly refresh techsupp.asp, the
|
|
distribution of content that you will see will almost certainly not
|
|
match the weights specified in techsupp.txt. If you look at
|
|
fortunes.asp, you will see that the distributions of fortunes is
|
|
correct. See the Discussion of the Design section below for why this
|
|
is so.
|
|
|
|
If a user is likely to visit a page with a content rotator only once,
|
|
then it doesn't really matter whether it's a session-level object or
|
|
not. If a user revisits a page several times within a few minutes,
|
|
which is quite likely if it's a key page they have to keep navigating
|
|
through, or if the same content rotator is used on multiple pages,
|
|
then it should be a session-level object.
|
|
|
|
Ufortune.txt is included only to demonstrate that the Content Rotator
|
|
really does work when it's built as a Unicode DLL and is of little
|
|
practical use. You can use NT's notepad.exe to write files in Unicode
|
|
format: check "Save as Unicode" on the Save As dialog box.
|
|
|
|
|
|
Build Notes
|
|
===========
|
|
|
|
This sample requires Microsoft Visual C++ 4.2b or newer. If you are using
|
|
VC 4.2, it is necessary that you upgrade to VC 4.2b, using the patch which
|
|
can be found at http://www.microsoft.com/visualc/patches/v4.2b/vc42b.htm
|
|
Note that this patch will not work with earlier or later versions of
|
|
Visual C++, only with VC 4.2.
|
|
|
|
This sample also requires ATL (Microsoft Active Template Library)
|
|
version 2.0 or newer. ATL 2.1 ships with Visual C++ 5.0. ATL 2.0 for
|
|
VC 4.2b can be downloaded from: http://www.microsoft.com/visualc/prodinfo/
|
|
You do not need the ATL Docs or Object Wizard Technology Preview to build
|
|
the registry access component, but you will probably find them useful.
|
|
|
|
If you get an error about "don't know how to make asptlb.h", you will
|
|
need to copy <InstallDir>\ASP\Cmpnts\AspTlb.h to your include
|
|
directory.
|
|
|
|
You can build this component with nmake at the command line. Read
|
|
Makefile for more details. You can also build it in Microsoft
|
|
Developer Studio, using the ContRot.mdp project.
|
|
|
|
The component can be built as ANSI or Unicode. If you intend to
|
|
run it on Windows 95, build it as ANSI. If you build it as a
|
|
Unicode DLL, all data files will need to be in Unicode format.
|
|
|
|
|
|
Support
|
|
=======
|
|
|
|
This component is not officially supported by Microsoft Corporation.
|
|
Peer support is available on the Active Server Pages mailing list or on
|
|
the microsoft.public.inetserver.iis.activeserverpages newsgroup.
|
|
|
|
To subscribe to the Active Server Pages mailing list, send mail to
|
|
listserv@listserv.msn.com with
|
|
|
|
subscribe Denali [firstname lastname]
|
|
|
|
in the body of the message, and then follow the directions carefully.
|
|
(firstname and lastname are optional.)
|
|
|
|
You can reach the newsgroup through msnews.microsoft.com and other NNTP
|
|
servers.
|
|
|
|
|
|
Data Format
|
|
===========
|
|
|
|
You can find examples of Content Schedule files in the Samples directory.
|
|
|
|
|
|
Discussion of the Design
|
|
========================
|
|
|
|
The Content Rotator is best used as a session-level object, rather
|
|
than a page-level object. It caches the contents of the data file,
|
|
which gives you two benefits at the cost of using some more memory:
|
|
it's faster on second and subsequent invocations and you get much
|
|
better random distribution of the data, as it takes some care to
|
|
ensure that each entry is served up no more than its fair share of
|
|
times.
|
|
|
|
When it's used as a page-level object, you do not benefit from its
|
|
caching of the data. More importantly, you are much more likely to
|
|
perceive a less random permutation of the data if you repeatedly
|
|
refresh the page. This is because there is no way to ensure a
|
|
properly random distribution of the data if the Content Rotator object
|
|
is created afresh each time the page is visited. See the Samples
|
|
directory for an example of how to use the Content Rotator as a
|
|
session-level object.
|
|
|
|
It is technically impossible to use the Content Rotator as an
|
|
application-level object (because application-level objects do not
|
|
receive the OnStartPage call which is needed to get a pointer to the
|
|
Server object so that its MapPath method can be called to translate
|
|
the virtual path of the data filename into a physical filesystem
|
|
path), or that would be the recommended way to use it. It would be
|
|
very easy for you to change the ChooseContent and GetAllContent
|
|
methods to work with a physical data path.
|
|
|
|
The Page Counter sample component demonstrates an alternative method
|
|
of caching data between invocations. The Page Counter DLL has a
|
|
global object (the Central Counter Manager) which tracks hits across
|
|
all pages and takes care of writing the data to persistent storage
|
|
periodically. When a Page Counter object is created, it modifies the
|
|
global CCM as necessary. Creating a global cache for the Content
|
|
Rotator would be more complicated because it would have to cache
|
|
multiple data files simultaneously.
|
|
|
|
Note that if you create a single content rotator object and you have
|
|
it use several data files on different pages, then the benefits of
|
|
caching the data are nullified. Far better to create one object for
|
|
each datafile, especially if the datafile is used in more than one
|
|
place.
|
|
|
|
The discussion of critical sections in RotObj.cpp may also be of
|
|
interest.
|
|
|
|
|
|
Change Notes
|
|
============
|
|
|
|
Beta 1: February 1997
|
|
---------------------
|
|
|
|
First release.
|
|
|
|
|
|
Beta 2: March 1997
|
|
------------------
|
|
|
|
* Fixed Developer Studio makefile problems in C++ components.
|
|
* Upgraded to build cleanly with ATL 2.0 (Visual C++ 4.2b) and ATL 2.0 (VC5).
|
|
* Type Library name changes
|
|
* Check for new returning NULL a la ATL itself
|