# README for CATweb v2
View your CAT collections with a web browser!

Description
Requirements
Caution Caution Caution
Support
What's In The Package?
Installation
Start-Up
How To Start The Web Server From The CAT Sites Menu
FAQs
Known Problems and Limitations
License

## Description

CATweb lets you use your web browser to view any of your FNProgramvare CAT collection databases. Now you can view your collection with a web browser from any computer on your network.

CATweb is designed to be absolutely simple to use. You should be up and running in less than 10 minutes!

CATweb works with your existing Explorer templates.

No knowledge about web servers is needed to use CATweb. There is no Windows installation required, just drag a folder from the zip file to your disk. To remove it you simply delete the folder.

It could not be any easier!

Bundled with a very compact build of the Apache web server.

CATweb, as delivered, is intended for use on a home or local private network.

## Requirements

Any number of the FNProgramvare CAT programs.

CATweb v2 was tested at the time of release with the CAT versions listed below.

- BookCAT v9.12
- CATraxx v8.30
- CATVids v8.15
- SoftCAT v4.01
- StampCAT v9.01

Firefox/IE/Opera/Chrome (should work with any recent browser).

Windows Vista/XP (Users report CATweb works fine with Windows 7 but the author has not tested it).

## Caution Caution Caution

Please read the following information about security.

It is important to note that the Apache web server delivered with CATweb is configured for casual use within "friendly" home or local private networks. The default configuration supplied may be quite "relaxed" with respect to security.

If you intend to use CATweb as a public-facing web server you will need to take extreme care to set up your server configuration properly to be secure. The issues are precisely the same as those which need to be handled for "standard" Apache. For more information see the references listed here.

## Support

Please read this entire README file.

If you have problems, questions, or comments you can reach me by email at my lotsocds address at gmail.com .

## What's In The Package?

- The CATweb CGI program that handles the interface between your browser, the web server, and the CAT programs.
- A compact build of the Apache web server that requires no installation, plus PHP5 and GD2.
- An index.html file that can be used as a home page.
- A folder for each CAT program with a set of image files and a CSS style sheet. The image files are duplicates of the ones supplied with each of the CAT programs in the Explorer Templates folder. They have to reside in this special folder for the web server to be able to access them. The file cgi_style.css is a style sheet used in the browser and <program>.ico is the favicon displayed by your browser.

## Installation

1. Open the distribution ZIP file and copy the contents of the CATweb folder to c:\CATweb.
   You may unzip the CATweb folder to a different drive or location, just be certain that there are NO space characters in the path to the CATweb folder. The Apache web server is not self configuring. If CATweb is not located in c:\catweb then you must edit the file catweb\apache\conf\httpd.conf to correct the several absolute paths referenced in the file. Be sure all paths are updated correctly.

2. That's it -- you are finished with the installation.

## Start-Up

1. Navigate to the CATweb folder. There you will see a file called CATweb_v2_Control.exe. Double click on CATweb_v2_Control.exe to start the web server.
   When the web server is running, a blue globe icon will be displayed in the system tray. Double click the icon to stop the web server, the globe will turn grey. Double click again to restart it.

2. Start your CAT programs and start your web browser.

3. Using your web browser, browse to http://localhost. You should see the CATweb Launch page with links to browse the CAT programs.

4. Click a link to browse a CAT program you started in step 2. If all is working well you will see a familiar display from your CAT program.

   At this point you can browse your entire CAT collection.

5. Next time you want to start a browsing session you can use either of these two URL's (substitute your CAT program's name for catraxx).

   Launch page:

       http://localhost/

   Direct (use as a bookmark):

       http://localhost/cgi-bin/catweb.cgi?cat=catraxx

   To browse from another machine on your network, use the machine name or IP address of the server instead of localhost in the URLs. For example:

        http://HomeServer/

        http://192.168.1.52/cgi-bin/catweb.cgi?cat=catraxx

6. To stop the web server, double click the blue globe icon in the system tray.

7. That's it!! We are all done. You now can access your collection from your browser. The rest of this document will provide you more detailed information about all the pieces.

   ENJOY!

## How To Start The Web Server From The CAT Sites Menu

In your CAT program. go to Sites>Edit Menu. Click ADD to add a new menu item. Type "Start Web Server" in the Title box. In the Address box type the full path to CATweb_v2_Control.exe.

    Title:   Start Web Server
    Address: c:\catweb\CATweb_v2_Control.exe

## FAQs

### What should I do if CATweb does not work properly?

