Signature Mill

Installation and Configuration Guide

This guide is for system administrators of discussion group forum sites to use in installing and configuring the program known as Signature Mill.

You can read the application’s info.pdf file to learn about Signature Mill itself.

Although Signature Mill can run on its own, it was designed to be installed and run along with forums that operate under the Simple Machine® Forum software.

https://www.simplemachines.org/

A brief discussion at the end of this document explains how to set up Signature Mill on its own and with forum software other than SMF.

Address questions and comments to:

al@alstevens.com

Amazon Web Services

Signature Mill uses features of AWS that search Amazon’s product pages for books. To use those features, the hosting site administrator must join two AWS programs.

This sign-up process might seem intimidating, but you have to do it only once. After that the drudgery is behind you.

Associate

You must become an Amazon Associate, an individual who promotes Amazon products by appending tags to the links that take customers to Amazon’s product pages where they can purchase items. The Associate is paid a commission for every sale resulting from a link that includes the associate’s tag in its URL. You apply to be an Amazon Associate, and they assign to you a code that becomes your associate tag.

Here’s an example of a tagged URL.

https://www.amazon.com/dp/B00O5CGCZ6/?tag=alste-20

The bold text at the end is the tag, in this case the tag of the author of this software. Your installation of Signature Mill lets you program your own tag as its default, which is inserted into the signatures the program generates for your members.

Go to this website to learn about the associates program and apply for your own free tag:

https://affiliate-program.amazon.com/

(The program is named “associates” but the website is named “affiliates.”)

Note that even if you don’t care whether you are credited with sales from your site, you need to be an associate for the second program, which you must join for Signature Mill to work.

Product Advertising API (PAAPI)

To search for Amazon products, Signature Mill uses Amazon’s Product Advertising Application Program Interface. PAAPI is a protocol that programs such as Signature Mill use to send queries to Amazon and retrieve digital responses which list the books that match the query criteria.

To use PAAPI, a program such as Signature Mill, must provide credentials in the form of a key pair, an Access Key ID and a Secret Access Key. Amazon provides those keys when you sign up for the program and request credentials.

The journey through Amazon’s web-based program can be complex and less than intuitive. It is suggested you start here:

https://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html

Navigate the site and get registered and signed in to request your key pair credentials. You’ll need them when you configure Signature Mill below. Keep in mind that you are provided the Secret Access Key only once and you can download both keys at that time. Make permanent copies of them.

Distribution

Signature Mill is distributed in a .zip file accompanied by this document. Your concerns are:

1. Where to unzip the file

2. How to configure Signature Mill

3. How to link to Signature Mill from your forum’s website

Installation

You can install Signature Mill along with you SMF forum’s software, other forum software, or all by itself. In all cases you need the ability to upload files to a server. That requires you to have File Transfer Protocal (ftp) access to the server, which you needed when you installed your forum’s software.

A utility that eases the complexities of FTP can be found here:

https://winscp.net/eng/index.php

Installing with Simple Machines® Forum

Signature Mill must run from the server that hosts your SMF forum. To install:

1. Unzip Signature Mill’s zip file somewhere on your local computer.

2. Create a subdirectory on the server in the SMF’s Sources subdirectory. For these discussions we assume the name to be sigmill. It can be anything you or your webmaster choose as long as it does not conflict with another subdirectory name at the same level on the server.

3. Upload the unzipped files to the sigmill subdirectory on the server.

4. Proceed with Configuration below.

Standalone Installation

You can install Signature Mill anywhere as long as it’s on a server that supports PHP and MySQL. To install:

Your webmaster must:

1. Create a MySQL database with a name of your choosing.

2. Create a username and password that grant access to the database.

3. Create a subdirectory on the server to host Signature Mill. Again, we assume the name is sigmill.

You must:

1. Make note of the subdirectory and database names, username, and password.

2. Unzip Signature Mill’s zip file somewhere on your local computer.

3. Upload the unzipped files to the subdirectory on the server.

Configuration: TSMSettings.php

Before you can run Signature Mill, you must configure it. You do that by changing text code entries in the file named TSMSettings.php. The following steps explain each of those entries. Make a copy of the original in case you make mistakes in your changes.

Of course, to make these changes, you need to know how to use a text editor.

The Database

If you are installing Signture Mill along with SMF software, these entries in TSMSettings.php need not be changed, and you can move to the next step.

If you are installing elsewhere, you must address them. These are PHP variables to which you assign values based on what you and your webmaster agreed to when the database was created.

The database variables are commented out between /* … */ tags and given mnemonic values. Uncomment the block and change the values accordingly. Make sure you include all values in quote marks as their mnemonic substitutions do.

$db_type = 'mysql';

$db_server = 'localhost';

$db_name = 'DATABASE NAME';

$db_user = 'SQL USER';

$db_passwd = 'SQL PASSWORD';

$db_table = 'sm_members';

The first two variables are typically not changed. Your webmaster can tell you if they must be. The next three are always changed, and you will assign the values you noted when the webmaster created your database. The $db_table variable is provided to cover the unlikely situation wherein the database you are given access to already has a table named sm_members.

Your Amazon Associate Tag

This is the tag that Amazon assigned to you when you signed up as an Associate. It is appended by default to the URLs that the members’ signatures provide so others can link to their books on Amazon.

$associate_tag = 'SITE ASSOCIATE TAG';

Members’ Amazon Associate Tags

