Configuration

Deployment and Configuration

How do you install a plugin on a new server?

Basically, move the plugin's folder to the server and you may be nearly done. Make sure that the common folder is at the same level as it is in this repository so that the paths in the html file will work.

Of course you should test it. We have seen situations in which changes in required versions, deprecated functions, etc., create problems as software ages or as we deploy on servers that have different versions of some tools.

Establishing credentials: If the plugin uses an external database

(Or just needs php for some reason)

The upshot: what do you have to pay attention to?

• The value of whence. We will talk about that shortly, but you will find it near the top of foo.js. It's a string that uniquely identifies this instantiation of the plugin.
• Base php urls. This is the url of your main php file. It's stored in an object using the value of whence as a key. You will find it in the foo.constants object, which is defined in foo.js or its own eponymous file.
• MySQL credentials. These should be in a file not in github at root/cred/fooCred.php. You will need to find, alter, and install that file in the right place. Let's look at each of these in turn.

The whence variable

The variable whence is a string that identifies instantiations of the plugin. For example, when running on Tim's laptop, whence is "local". When running on eeps, it's "eeps".

whence is defined (nearly consistently) high up in foo.js or foo.constants.js. Here is the beginning of acs.js:

let acs = {
    state: null,
    whence: "local",
    allAttributes: {},     //  object containing all Attributes (a class), keyed by NAME.

That is, we can now use acs.whence as the key in that array of php urls. We will use whence in what follows.

The php URL

For access to php, you will need the URL of the php file. In our mythical foo plugin, that php file is probably foo.php in the very folder you are already in. As described in the page about integrating php and mySQL, you'll be using the Fetch API, for which you need the URL of that file.

Generally, Tim has made a constant for the full URL (he can't remember why simply using foo.php as a relative URL didn't work, or even if it didn't). It's defined in foo.js or foo.constants.js, like this (adapted from acs):

acs.constants = {
    version: "001d",

    kBasePhpURL: {
        local: "http://localhost:8888/plugins/acs/acs.php",
        xyz: "https://codap.xyz/plugins/acs/acs.php",
        eeps: "https://www.eeps.com/codap/acs/acs.php"
    }
};

Finally, mySQL credentials

For access to the mySQL database, you need a database handle, and in order to get that, you need credentials: the name of the database, a username, a password, and the URL of the mySQL server. The latter is simple: it's always localhost: we're running mySQL on the same server as we're running php. The rest are tougher. For security reasons, we don't want to put them, in cleartext, in a publicly-accessible file. So we store them above the level of the web server root.

For our plugin called foo, there might be a file called root/cred/fooCred.php that looks like this:

<?php
$credentials = array(
    "local" => array(        //  http://localhost:8888/foo/foo.php
        "dbname" => "foo",
        "host" => "localhost",
        "user" => "fooUser",
        "pass" => "foo42"
    ),
    "xyz" => array(         //  http://codap.xyz/projects/foo/foo.php
        "dbname" => "codapxyz_foo",
        "host" => "localhost",
        "user" => "codapxyz_foo",
        "pass" => "foo.wombat42"
    ),
    "eeps" => array(         //  https://www.eeps.com/foo/foo.php
        "dbname" => "denofinq_foo",
        "host" => "localhost",
        "user" => "denofinq_foo",
        "pass" => "foo42^&%"
    )
);
?>

As you can see, we store the credentials for a number of possible sites in this associative array. And the keys to the array ate the same as the whence variable.

Then, in the php itself, we do this (the beginning of a fictional foo.php):

include 'foo.establishCredentials.php';     //  tells us where the credentials are
header('Access-Control-Allow-Origin: *');
include '../common/TE_DBCommon.php';    // basic functions for connections and queries

$DBH = CODAP_MySQL_connect("localhost", $user, $pass, $dbname);   

The code in establishCredentials.php defines $user, $pass, and $dbname. We will need the output of the connect function, $DBH, for every interaction with the database.