System Requirements
The feedback-enabled WebHelp system of
Oxygen XML Developer plugin requires a standard server
deployment. You can request this from your server admin and it needs the following system
components:
- A Web server (such as Apache Web Server)
- A MySQL or MariaDB database server
- A database admin tool (such as phpMyAdmin)
- PHP Version 5.1.6 or later
Oxygen XML WebHelp system supports most of the recent versions of the following
browsers: Chrome, Firefox, Internet Explorer, Safari, Opera.
Create WebHelp with Feedback Database
The
WebHelp system needs a database to store user details and the actual feedback, and a user
added to it with all privileges. After this is created, you should have the following
information:
- Database name
- Username
- Password
Exactly how you create the database and user depends on your web host and your
particular needs.
For example, the following procedure uses phpMyAdmin to create a MySQL
database for the feedback system and a MySQL user with privileges for that database. The
feedback system uses these credentials to connect to the database.
Using
phpMyAdmin to create a database:
- Type localhost in your browser.
- In the left area, select: phpMyAdmin.
- Click Databases (in the right frame) and then create a database. You can
give it any name you want (for example comments).
- Create a user with connection privileges for this database.
- Under localhost, in the right frame, click Privileges and then at the
bottom of the page click the reload the privileges link.
Deploying the WebHelp output
If you have a web server configured with PHP and MySQL, you can deploy the WebHelp output
by following these steps:
- Connect to your server using an FTP client.
- Locate the home directory (from now on, referred to as
DOCUMENT_ROOT) of your server.
- Copy the transformation output folder into the DOCUMENT_ROOT
folder.
- Rename it to something relevant, for example,
myProductWebHelp.
- Open the output folder (for example,
http://[YOUR_SERVER]/myProductWebHelp/). You are redirected to
the WebHelp installation wizard. Proceed with the installation as follows:
- Verify that the prerequisites are met.
- Press Start Installation.
- Configure the Deployment Settings section. Default values
are provided, but you should adjust them as needed.
Tip: You can change
some of the options later. The installation creates a
config.php file in
[OXYGEN_WEBHELP]/resources/php/config/config.php where all
your configuration options are stored.
- Configure the MySql Database Connection Settings section.
Use the information (database name, username, password) from the Create WebHelp with Feedback Database section to fill-in the appropriate
text boxes.
Warning: Checking the Create
new database structure option will overwrite any existing data in
the selected database, if it already exists. Therefore, it is useful the first
time you install the WebHelp with Feedback system, but you do not want to select
this option on subsequent deployments.
- If you are using a domain (such as OpenLDAP or Active
Directory) to manage users in your organization, check the
Enable LDAP Autehntication option. This will allow you to
configure the LDAP server, which will provide information and credentials for users
who will access the WebHelp system. Also, this will allow you to choose which of the
domain users will have administrator privileges.
- If the Create new database structure option is checked, the
Create WebHelp Administrator Account section becomes
available. Here you can set the administrator account data. The administrator is
able to moderate new posts and manage WebHelp users.
The same database can be
used to store comments for different WebHelp deployments. If a topic is available
in more than one WebHelp deployments and there are comments associated with it,
you can choose to display the comments in all deployments that share the database.
To do this, enable the
Display comments from other products
option. In the
Display comments from section, a list with
the deployments sharing the same database is displayed. Select the deployments
allowed to share common feedback.
Note: You can restrict the displayed comments of
a product depending on its version. If you have two products that use the same
database and you restrict one of them to display comments starting from a
certain version, the comments of the other product are also displayed from the
specified version onwards.
- Press Next Step.
- Remove the installation folder from your web server.
Important: When
you publish subsequent iterations of your WebHelp system, you will not upload the
/install folder in the output, as you only need it uploaded
the first time you create the installation. On subsequent uploads, you will just
upload the other output files.
- In your Web browser, go to your WebHelp system main page.
Testing Your WebHelp with Feedback System
To test your system, create a
user and post a comment. Check to see if the notification emails are delivered to your email
inbox.
Note: To read debug messages generated by the system:
- Enable JavaScript logging by doing one of the following:
- Open the log.js file, locate the var log= new
Log(Level.NONE); line, and change the logging level to:
Level.INFO, Level.DEBUG,
Level.WARN, or Level.ERROR.
- Append ?log=true to the WebHelp URL.
- Inspect the PHP and Apache server log files.
Documentation Product ID and Version
When you run a WebHelp with Feedback transformation scenario, by default you are prompted
for a documentation product ID and version number. This is needed when multiple WebHelp
systems are deployed on the same server. Think of your WebHelp output as a
product. If you have 3 different WebHelp outputs, you have 3 different
products (each with their own unique documentation product ID). This
identifier is included in a configuration file so that comments are tied to a particular
output (product ID and version number).
Note: The WebHelp with Feedback installation includes
a configuration option Display comments from other products that
allows you to choose to have comments be visible in other specified
products.