If you encounter any problems with CATweb not answered in this document, please send me an email.

If you created a shortcut for CATweb_v2_Control.exe be sure the Start in property points to the CATweb folder (right click on the shortcut, choose Properties > Shortcut Tab > Start in).

If the web server will not start there may be another program that is using the same port (default 80). See below for instructions on how to change the port used by CATweb.

### I just installed CATweb and the Apache web server will not start (the blue earth icon turns grey). What's wrong?

The first thing to try is manually starting Apache. To do this, open a command window and navigate to CATweb\apache and start the program mapache.exe. Take a look in the command window for an error message. This information will help to identify the problem.

### I just installed CATweb and see this error in my browser when trying to open my database. What's wrong?

ERROR: Can't connect to CATraxx
No Html File Generated

Open a command window and navigate to the folder where your CAT program .exe is located. For instance, with CATraxx that would normally be c:\program files\catraxx. At the command prompt enter the following using the appropriate CAT program name.

    catraxx.exe /regserver

### Can I use my own customized templates?

Yes. Your custom templates should work fine. Go ahead and try them. If you have any problems please email me a copy of the troublesome template.

Note that a copy of all icons, and any other image elements referenced by the templates, must be stored in the appropriate CAT program sub-folder under the catweb folder.

The web server is not able to access any image elements that your Explorer templates reference using an absolute path, or that are located outside the catweb folder and sub-folders. Paths should be relative to the CAT program sub-folder under catweb.

All URLs must use the web standard forward slash '/' and not the back slash '\'. The CAT Explorer is a little more forgiving and allows the use of the back slash in URLs.

### Why doesn't the cursor go to the search text box when opening the Index page.

You need to enable JavaScript in your browser.

### Can I run CATweb from a user account with restricted permissions?

With CATweb v2 it is possible to run from a limited user account (XP) or a standard user account (Vista).

For CATweb to run properly the administrator needs to grant the restricted user full control to the folder CATweb\apache\logs.

Setting user permissions can be a complicated business. Depending on how your system is presently configured you may need to adjust other folder's permissions to get it to work. This link may be helpful if you don't see the security tab on the folder properties on an XP system.

Please see the Known Problems and Limitations section for additional information.

### Why don't the Task links on the index/home page work?

These links can only work from within the CAT Explorer. They use a special command 'CMD' that does not work from an external program like the browser. In the browser, 'CMD' links will point back to the current page.

New in CATweb 2.4.2 you can optionally enable CMD:EDIT, CMD:GOTORECORD (and PLAY, PLAYALL, PLAYPLAYLIST, PLAYFILTER in CATraxx) to work when your browser is running on the same machine as CATweb (running locally). This feature only works for a local browser. Someone accessing the database over a network will not be able EDIT or use GOTORECORD. To enable this feature add this line to the bottom of catweb\apache\conf\httpd.conf. Apache must be restarted for the change to take effect.

    SetEnv allow_ds_calls   1

### Why don't the action icons, like play audio, play video, and open folder work?

Those are impossible things for a simple HTML web page to do from the browser without an embedded media player. Several embedded players are available on the web. You could incorporate one into your templates. Alternately, with a little JavaScript you could implement those features and a whole lot more.

New in CATweb 2.4.2 with CATraxx you can optionally enable PLAY, PLAYALL, PLAYPLAYLIST, PLAYFILTER to work when your browser is running on the same machine as CATweb (running locally). This feature only works for a local browser. Someone accessing the database over a network will not be able to play multimedia files. Sorry, but PLAYVIDEO is not supported by the data server. To enable this feature add this line to the bottom of catweb\apache\conf\httpd.conf. Apache must be restarted for the change to take effect.

    SetEnv allow_ds_calls   1

### Why do some images look bad in the web browser but look good in the CAT Explorer.

The CAT Explorer does a much better job of resizing images than your browser. There is not much that you can do to improve the look of resized images in the browser other than to change the source image's size to more closely match the size displayed in the browser.

### Can I safely delete the sub-folders under catweb for the programs that I do not use?

Yes. You can also edit the file catweb\htdocs\index.html to delete links to the programs you do not use.

### Are there any other files that I can or should delete?

The web server creates log files in catweb\apache\logs. If they get large they can be deleted when the web server is not running.

Some files may be left in the catweb\htdocs\tmp folder. They can be safely deleted.

### Is the performance the same as working in the CAT program's explorer?

Almost. The web server, web browser, and CATweb.cgi each add some processing time. Network performance could add some delay too. I'm certainly interested to hear how well you feel it works on your machine.

