HoloStore - Instant Stores - NEW

Overview

• Automatically Go Secure
  If the purchaser is using Netscape and you have secure service (SSL), HoloStore will automatically go secure. It is not necessary to use SSL, however your customers may feel more secure about sending their credit card information if you have it. If you do not have your own key, you may still take advantage of secure service by using the HoloNet secure key for no extra charge using the 'holossl' option (for technical reasons this reqiures that your store run under "www.holonet.net" domain while in secure mode).

• Charge Their Credit Card
  If you have a Credit Card Network or Anacom account, their card can be immediately charged before proceeding.

• Allow Access To Password Protected Area
  You can automatically allow access to a password protected area. The purchaser selects a login name and password to access the area. When allowing access, you can specify what length of time they should be allowed access.

  Note: This feature is only available to customers on our Apache servers. Contact us to move your site or confirm that your site is on an Apache server. If you are on a CERN server and are looking for documentation on the CERN password protection scheme, please click here.

• Send E-mail
  You can have e-mail detailing each purchase automatically sent to the addresses of your choice.

Mock Instant Stores example:

• The Rocket Shop

LIVE Instant Stores :

Rates

Consultants for Instant Stores

Creating An Instant Stores Page

• HoloStore will search your file until it spots a HoloStore command.

• HoloStore will perform the command, replacing your command with appropriate HTML.

• HoloStore will continue searching for futher commands.

Similiarly, to see your source page, you need to FTP your source file to your computers. In particular, the view source option of your Web browser will not be able to display your source page, only the resulting HTML.

Command Syntax

{command arg1 arg2 arg3}

