Documentation

This documentation gives a overview of the site structure and instructions on setting up your own Evidence Hub.

NOTE: The Evidence Hub code base is released under the LGPL license: http://www.fsf.org/licensing/licenses/lgpl.html.
It includes third party code which should all have licenses which are compatible with LGPL (see /core/lib and /ui/lib folders to view third party libraries used)

If you need more help, please ask your questions through our Evidence Hub Reporting System, or join the Evidence Hub Google Group (Go to the Community page)

MySQL

This first version of the Evidence Hub only uses MySQL as the database (we may offer other options in future releases).
So you will need to install MySQL on your server.

Email

The Evidence Hub uses emails to tell users their registration is successful etc. and send out email digests of items or people they are following.
So your server should be able to do emailing if you want these to be sent. You can switch off emailing with a setting in the config file if required (see Config Settings, below).

Crons

To send out the digest emails you will need to setup three cron jobs. An example is shown below.
To use the lines below you need to add the file system path to your Evidence Hub code where indicated:

The top level of the file structure has the config.php file, (see Config Settings, below) and the setup.php file.

This level also has the files for the other main context pages of the site: index (for the global context) explore (for the item context), user, search and the fav icon etc..

The Folders:

admin – This folder has various files that run the activity digest email cron jobs, hold the administer themes page, the register new user form, the user statistics page etc..
If you are a user who has the ‘IsAdministrator’ field in the Users table set to ‘Y’, you will see an
extra menu item when logged in at the top of the screen called ‘admin’.
This page currently only has the ‘Register New User’ link.
In future releases it will have more.

If you are logged in as the Site admin user (see $CFG->ADMIN_USERID in the Config Settings section below), you will see a ‘Manage Themes’ option to allow you to add, edit and delete system Themes.
This should really only be done before a hub is up an running. Be very careful deleting or editing Themes once people have started using them. Think about the consequesnces carefully.

datamodel – This holds that classes that hold that database record information when it is loaded. There are classes for all the mail items types, like user, node, linktype etc…

formats – This holds the files that process the api return data into the correct format, e.g. json, xml etc..

lib – This holds all the external libraries that the evidence Hub is using in the server side code.

docs – This is where there are some additinal develop docs.

Once you have finished the install process you may want to remove this folder from your website.

help – This is where the help pages are. But the actual text can be found io the language folder.

images – This is where all the graphics for the site are.

install – This folder has setup notes, the sql file needed to create a Evidence Hub database and the script to install the default data. See Setting up an Evidence Hub below.

Once you have finished the install process remove this folder from your website.

io – This folder holds the code to handle the import options in the Evidence Hub: currently just from Compendium.

language – This folder holds the language files for all the interface text. By changing the $CFG->language property (see below) you can override the default language of ‘en’ and add a different folder and then convert all the language files to another language if you want to. For more details on how this works see Language below.

en – This holds the default English language version of all interface text shown to the user. Please never remove this folder.

custom – This folder will intially be empty, and is where you will place any site specific text overrides, (see Site specific text below).

ui – This folder has most of the client side code e.g. header, footer, sidebar etc.

explore – This holds that classes that create the debate and widget explore pages.

geomaps – This holds the files that produce the geographic map pages

lib – This holds all the external libraries that the evidence Hub is using in the client side code.

ckeditor – This folder holds the library that handles the html wysiwig editor displayed in forms.

scriptaculous – This folder holds the library that handles the string matching for idea creation and search entries and then draws the
drop-down box to select from as the user types.

networkmaps – This holds the files that create all the network applet pages. It also has the subfolder holding the java applet jar files.

popups – This holds the files that are shown in popup windows, like the add and edit forms, the story forms, the print pages etc..

styles – This holds the css files.

uploads – This folder holds user profile pictures. Each user will have a folder
in here labelled uniquely. This folder also holds the default user and group images to use when no image has been uploaded.