### How many browser sessions can be active at the same time?

You can have any number of browsers open and viewing your CAT databases subject to the following limitation. A web page may show errors if multiple browsers make simultaneous requests to CATweb.cgi. A browser refresh should clear things up. The CAT databases are always safe.

### In the CAT programs, links are made inactive when there is no data on the next page. Why are these links always active in the browser?

Some links use validate= to check for data on the following page. That look-ahead feature in not available for HTML pages generated using the CAT data server interface.

### Is there a way to hide HTML elements in the web browser but still see them in the Explorer?

Yes you can. Use an xsl:if as shown here.

    <xsl:if test="/data/@dataserver = 'No'">
      <xsl:value-of select="'SHOW THIS ELEMENT ONLY IN THE EXPLORER'"/>
    </xsl:if>

As of this writing, the above technique works with all the CATs except StampCAT and that will probably be remedied future release of StampCAT.

### Can I use JavaScript in my templates?

Absolutely. I use JavaScript extensively in my own templates. Adding JavaScript can greatly enhance your CAT browsing experience. Use the common techniques for hiding JavaScript code from non-JavaScript enabled browsers to keep your templates compatible with the CAT Explorer.

### Can I use PHP or ASP in my templates?

Yes. CATweb comes with PHP5. You'll have to figure out how to configure ASP with Apache yourself. CATweb is compatible with any web server that supports CGI so it can work with IIS.

### Where is the style sheet cgi_style.css?

In the related CAT program sub-folder under the catweb folder.

### What is CGI and what does the file CATweb.cgi do?

CGI is the acronym for Common Gateway Interface. In short, CGI allows HTML pages to interact with programming applications.

CATweb.cgi is a program. It receives URLs passed through the web server when you click a link in the browser. CATweb.cgi interprets the URL, communicates with the appropriate CAT program to get the information you are looking for in HTML format, and then presents a finished web page to the web server to deliver back to your browser.

### Does the web server produce log files?

Yes. They are standard Apache log files that can be found in the folder apache\logs.

### Where can I learn more about Apache?

The Apache Software Foundation

Micro- Apache the Apache distribution that was adapted for use with CATweb 2.0

Apache Desktop Reference free online and downloadable electronic book

### Can I use a port other than the standard port 80 for the web server?

Yes. You will need to edit the file apache\conf\httpd.conf and restart Apache.

Look for a line like this and change the port number. Apache must be restarted for the change to take effect.

    Listen 80

### Will CATweb.cgi work with other web servers.

Yes it will. CATweb.cgi has been tested with several web servers including IIS.

### Can I have the source to CATweb.cgi?

It is not available. If you are curious what's in a similar cgi program take a look at CATraxx.cgi. You can find it in the CATraxx Dataserver folder in the files section of the Traxers group on Yahoo (http://groups.yahoo.com/group/traxers/).

### What's next?

There are unlimited possibilities now that templates can take advantage of web technologies like JavaScript, AJAX, and PHP to enhance browsing your CAT collection. I may publish some fun stuff in the future, and I encourage you to experiment and share what you find and learn.

### Will you add a feature for me?

No promises, but if there's a feature you need let me know.

### I would like to contribute something to you for sharing your work. What can I do?

Well a simple thank you always helps! If you'd like to do more you can feed my other passion which is roasting coffee. A gift certificate from Sweet Marias would make me very happy.

Alternately you can use the PayPal link below, or send me an email and we can figure out something else.

Any gestures are appreciated!

As deceptively simple as CATweb appears to be, it is in fact a complex program that took countless hours of effort to develop and refine.

The link is safe, although you might need to turn off the browser plug-in NoScript for the link to work properly.

## Known Problems and Limitations

### All CAT programs

None at this time.

## HAVE FUN WITH IT!

## License

    CATweb and CATweb_v2_Control Copyright (c) 2009 by LotsOCds. All rights reserved.

    These programs are free for commercial and non-commercial use as long as the
    following conditions are satisfied.

    Copyright remains with LotsOCDs, and as such any Copyright notices in the code
    are not to be removed. If this package is used in a product, LotsOCds should be
    given attribution as the author of the parts of the product used. This can be in
    the form of a textual message at program startup or in documentation (on-line or
    textual) provided with the package.

    Redistribution and use in any form, with or without modification, is permitted
    provided that the following conditions are met:

    1. Redistributions in any form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.
    2. All advertising materials mentioning features or use of this software
       must display the following acknowledgement:
       "Based on CATweb by LotsOCds"

    THIS SOFTWARE IS PROVIDED BY LOTSOCDS "AS IS" AND ANY EXPRESS
    OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
    DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
    ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
    GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
    INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
    IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
    ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

    The licence and distribution terms for any publicly available
    version or derivative of this code cannot be changed. i.e. this code
    cannot simply be copied and put under another distribution licence
    (including the GNU Public Licence).