If you wish to use a "{" in your HTML page, you must place a "\" before the "{" to tell HoloStore to skip the "{".

If you need to place a space in an argument, you must place a "\" before the space:

{command arg1a\ arg1b arg2}

{command "arg1a arg1b" arg2a" "arg2b arg3}

If you need to place a quote in an argument, you must place a "\" before the quote.

A Basic HoloStore Command

{holostore ... }

For example:

{holostore -i shoes ... }
{holostore -i carrots ... }

The first time you mention an ID, you must specify a simple description and price for the item:

{holostore -i shoes -d "Garden Clogs From Germany" -p 29.95 ... }

Finally, you must specify at least one of the following three behavoirs: charge the card, allow access to a protected area, and/or send e-mail.

To send e-mail we specify a comma seperated list of e-mail addresses:

{holostore -i shoes -d "Garden Clogs From Germany" -p 29.95
-e ,}

Note that there should be no spaces between comma seperated email addresses, because that would make them different arguments!

The default behavior of the holostore command is to create a purchase button:

Changing The Button Name

{holostore -i shoes -d "Garden Clogs From Germany" -p 29.95
-e , -b "Buy Me"}

Verbose Purchase Form

{holostore -i shoes -d "Garden Clogs From Germany" -p 29.95
-e , -s verbose}

Generating A Link

<A HREF="{holostore -i shoes -d "Garden Clogs From Germany" -p 29.95
-e , -s url}">Buy Some Clogs</A>

Charging Credit Cards

{holostore -i shoes -d "Garden Clogs From Germany" -p 29.95
-anacom merchant password}

To charge the transaction via Credit Card Network, you must specify your Merchant id and password with the "-ccn" option:

{holostore -i shoes -d "Garden Clogs From Germany" -p 29.95
-ccn merchant password}

Additional Fields

Both options will add an additional input field to the bottom of the credit card form that will be presented to the user. For example:

{holostore -i shoes -d "Garden Clogs From Germany" -p 29.95
-e
-f E-mail}

To require that the field be filled out, use the '-F' option instead. However, even with the '-F' option, no checking is done on the field, so the user may enter any value they wish and it will be accepted without further prompting as long as they don't leave it blank.

You may add multiple -f or -F fields if you wish For example, '-F email -f Age -f Weight' would prompt the user for their email address, age, and weight. Because of the -F option, the email address would be required.

• Your site must be on an Apache Web server.
  Contact HoloNet to verify your site is on an Apache Web server, or to have your site moved to an Apache Web server.

  The Apache Web server uses a different password protection scheme from the HoloNet standard CERN Web server. Eventually, all accounts will be moved from the CERN Web server to the Apache Web Server.

• Create a directory to protect.
  This directory must be under a directory called "protect" in your site's http or https directory.

• Create a blank password file.
  This file should be inaccessible to Web browsers. We suggest you place in a directory called "passwords" under your site's "control" directory.

  The full path of your password file will be similar to:

  /www/sites/sitename/control/passwords/file

• Create a www_htaccess file
  This file specifies which users can access your protected folder. Place this file in the folder you wish to protect.

  ---

  AuthType Basic
  AuthName Pictures From Germany
  AuthDBUserFile /www/sites/rocketshop/control/passwords/germany
  AuthDBGroupFile /www/sites/rocketshop/control/passwords/germany
  <Limit GET>
  require valid-user|group groupName[ groupName]*
  </Limit>
  

  ---

  • AuthType Basic specifies that the standard type of password checking should be done.

  • AuthName DESCRIPTION specifies the name of password protected area. The description is shown to the user when a password is requested from the user. You should change this as appropriate.

  • AuthDBUserFile PASSWORD_FILE specifies the location of your password file. You should modify this as apporpriate.

  • AuthDBGroupFile PASSWORD_FILE Not necessary unless you are using groups. If you are using groups, PASSWORD_FILE should be the same as used in the AuthDBUserFile. See the -g option for details on groups.

  • AuthDBGroupFile PASSWORD_FILE specifies the location of your password file. You should modify this as apporpriate.

  • require valid-user|group[ group]* specifies which users or groups are allowed access to this file. If you are not using groups, the line should be 'require valid-user'. If you are using groups, you should the line 'require group' with all groups to be allowed following on the same line seperated by spaces. For example 'require group bronze silver gold'. See the -g option for details on groups.

• Specify password protection.
  Use the -a option to specifiy the location of the password file, minutes of access allowed, and the URL of password protected area:

  {holostore -i pictures -d "Pictures From Germany" -p 29.95
  -a /control/passwords/germany 60 http://www.custom.com/protect/pictures/}

  Note that you can use 'h', 'd', and 'w' at the end of this option as short hand for hours, days and weeks respectively. For instance '100' alone would allow access for 100 minutes, while '100d' would allow access for 100 days.

• Specify groups (OPTIONAL)
  Use the -g option to specifiy groups that the purchaser will become members of.

  This option can be used to specify a level of access. For example, suppose your store sold panoramic pictures from Germany, with two pricing options: Silver and Gold. Silver is less expensive, but Gold gets access to additional pictures as well as the pictures that Silver users have.

  On your store page, you would have have at least two holostore commands, one with the option '-g silver', one with the option '-g gold':

  {holostore -i silverPics
  -d "Pictures From Germany: Silver Access"
  -p 29.95
  -a /control/passwords/germany 60 http://www.custom.com/protect/silver/
  -g silver}

  {holostore -i goldPics
  -d "Pictures From Germany: Gold Access"
  -p 59.95
  -a /control/passwords/germany 60 http://www.custom.com/protect/gold/
  -g gold}

  In your protect directory you would have two directories, the silver directory and the gold directory. Both directories would have their own www_htaccess file.

  However, the silver www_htaccess would have the lines:

  require group silver gold
  

  The gold www_htaccess would have the line:

  require group gold

  All the other lines in the two files would be identical. This would allow silver or gold users to have access to files in the silver directory, while gold users would have access to the files in the gold directory as well.

  If you also wanted to sell upgrade packages from silver to gold, you could have another holostore command with the option '-g gold silver'. This would require that users purchasing this item must already be a member of the group silver, and would give them access to the gold group when purchased.

  {holostore -i goldUpgrade
  -d "Pictures From Germany: Upgrade to Gold Access"
  -p 30.00
  -a /control/passwords/germany 60 http://www.custom.com/protect/gold/
  -g gold silver}

  Presumably it would be priced as the difference between buying Gold access and buying Silver access.

Template Pages

{holostore -i pictures -d "Pictures From Germany" -p 29.95
-a /control/passwords/germany 60 http://www.custom.com/protect/pictures/
-t template.holostore}

{holostore -t}

<HTML>
<HEAD>
<TITLE>Page Title For Browsers To Display</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<H2>Sample Template Header</H2>

The purchase forms will appear below this line.
<P>

{holostore -t}

The purchase forms will appear above this line.
<P>

<HR><A HREF="mailto:></A>
</BODY>
</HTML>

Persistent Options

If '-persistent' is specified, no button or URL is output for that command. However, any option specified in the command is inherited by any holostore commands that follows it.

For example, suppose you wanted all your buttons to say 'Buy Me' instead of the default 'Purchase'. You could do this by adding the option '-b "Buy Me"' to all of your holostore commands, but this would be tedious.

With the persistent option, you could specify the following:

{holostore -persistent -b "Buy Me"}

All holostore commands that followed this command in your file would inherit the button name "Buy Me".

You can place as many flags as you wish with the '-persistent' option. For example, the following command would allow the button name, style, and price to be inherited:

{holostore -persistent -b "Buy Me" -s verbose -p 9.95}

Persistent commands have the following qualities:

• They do not create a purchase button. They simply set defaults for holostore commands that follow it in the file.
• Individual holostore commands can override the defaults set by the persistent option by explicity including the option.
• The last persistent command overides all previous persistent commands, but only for the options expicitly mentioned in the last command. So for the the following commands:

  {holostore -persistent -b "Buy Me" -p 9.95}

  {holostore -persistent -p 20.00}

Any command between these two commands would inherit the button name "Buy Me" and the price 9.95.

Any commands after the second command would inherit the price 20.00, and also the button name "Buy Me".

Debugging

Any invalid entries in this table also include an error row which will tell you what is wrong with the entry. For example, the following incomplete holostore command produces the following output:

{holostore -a bad_file}

Each field that has an error is easily spotted. Notice that some options are required, like the price option. Other fields may have other problems. In the above example, the file 'bad_file' does not exist, and so must be remedied by creating the file.

NOTE: If you are using the '-s url' option, and have imbeded the holostore command in a HREF command, if the command needs to display errors in a table they will not look correct. This is because placing a table in a HREF is not supported HTML. However, while this is not aethetically appealing, you should still be able to determine the error and correct the problem.

If you prefer you can temporarily move the holostore command out of the HREF until you have fixed the problem.

Reference

{holostore -i item_id [-s[tyle] [button|url|verbose|debug]] [-b text]
	[-d item_description -p item_price]
	[-[eE] e-mail[,email]*]
	[-(ccn|anacom) merchant_id merchant password [subaccount]]
	[-a password_file minutes url]
	[-persistent]
	[-[fF] field]
	[-[cC] field text]
	[-t template]
	[-lt file]
	[-T title]
	[-nocard]
	[-nocnp]
	[-holossl]
	[-r] [file]
	[-regnum] file
	[-remoteNotify remoteURL errorURL errorEmail]
	[-l[ogin]]
}

• -i item_id
  REQUIRED
  Each command on a page must have a unique name, or ID. The first use of an ID defines the item. Any following items with the same ID will have the same options, with the exception of style.

• -s button|url|verbose|debug
  
  • button
    This is the default behavior and will be used if no style is specified. A form is created with a button named purchased. The -b option can be used to rename the button.

  • url
    Creates the approrpriate URL to bring up a purchase form.

  • verbose
    Creates a small HTML form displaying the item description, price, and a purchase button. The -b option can be used to rename the button.

  • debug
    Displays information which may be helpful in diagnosing problems.

• -d description
  REQUIRED
  This option is used to specify the description of the item to be used in purchase forms. This item must be set the first time an item is used.

• -p price
  REQUIRED
  This option is used to specify the cost of the item in US dollars. This item must be set the first time an item is used.

• -b button
  This changes the text of the button that appears in the button or verbose style. It also changes the text of any subsequent 'Purchase' buttons that are displayed after clicking on the item. The default value is 'Purchase'.

• -(ccn|anacom) merchant_id mechant_password [subaccount]
  This option is used to charge buyer's credit card via an Internet Credit Card Processor.

  The following Credit Card Processors are currently supported:

  • Anacom Mechant Services (-anacom)
  • Credit Card Network (-ccn)

  Use the flag which corresponds to the service you wish to use.

  NOTE: You must have an account with the service that you wish to use.

• -[eE] mailbox[,mailbox]*
  This option sends email to the specified addresses detailing the transaction when an item is purchased. Multiple comma separated email addresses can be specified. Note that there should be no spaces between the comma seperated addresses. If a capital E is used for the flag, then the customer's credit card number will not be included in the email. You may wish to use this option for security reasons.

• -a password_file minutes url
  This option specifies a password file be used to limit access to a particular URL.

• -g group[,group]* [required_groups[,required_groups]*]
  This option allows you to specify one or more groups that the user will become a member of if they purchase the item. The required groups field allows will insist that the user already be a member of all of the required groups listed before they may purchase this item.

  For bothe the group and required_groups field, multiple comma separated groups can be specified. Note that there should be no spaces beween the comma separated groups.

• -persistent
  This option sets defaults for any holostore command that follows it. No button is be displayed for holostore commands with the persistent option set.

• -t template_file
  This option allows you to specify an HTML file to customize the header, footer, and background of the purchase form.

  This file should contain the token {holostore -t} which will be replaced with the purchase form when the template is displayed.

• -lt file
  This option will log all purchases in the file specified. The first line will be a list of fields, and all further lines represent purchases. Lines are tab delimited. Any tabs inside of fields are converted to spaces before logging.

• -T title
  This option allows you to change the title of the purchase form. By default, the title is "Purchase Item". If you wish to have a title with spaces, be sure to surround the title with double quotes (i.e. -T "Purchase My Book").

• -[fF] field
  This option allows you to add additional fields to the form that is presented the user when making a purchase. For required fields, use -F.

• -[cC] field text
  This option allows you to add checkbox fields to the form that is presented the user when making a purchase. 'field' is the name of the field, and 'text' is the text presented after the checkbox. You may include HTML in 'text' if you wish.

  If you wish the form to require that the checkbox be checked before allowing the user to purchase the item, use '-C' instead of '-c'

• -nocard
  When this flag is present, the customer is not asked for any credit card information or billing address.

  This flag may not be used with the -anacom or -ccn flag.

• -nocnp
  When this flag is present, the customer is not asked for their name and billing address, only their credit card information.

• -holossl
  When this flag is present, the store will go secure when asking for billing information using HoloNet's secure key (If you have your own key, you need not use this option, since the store will go secure automatically).

  For technical reasons, store the must be under the 'www.holonet.net' URL while in secure mode using the HoloNet key (it does this automatically).

• -r [file]
  When this flag is present, the customer is presented with an 'E-mail' field to fill out with the rest of their billing information. After a purchase is made, a receipt for the purchase is sent to this email address. Additionally, email address is recorded for the use of the merchant.

  If a file is specified, the text of the file is added to the end of the standard email.

• -regnum file
  When this flag is present, the customer is not asked for any credit card or billing information. Instead they are asked for a registration number. If they enter in a valid registration number, the purchase goes through and the registration number the customer entered is marked 'used' so that it may not be used again.

  All Valid registration numbers must be listed in 'file'. Registration numbers may be any ASCII string, but may not include whitespace (spaces, tabs, returns). You may include multiple registration numbers per line, seperated by whitespace.

  So for example, 'file' might contain the lines:

  123 456 789
  999 888 777

  Each of these numbers would be a valid registration number.

  Used registation numbers are placed in 'file.used', one per line. This file may be edited by the merchant as desired.

  This flag may not be used with the -anacom or -ccn flag.

  This option sets -nocard flag as a side effect.

• -remoteNotify remoteURL errorURL errorEmail
  This flag requires a setup fee to become active, and charges a fee for each purchase.

  When this flag is present, the the URL remoteURL is "touched" by the HoloStore (a HTTP GET command is issued) after each successful purchase, and given all the relevant parameters pertaining to the purchase. This allows you to use a HoloStore to purchase services you may have on web sites that are not on HoloNet.

  remoteURL presumably is a cgi script that interprets the HoloStore parameters (passed in the Query String, e.g. remoteURL?parameters) and grants access to a remote service.

  If the HoloStore is unable to touch remoteURL (due to a network failure, or whatever), the client is redirected to errorURL. That URL should be a page that notifies the client that they have been successfully charged, but that access will not be available for some period time (for example, within 24 hours).

  In the case of such a failure, email with all the relevant purchase parameters is sent to the email address errorEmail. The recipient of this mail must manually grant access to the client.

  NOTE: It would be wise for errorURL to be on HoloNet, or a provider different from remoteURL, so that the odds of both URL's being unreachable is minimized.

  An example CGI script which displays parameters is available at:

  remoteNotify.cgi?a=1&b=2	(executable, for an Apache server)
  remoteNotify.txt	(text)

  Adding a new login to a password file is system specific and not included in this example.

• -l login
  Currently unsupported.