Create an empty database for the Evidence Hub to use in your MySQL installation,
making sure that the database character set and collation are UTF-8, e.g.CREATE DATABASE dbname CHARACTER SET utf8 COLLATE utf8_general_ci;

If you do not want to use utf8, you will need to edit the db.sql file before you run it in c. below, as the table creation statements are using utf8.

Create a MySQL user for the Evidence Hub to use.

Load the database schema from /install/db.sql into your new Evidence Hub Database to create all the required tables.

Adding the Default Data:

Edit /install/adddefaultdata.php. You must fill in the following data in the file:

$dirAddress = the file path to where you website code resides on the server (ending in ‘/’)

$databaseuser = the username of your mysql user for the Evidence Hub, as created in step 1b above;

$databasepass = the password of your mysql user for the Evidence Hub, as created in step 1b above;

$databasename = the name of your mysql database for the Evidence Hub, as created in step 1a above;

$email = fill in a default user email address for the Evidence Hub – this can be made up. This user account owns the default node and links types and acts as a template for all subsequent user accounts;

$password = fill in an default user password for the Evidence Hub;

$email2 = fill in a theme admin user email address for the Evidence Hub – this can be made up. This user account manages the Evidence Hub Themes list and is called the System Admin user.

$password2 = fill in an theme admin user password for the Evidence Hub;

Edit /install/adddefaultdata.php some more.
You must decide now if you want to change the Evidence Node types supplied in this file.
If you do, edit the appropriate section of this file which has the heading ‘Evidence Types’.
We supply four Evidence Types by default – Anecdote, Case Study, Policy and Research Finding.
You can edit any of these or add more.

To add another Evidence node type you will need to decide/create an icon and place it in ‘images/nodetypes/Default’ add the follow lines of code:

You will find all these lines of code in the adddefaultdata file with instructions.

If you add more please make sure you also add a new line for each new Evidence Type in the ‘Evidence Types into the Evidence Group’ section of this file.

NOTE: If you ever need to add a new Evidence Type after this file has been run, make sure you add it to that database against the default user account and then any other Users accounts that exist at that time. And also add it to the Evidence NodeTypeGrouping table for the Evidence Group

Now run the adddefaultdata.php file on your server. You can do this in two ways:

Run it from the command line. Note that the file will output data that you will need, specifically two UserIDs (as well as possible error messages). You can get the user ids you will need from the database Users table if required.

Surf to the file through your browser. In this case the two user id’s will be displayed on screen as will any error messages.

When it completes (hopefully without error) make a note of the user id for the System Admin User and the Default User. You will need these in a moment to put in the Config file.

Copy /config-sample.php to /config.php

Edit settings in /config.php to point to your set up and database and to configure other important aspects of the Evidence Hub.

for the setting $CFG->ADMIN_USERID and $CFG->defaultUserID you need to copy in the userids given from step 2c. above.

Some setting you MUST NOT change as they are default or static system data for the site.

The ones in red represent the minimum settings that you must look at and edit as required.

(Please respect the comments on the settings that say ‘Leave this alone’!)

At this point you should be able to surf to the website and check it comes up OK.
It will, of course, have the default supplied look and feel
(using any header icon you have specififed in the config),
but you can at least test that all is working thus far.

If all is well, remove the install folder from your website and probably the docs folder as well. (Unless you want people to be able to surf to these docs for some reason).

Setting up the Themes:To complete the default data your Evidence Hub will need, you now need to add the Themes specific to your domain.

Login as the System Admin user (using the details you used in 2a above).

You should now see an ‘Admin’ link at the top-right of the website. Click on this link.

On the admin page click on the ‘Manage Themes’ link.

This opens a new window with the Theme Manager in. You can now add the Themes you want to use for your Evidence Hub

While you can always add themes later on, think carefully about editing and deleting them once they are in use.

Node Types

( These are the basic node types for the Evidence Hub Datamodel. There is some flexibility. You can if you chose remove Challenge. You can also choose to remove either Solution or Claim, but not both. If you remove both the site will not work. If you remove any other node types the site will not work properly.)