Signature Mill allows members to substitute their own Associate tags in place of yours. You might want to disable that feature. To do so, change this variable to false.

$usertag_enabled = true;

Why would you want to disable this feature? In order for Amazon to continue to grant you access to the PAAPI, they must see sales originating from your website. They identify you by the Associate tag appended to the URL links that result in sales. If they do not see sufficient sales, they will invalidate your credentials, and the retrieval functions of Signature Mill will cease to work. When you allow your members to override your tag, you lessen the number of sales accredited to your Associate account.

PAAPI AWS Access Keys

When you sign up to allow Signature Mill to use the AWS search engine, Amazon, as explained above, assigns two keys, a private one and a public one. To allow Signature Mill to make the searches, you must encode those keys in the variables shown here:

$key_Private = 'AWS PRIVATE KEY';

$AWSAccessKeyId = 'AWS PUBLIC ACCESS KEY';

Donation Button

This is optional. If you have a PayPal account, you can have PayPal construct the HTML code you’d need to display a button that users can use to link to PayPal and donate money to your account. PayPal’s code is in the form of a string of text. Place it inside single quote marks as the value initialized to the $donation variable.

$donation = 'PAYPAL FORM CODE';

If you wish to solicit no donations, place no text inside the quote marks. If you wish to allow users to donate to help development of Signature Mill and other writer-oriented software, leave the code with which the software is distributed.

Testing the Configuration

When you have made all the changes to TSMSettings.php;

1. Upload the modified TSMSettings.php file to the subdirectory on the server to replace the file that is already there.

2. Run Signature Mill by typing the URL where you installed it into your browser’s address bar.

3. If it doesn’t work according to the user’s guide, review and correct your changes.

Linking Signature Mill from your Forum

You probably prefer to include a link on your forum site that your members can click to open Signature Mill. Adding such a link involves getting inside the PHP code that drives your forum’s software. This section shows you how to modify the code in the SMF software. It also briefly discusses installing on forum sites that use other software, but not in any detail whatsoever.

As forum administrator, you have access to the program code that drives your forum. Knowledge of that code is another thing. The procedures given here might seem intimidating, but if you follow them to the letter, they should work.

The best advice you can heed is this: Make a backup copy of any code file you intend to modify and know how to restore it to its original state in case your changes have ill effects on your forum. Make your changes in small increments and test each increment by making sure the forum software still works.

Given that you have already installed and are operating the forum’s software on your server, these instructions should be, at the very least, manageable by you. If you are completely intimidated by what follows, employ the services of a PHP programmer for an hour or two.

From your SFM installation

First, if you installed Signature Mill according to the instructions above, the software that needs to be linked to is in your site’s Sources subdirectory in its own subdirectory named sigmill. Therefore, to run Signature Mill, you enter its address into your browser’s address bar like this:

https://www.yoursite.com/Sources/sigmill

That runs the program from the browser’s address bar. To install a link into one of your webpages, all of which are located in the Sources subdirectory, you install one at the appropriate place in the code that says something like this:

<br><a href="sigmill">Signature Mill</a></br>

The trick is to find where in the SMF source code to place that line of code. The next trick is to insert the code and test it. You can mark and copy lines of code from this document to insert the modification code into your forum source code files.

You might want the link to show up in the footer of each page just above the copyright notice. To do that you must modify the files named index.template.php for each of the themes you allow users to opt for, or, if there is only one theme, that file for your theme only.

Themes files are located in the Themes subdirectory where you installed SMF. Each theme has its own subdirectory named with the name of the theme. The index.template.php file is found there.

Now to modify the file.

1. Search for the second instance of the word “footer” in the index.template.php file. You will see a line of code like this:

<div id="footer_section"><div class="frame">

2. Insert this line of code after the code just shown.

<br><a href="sigmill">Signature Mill</a></br>

3. Run your SMF forum and look at the bottom of the page.

4. Click the Signature Mill text to open Signature Mill

The procedures are the same for other themes.

If you wish to display Signature Mill’s logo instead of its name, use this line of code in step 2 above:

<br><a href="sigmill"><img height="40" src="sigmill/images/logo.gif"/></a></br>

If you’d prefer to add an entry to the horizontal menu at the top of the page:

1. Open the file named Subs.php in the Sources subdirectory.

2. Find this line of code.

function setupMenuContext()

3. Insert this line of code two lines down past the global declarations.

$txt['sigmill'] = 'Signature Mill';

4. Find this line of code:

'logout' => array(

5. Immediately ahead of that line of code, insert this code:

'sigmill' => array(

    'title' => $txt['sigmill'],

    'href' => 'sigmill/index.php',

    'show' => !$user_info['is_guest'],

    'sub_buttons' => array(

    ),

    'is_last' => !$context['right_to_left'],

),

When you copy and paste this code, it will probably be double-spaced. That won't hurt anything, but you might want to change the line spacing and indent so it fits in with the appearance of the rest of the code.

From Other Sites

To insert links to Signature Mill from forum sites not using SMF software requires that you dig into their code and find where the best place is to insert the link codes given above. SMF has discussion forums for administrators and developers, and probably so do the other forum software vendors. That’s where you must start.

By Itself

You can run Signature Mill independently of other software packages by installing it in it own subdirectory on the server and revealing its URL to its potential users. Signature Mill uses no components of the forum software other than the Settings.php file of SMF, and the Configuration discussion above explains how to avoid needing that file by providing entries in the file named TSMsettings.php.