----------------------------------------------------------------------

                                     Apache License
                               Version 2.0, January 2004
                            http://www.apache.org/licenses/

       TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

       1. Definitions.

          "License" shall mean the terms and conditions for use, reproduction,
          and distribution as defined by Sections 1 through 9 of this document.

          "Licensor" shall mean the copyright owner or entity authorized by
          the copyright owner that is granting the License.

          "Legal Entity" shall mean the union of the acting entity and all
          other entities that control, are controlled by, or are under common
          control with that entity. For the purposes of this definition,
          "control" means (i) the power, direct or indirect, to cause the
          direction or management of such entity, whether by contract or
          otherwise, or (ii) ownership of fifty percent (50%) or more of the
          outstanding shares, or (iii) beneficial ownership of such entity.

          "You" (or "Your") shall mean an individual or Legal Entity
          exercising permissions granted by this License.

          "Source" form shall mean the preferred form for making modifications,
          including but not limited to software source code, documentation
          source, and configuration files.

          "Object" form shall mean any form resulting from mechanical
          transformation or translation of a Source form, including but
          not limited to compiled object code, generated documentation,
          and conversions to other media types.

          "Work" shall mean the work of authorship, whether in Source or
          Object form, made available under the License, as indicated by a
          copyright notice that is included in or attached to the work
          (an example is provided in the Appendix below).

          "Derivative Works" shall mean any work, whether in Source or Object
          form, that is based on (or derived from) the Work and for which the
          editorial revisions, annotations, elaborations, or other modifications
          represent, as a whole, an original work of authorship. For the purposes
          of this License, Derivative Works shall not include works that remain
          separable from, or merely link (or bind by name) to the interfaces of,
          the Work and Derivative Works thereof.

          "Contribution" shall mean any work of authorship, including
          the original version of the Work and any modifications or additions
          to that Work or Derivative Works thereof, that is intentionally
          submitted to Licensor for inclusion in the Work by the copyright owner
          or by an individual or Legal Entity authorized to submit on behalf of
          the copyright owner. For the purposes of this definition, "submitted"
          means any form of electronic, verbal, or written communication sent
          to the Licensor or its representatives, including but not limited to
          communication on electronic mailing lists, source code control systems,
          and issue tracking systems that are managed by, or on behalf of, the
          Licensor for the purpose of discussing and improving the Work, but
          excluding communication that is conspicuously marked or otherwise
          designated in writing by the copyright owner as "Not a Contribution."

          "Contributor" shall mean Licensor and any individual or Legal Entity
          on behalf of whom a Contribution has been received by Licensor and
          subsequently incorporated within the Work.

       2. Grant of Copyright License. Subject to the terms and conditions of
          this License, each Contributor hereby grants to You a perpetual,
          worldwide, non-exclusive, no-charge, royalty-free, irrevocable
          copyright license to reproduce, prepare Derivative Works of,
          publicly display, publicly perform, sublicense, and distribute the
          Work and such Derivative Works in Source or Object form.

       3. Grant of Patent License. Subject to the terms and conditions of
          this License, each Contributor hereby grants to You a perpetual,
          worldwide, non-exclusive, no-charge, royalty-free, irrevocable
          (except as stated in this section) patent license to make, have made,
          use, offer to sell, sell, import, and otherwise transfer the Work,
          where such license applies only to those patent claims licensable
          by such Contributor that are necessarily infringed by their
          Contribution(s) alone or by combination of their Contribution(s)
          with the Work to which such Contribution(s) was submitted. If You
          institute patent litigation against any entity (including a
          cross-claim or counterclaim in a lawsuit) alleging that the Work
          or a Contribution incorporated within the Work constitutes direct
          or contributory patent infringement, then any patent licenses
          granted to You under this License for that Work shall terminate
          as of the date such litigation is filed.

       4. Redistribution. You may reproduce and distribute copies of the
          Work or Derivative Works thereof in any medium, with or without
          modifications, and in Source or Object form, provided that You
          meet the following conditions:

          (a) You must give any other recipients of the Work or
              Derivative Works a copy of this License; and

          (b) You must cause any modified files to carry prominent notices
              stating that You changed the files; and

          (c) You must retain, in the Source form of any Derivative Works
              that You distribute, all copyright, patent, trademark, and
              attribution notices from the Source form of the Work,
              excluding those notices that do not pertain to any part of
              the Derivative Works; and

          (d) If the Work includes a "NOTICE" text file as part of its
              distribution, then any Derivative Works that You distribute must
              include a readable copy of the attribution notices contained
              within such NOTICE file, excluding those notices that do not
              pertain to any part of the Derivative Works, in at least one
              of the following places: within a NOTICE text file distributed
              as part of the Derivative Works; within the Source form or
              documentation, if provided along with the Derivative Works; or,
              within a display generated by the Derivative Works, if and
              wherever such third-party notices normally appear. The contents
              of the NOTICE file are for informational purposes only and
              do not modify the License. You may add Your own attribution
              notices within Derivative Works that You distribute, alongside
              or as an addendum to the NOTICE text from the Work, provided
              that such additional attribution notices cannot be construed
              as modifying the License.

          You may add Your own copyright statement to Your modifications and
          may provide additional or different license terms and conditions
          for use, reproduction, or distribution of Your modifications, or
          for any such Derivative Works as a whole, provided Your use,
          reproduction, and distribution of the Work otherwise complies with
          the conditions stated in this License.

       5. Submission of Contributions. Unless You explicitly state otherwise,
          any Contribution intentionally submitted for inclusion in the Work
          by You to the Licensor shall be under the terms and conditions of
          this License, without any additional terms or conditions.
          Notwithstanding the above, nothing herein shall supersede or modify
          the terms of any separate license agreement you may have executed
          with Licensor regarding such Contributions.

       6. Trademarks. This License does not grant permission to use the trade
          names, trademarks, service marks, or product names of the Licensor,
          except as required for reasonable and customary use in describing the
          origin of the Work and reproducing the content of the NOTICE file.

       7. Disclaimer of Warranty. Unless required by applicable law or
          agreed to in writing, Licensor provides the Work (and each
          Contributor provides its Contributions) on an "AS IS" BASIS,
          WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
          implied, including, without limitation, any warranties or conditions
          of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
          PARTICULAR PURPOSE. You are solely responsible for determining the
          appropriateness of using or redistributing the Work and assume any
          risks associated with Your exercise of permissions under this License.

       8. Limitation of Liability. In no event and under no legal theory,
          whether in tort (including negligence), contract, or otherwise,
          unless required by applicable law (such as deliberate and grossly
          negligent acts) or agreed to in writing, shall any Contributor be
          liable to You for damages, including any direct, indirect, special,
          incidental, or consequential damages of any character arising as a
          result of this License or out of the use or inability to use the
          Work (including but not limited to damages for loss of goodwill,
          work stoppage, computer failure or malfunction, or any and all
          other commercial damages or losses), even if such Contributor
          has been advised of the possibility of such damages.

       9. Accepting Warranty or Additional Liability. While redistributing
          the Work or Derivative Works thereof, You may choose to offer,
          and charge a fee for, acceptance of support, warranty, indemnity,
          or other liability obligations and/or rights consistent with this
          License. However, in accepting such obligations, You may act only
          on Your own behalf and on Your sole responsibility, not on behalf
          of any other Contributor, and only if You agree to indemnify,
          defend, and hold each Contributor harmless for any liability
          incurred by, or claims asserted against, such Contributor by reason
          of your accepting any such warranty or additional liability.

       END OF TERMS AND CONDITIONS

       APPENDIX: How to apply the Apache License to your work.

          To apply the Apache License to your work, attach the following
          boilerplate notice, with the fields enclosed by brackets "[]"
          replaced with your own identifying information. (Don't include
          the brackets!)  The text should be enclosed in the appropriate
          comment syntax for the file format. We also recommend that a
          file or class name and description of purpose be included on the
          same "printed page" as the copyright notice for easier
          identification within third-party archives.

       Copyright [yyyy] [name of copyright owner]

       Licensed under the Apache License, Version 2.0 (the "License");
       you may not use this file except in compliance with the License.
       You may obtain a copy of the License at

           http://www.apache.org/licenses/LICENSE-2.0

       Unless required by applicable law or agreed to in writing, software
       distributed under the License is distributed on an "AS IS" BASIS,
       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
       See the License for the specific language governing permissions and
       limitations under the License.