( These are the default Evidence Types. If you have changed them when you installed your default data please edit these to be exactly the same as your Evidence Type names in the database. )

$CFG->RESOURCE_TYPES = array("Publication","Web Resource");

( These are the default Resource Types. If you have changed them when you installed your default data please edit these to be exactly the same as your Resource Type names in the database. )

$CFG->EVIDENCE_TYPES_DEFAULT = "Anecdote";

( This is the default Evidence Type selected in the interface. This must match one of the Evidence Types listed in the EVIDENCE_TYPES property above. )

$CFG->RESOURCE_TYPES_DEFAULT = "Web Resource";

( This is the default Resource Type selected in the interface. This must match one of the Resource Types listed in the RESOURCE_TYPES property above. )

Link Types

WARNING: Only edit these names if you have also edited them in the database linktype table. The two must match or the Evidence Hub code will not work properly!

$CFG->LINK_SOLUTION_ISSUE = ‘addresses’;

$CFG->LINK_CLAIM_ISSUE = ‘responds to’;

$CFG->LINK_ISSUE_CHALLENGE = ‘is related to’;

$CFG->LINK_EVIDENCE_SOLCLAIM_PRO = ‘supports’;

$CFG->LINK_EVIDENCE_SOLCLAIM_CON = ‘challenges’;

$CFG->LINK_ORGP_ISSUE = ‘addresses’;

$CFG->LINK_ORGP_CHALLENGE = ‘addresses’;

$CFG->LINK_ORGP_CLAIM = ‘claims’;

$CFG->LINK_ORGP_SOLUTION = ‘specifies’;

$CFG->LINK_ORGP_EVIDENCE = ‘specifies’;

$CFG->LINK_ORGP_ORGP = ‘partnered with’;

$CFG->LINK_ORG_PROJECT = ‘manages’;

$CFG->LINK_COMMENT_NODE = ‘is related to’;

$CFG->LINK_NODE_THEME = ‘has main theme’;

$CFG->LINK_RESOURCE_NODE = ‘is related to’;

( Leave alone unless you know what you are doing! )

URL Setup

$CFG->homeAddress = "http://web/path/to/website/";

( home address is the base url for the website and must end with trailing ‘/’ )

$CFG->dirAddress = "/file/path/to/website/";

(dir address is the base file path for the website)

Database Setup

$CFG->databaseaddress = "localhost";

(The database address, e.g. localhost or a url etc.)

$CFG->databaseuser

(The database username that Cohere uses to login to the database)

$CFG->databasepass

(The database password to go with the above username)

$CFG->databasename

(The database name for the Evidence Hub is to use)

Language

$CFG->language = ‘en’;

(This string indicates what language the interface text should use. The name must correspnd to a folder in the ‘language’ folder where the translated texts should exist.)

For more information about the language system please see Language below.

$CFG->defaultcountry = “United Kingdom”;

(Country name as it appears in the language/<your language as above>/countries.php list to used as the default selection in Countries menus. If you change the language used you must also change this text.)

Bits and Pieces

$CFG->workdir = "/tmp/"

(The path to a temp directory that Evidence Hub can use)

$CFG->hasCompendiumImport = false (or true);

(Does this site want to use a Compendium import. Note: the default import may need to be modified to match any site specific changes. )

$CFG->hasUserHomePageOption = false (or true);

(Does this site want to have the homepage field on the user registration/profile forms. )

$CFG->hasConditionsOfUserAgreement = false (or true);

(Does this site want to display a Conditions of use Agreement statement when user’s sign up? The default text for this can be overriden in the language custom folder.)

Add another language: You can change the language you are using by translating all the language files into another language.

Site specific text: You can change the text in your version of the hub to be site specific.

Adding another language

If you want to add a new language set to the Evidence Hub you need to:

