MiniMate - An Administration Tool for MiniVend
**********************************************

MiniMate, formerly called MaxiVend, is a web frontend for MiniVend. It has
been written by Mike Heins, also the author of MiniVend. With MiniMate you
can easily: 
     
   * Edit MiniVend databases (e.g. add and delete columns [4.0 only])
   * Upload/Download pages and other files (e.g. images)
   * separate user administration and access control [4.0 only]
   * ...

License
*******

MiniMate is distributed under the terms of the GPL (URL:
http://www.gnu.org/copyleft/gpl.html).

Homepage, Version and Download
******************************

Up-to-date informations about MiniMate are available from 
http://www.linuxia.de/minimate/. To stay tuned with current developments
contact please <racke@linuxia.de>.

The version of MiniMate is `4.0.0.1'. An archive of this version is
available from this site (URL: minimate.tar.gz) and from ftp.minivend.com (URL:
ftp://ftp.minivend.com/pub/minimate/minimate.tar.gz) (daily updates) and can
be used on all operating systems.

MiniVend 4.00 and higher is required to running MiniMate.

Additionally there is a older version of MiniMate for the 3.x series of
MiniVend. These (MiniMate-3.14.0.3.tar.gz) requires at least MiniVend 3.12.

Demonstration
*************

MiniMate can be tested at the following locations: 

http://www.linuxia.de/mmdemo/simple/admin/menu (URL: http://www.linuxia.de/mmdemo/simple/admin/menu)

http://www.linuxia.de/mmdemo/simple/config/menu (URL: http://www.linuxia.de/mmdemo/simple/config/menu)

Installation
************

First unpack the sources in an arbitrary directory (not in the MiniVend
installation directory):

racke@linuxia.de:/tmp > gzip -cd minimate.tar.gz | tar -xf -
On a computer running Linux or with GNU tar the following is sufficient:

racke@linuxia.de:/tmp > tar -xzf minimate.tar.gz
After unpacking the sources change to the directory `MiniMate-4.0.0.1'. Then
run the `install' script with the installation directory of MiniVend as
parameter:

racke@linuxia.de:/tmp/MiniMate-4.0.0.1 > perl install ~/mvend
The script checks the existence of `minivend.cfg', creates a subdirectory `
lib/MiniMate' in the installation directory and copies the necessary files
into this directory.

Now you need to edit your `minivend.cfg' and add the following line: 


#include lib/MiniMate/minimate.cfg

The administration tool is available after a restart of MiniVend. You can
access it from every catalog. Use the pages `admin/menu.html' (with frames)
resp. `config/menu.html' (without frames). For example, the URL to access
the catalog is `http://linuxia.de/cgi-bin/simple'. Then the simpler variant
of MiniMate can be found at `http://linuxia.de/cgi-bin/simple/config/menu'.

Please note that currently protecting the administration tool against access
from other people.

Installation Problems
=====================

`Term::ReadKey' misses `resize'
-------------------------------


Can't exec "resize": No such file or directory at /usr/lib/perl5/site_perl/Term/ReadKey.pm line 305.
Unable to get Terminal Size. The TIOCGWINSZ ioctl didn't work.
The COLUMNS and LINES environment variables didn't work.
The resize program didn't work. at /usr/lib/perl5/site_perl/Term/ReadKey.pm line 323.
make: *** No targets.  Stop.

This is a known problem with Perl and MakeMaker on Solaris. There are
reports for this problem on Linux (Slackware and SuSE) where X isn't
installed. Mike Heins suggested the following workaround:


    export LINES=24 COLUMNS=80

or (for Korn and similar shells)


    setenv LINES=24
    setenv COLUMNS=80

Alternatively, you may uninstall `Term::ReadKey'.

Security
********

The administration tool should only accessible for the shop owner.

Access Control with Apache
==========================

First configure Apache to deny access to the MiniMate pages without a
password:


<LocationMatch /cgi-bin/simple/+(admin|config)>
AuthType Basic
AuthUserFile /home/minivend/users
AuthName "MiniVend Administration"
require valid-user
</LocationMatch>

The plus sign is necessary to protect against access with the URL `
/cgi-bin/simple//config/menu.html'. Enter the user name of the shop owner in
the catalog configuration file `catalog.cfg':

RemoteUser minivend
For access to the MiniMate pages by the shop owner create empty files named `
.access' in the directories `config' and `admin':

racke@linuxia.de:~ > rm -f /home/minivend/lib/MiniMate/pages/config/.access
racke@linuxia.de:~ > touch /home/minivend/lib/MiniMate/pages/config/.access
racke@linuxia.de:~ > rm -f /home/minivend/lib/MiniMate/pages/admin/.access    
racke@linuxia.de:~ > touch /home/minivend/lib/MiniMate/pages/admin/.access

Create files named `.access_gate' in the same directories to allow access by
the user authentified through Apache:

*: [perl arg="config" interpolate=1]
        return 1 if $Safe{config}{RemoteUser} eq q{[data session user]};
        return 0;
    [/perl]


Access Through the Internal Web Server
======================================

Create an non-empty file `.access' in all directories containing MiniMate
pages.All those pages are accessible only by the shop owner defined by the
catalog configuration directives `RemoteUser' and `Password':

Variable    MV_NO_CRYPT 1
RemoteUser  demo
Password    Gu3109n

The shop owner access the MiniMate pages via the internal web server
provided by the MiniVend daemon: 

http://www.linuxia.de:7786/simple/config/menu

MiniMate Usage
**************

Upload Images
=============

Uploaded files could stored only below the catalog directory. Usually you
deny access to files within the catalog directory to the web server due to
security and data protection reasons. You have to break this golden rule to
allow image upload with MiniMate. You should permit access only to the
subdirectory with the images.

For image upload please choose on the page `config/menu' "Upload other
files".

Problems
********

Fast Binary Searches
====================

If you use fast binary searching (see the MiniVend documentation for more
information) and edit the corresponding database table with MiniMate, the
index for the binary search will not get updated. This is the case for the
simple demo, where an index `category' for the `products' database exists. A
workaround for this problem is to access a MiniVend page like the following
after editing with MiniMate:


<HTML><HEAD><TITLE>Index Update</TITLE></HEAD>
<BODY>
[index table=products
        extension=category
        spec="rf=category,0
              ra=yes
              tf=category"
]
</BODY>


Inserting data containing single quotes fails
=============================================

This error occurs with MiniVend 3.11. Please upgrade.

Edit Databases Causes Runtime Error
===================================

Pumin Wuvanich reported this problem. I was not able to reproduce it. Maybe
it is related to subcatalogs.

206.111.118.118 4pedfCqg:206.111.118.118 - [30/June/1999:12:30:14 -0700] 
test01 /cgi-bin/simple/config/dbedit Runtime error: Can't use string 
("2ndDayAir") as a HASH ref while "strict refs" in use at (eval 68) line 22.
>
206.111.118.118 4pedfCqg:206.111.118.118 - [30/June/1999:12:30:31 -0700] 
test01 /cgi-bin/simple/config/dbedit Runtime error: Can't use string 
("Ground") as a HASH ref while "strict refs" in use at (eval 68) line 22.
>
206.111.118.118 4pedfCqg:206.111.118.118 - [30/June/1999:12:31:00 -0700] 
test01 /cgi-bin/simple/config/dbedit Runtime error: Can't use string 
("locale") as a HASH ref while "strict refs" in use at (eval 68) line 22.
>


User Administration and Access Control [4.0 only]
*************************************************

First you need a user database (`userdb') for the catalog managed by
MiniMate.

Configuration
=============

You need to add the database with the informations about user administration
and access control to the catalog configuration: 

Database minimate minimate.asc TAB
The database can be named differently if you set the variable 
`MINIMATE_TABLE' to the corresponding value in the catalog configuration:

Variable MINIMATE_TABLE mmcontrol
Database mmcontrol mmcontrol.asc TAB

Database Description
====================

MiniMate stores all data concerning user administration and access control
in the database `minimate'.

Field name   Description
`username'   MiniMate username
`super'      1 for superusers, 0 otherwise.
`yes_tables' space-separated list of databases
`no_tables'  space-separated list of databases


Internationalization
********************

The internationalization of MiniMate is in progress. However, additional
volunteers are needed.

A Russian, a German and a French translation has been already made.

List of MiniMate Pages
**********************


`config/db_column' [4.0 only]
     
       Add or delete columns of MiniVend databases.

`config/menu'
     
     start page for the frameless version

`config/upload_other'
     
       upload/download of arbitrary files


MiniMate for Developers
***********************

MiniMate Extensions to the MML
==============================


`directive_value' NAME [PARSEVARS]
     
     Expands to the value of the configuration directive NAME. If PARSEVARS
     has a truth value, the variables within the value are replaced by their
     value.


Undocumented Tags
-----------------

   * base-url
   * check-upload
   * counter
   * db_columns
   * dbinfo
   * display
   * display_directive
   * e
   * export-database
   * field_label [4.0 only]
   * global-value
   * grep-mm [4.0 only]
   * if-key-exists
   * if-mm [4.0 only]
   * if-sql
   * ifdef [4.0 only]
   * ifndef [4.0 only]
   * import_fields
   * list-databases [4.0 only]
   * list_directives
   * list_glob [4.0 only]
   * list-keys [4.0 only]
   * list_pages
   * mm-value [4.0 only]
   * newer
   * quick_table
   * read_serial
   * reconfigure
   * rotate-database
   * rotate-table
   * rotate_file
   * row-edit
   * send-help
   * set-alias
   * set-click
   * substitute
   * title-bar
   * unconfigure
   * uneval [4.0 only]
   * version
   * widget
   * with [4.0 only]
   * write_config
   * write_relative_file [4.0 only]

`MiniMate::CfgMgr'
==================


`mm_acl_enabled'
     
     Returns truth value if MiniMate access control is enabled.


Makefile
========


`localefiles'
     
      Updates the localization files in the `locales' subdirectory.


TODO list
*********

Bug Fixes
=========

   * Update index for binary searches
   * Edit Databases Causes Runtime Error

Miscellaneous
=============

   * Integrate help pages
   * Secure installation out of the box
   * Support MiniMate completely served by `https:'
   * Change `admin/menu' file uploads to the internal variety instead of
     using external `mv_upload' program.
   * Browse existing files (upload other files).
   * Consider version control systems for page upload.
   * Compare with ShopAdmin

Internationalization
====================

   * include only desired languages
   * use custom tag acting on the global Locale array to save a lot of
     memory by not duplicating the entries from catalog to catalog

Clean HTML code
===============

   * Use <H?> instead of font tags
   * Use style sheets instead of <FONT> tags and color attributes.
   * Validate HTML output.

Changes
*******


12. Dezember 99
     
     New makefile target `localefiles'.

8. August 99
     
     German translation from Birgitt Funk added.

5. August 99
     
     Russian translation from Alexei Yakimovich added.

28. July 99
     
     MiniMate pages prepared for localization.

26. July 99
     
     Fixed searching for records (`config/dbedit').

13. July 99
     
     Help for configuration directives shows up now.

6. July 99
     
     Fixed `Makefile.PL' for Win32 systems. Rewrote the `install' script.

29. June 99
     
     Useless import of `Data::Dumper' removed.

16. June 99
     
     Support for internationalization added.


Credits
*******

Mike Heins for writing MaxiVend in the first place and being a invaluable
resource for tips and bug fixes.

Betty Chung for preparing the MiniMate pages for localization.

Alexei Yakimovich for the Russian translation.

Birgitt Funk for the German translation.

Stephen M. LaBar, Jr. for his help to make `Makefile.PL' working on Win32
systems.

Kaare Rasmussen and Robert Hutchinson for reporting the `resize' problem and
again Mike Heins for the workaround.

Bob Jordan for reporting the `Data::Dumper' problem.

Marc Infield for reporting a documentation bug (20000103).

Waldemar Gerr for his suggestion on documenting the installation.

Marci Beedle for reporting his problem with the documentation in respect of
an MiniMate URL.

History
*******


28. Februar 2000
     
     Version 4.0.0.1 released

12. July 99
     
     Version 3.14.0.3 released

30. June 99
     
     Version 3.14.0.2 released

29. June 99
     
     Version 3.14.0.1 released