Create a new folder inside the ‘language’ folder whose name the two letter abbreviation for the language you are providing a translation for.
These codes are specified by the ISO 639 standard, e.g.

Language Code

Language

en

English

fr

French

it

Italian

de

German

Copy the language files from inside the default ‘en’ language folder into you new folder.

Inside any given language file, each item is set up as a key/value pair, in the form key=’value’.
You must translate/change only the values on the right hand side, NEVER change the key name on the left.

Change the language variables in the config file: $CFG->language = ‘en’; and $CFG->defaultcountry = “United Kingdom”; to reflect your new language of choice.
The $CFG->language setting must match the folder name for your new language.

NB: Some HTML is mixed up in the language files especially in the language heavy areas like the About and the Help pages.

The languagecore.php file contains the node and link names used by other language files. It will always be loaded first so that other language files can refernece it.

To provide site specific text for any of the interface languages you follow this basic pattern:

Locate the term you wish to replace in the language files.

Create a files with the same name as the file containing the term you wish to change but with ‘Custom’ at the end and place it in the ‘custom’ folder of the language file you are using.
So, for example, if you wish to replace the About page in the English language files, create a file in the ‘language/en/custom’ folder called ‘aboutCustom.php’.

Inside this new file you must use the same key label on the left as in the original file, and then just replace the part on the right after the ‘=’ sign.
All files in the ‘custom’ folder are loaded after the ones outside, and provided you have used the same keys, the text will be replaced with your version when the language files are loaded.

NOTE: If what you want to change any of the core terms, the names of the categories or links, for example, if you wish to call ‘Themes’ say ‘Topics’ instead on your Hub, you can just create a custom languagecore.php file
and change the text in that. These terms will ripple through the rest of the interface text as all the rest of the text should reference those terms through their keys.
This makes it easy to change the basic terminology for a given Hub community without editing lots of interface text.

IMPORTANT: There are two none-standard items in the language folder that are not handled in the same way as the other language files:

The countries.php file: This holds the country names used in the location drop-down menus displayed to users.
When translating these, please, as with the other files change only the part on the right after the ‘=’.
NOTE: this file may need updating if new countries come into existence.
The location of where to check for updates is in the file header.

The mailtemplates folder: The files inside this folder are used when constructing the emails send out to users.
When translating them please change only the words and leave all HTML alone, unless you know what you are doing.
Be especially careful about leaving all %s items alone.
These are replace with specific text when an email is created.
So the number of %s and their order in the file is very important. Please don’t remove any or that email will no longer be written correctly.

Currently the Evidence Hub does not have a Themes system, though we hope to introduce one for the next release.

So at present, if you want to change the look and feel or text of your Evidence Hub, these are the main places you should look at making changes:

Text: All text displayed in the Evidence Hub has been placed in various files in the ‘language’ folder system.
So you can override all the default texts your specific site needs.
You may especially like to add to or redo the about page (language/en/about.php).
REMEBER: never edit the original language files. Always use the Custom file override system.
You can also provide sets of lanbguage files for other languages.
(See the Language section of these notes for more details).

Homepage: The file that draws the homepage (ui/homepage.php) is in the ‘ui’ folder. While all the text can be changed through the language files, you may want to completely redo this page for your specific Evidence Hub.

Styles: The style sheet for the ui can be found in ‘ui/styles/’. At present you would edit the originals. Therefore you may like to copy them before editing and call them something like style.css.ori etc..

Images: All icons and images can be found in the ‘images’ folder. Like the styles, for the present you would replace the originals to change them. Just keep the names the same as the originals when you replace any icons and you will not need to edit any code.

Headers and Footers: The header and footer files can be found in the ‘ui’ folder:

There are the main ‘header.php’ and ‘footer.php’ that do the base site pages.

There are ‘dialogheader.php’ and ‘dialogfooter.php’ that do the pages in the popup windows, like the add/edit forms.

There are the ‘reportheader.php’ and ‘reportfooter.php’ that do the printed reports.