Documentation

Contents

Intro

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)

System Requirements

The Evidence Hub code has been developed and tested on a Red Hat Enterprise Linux server using:

Apache 2.2.15.

Please add the following in your Apache config:

Options All -Indexes -MultiViews

RewriteEngine on

AllowOverride FileInfo AuthConfig

If you have .htaccess files disabled (AllowOverride none), it will not affect the running of the site.

Our .htaccess file has the following:

#RewriteEngine on

#RewriteCond %{REQUEST_URI} !/index-maintenance.php$

#RewriteRule $ /index-maintenance.php [R=302,L]

ErrorDocument 404 /404-error-page.php

ErrorDocument 403 /403-error-page.php

So we use it for having site specific 404 and 403 pages.

We also uncomment the first three lines if we want to put the hub into maintenace mode
and display a holding page to the user (index-maintenace.php)

PHP version 5.3.3

Modules installed:

bcmath,bz2,calendar,Core,ctype,curl,date,dba,dom,enchant,ereg,exif,fileinfo,filter,ftp,
gd,gettext,gmp,hash,iconv,imap,intl,json,ldap,libxml,mbstring,mcrypt,memcache,mysql,mysqli,odbc,
openssl,pcntl,pcre,PDO,pdo_mysql,PDO_ODBC,pdo_pgsql,pdo_sqlite,pgsql,Phar,phpcups,posix,pspell,
readline,recode,Reflection,rrdtool,session,shmop,SimpleXML,snmp,soap,sockets,SPL,sqlite3,standard,
sysvmsg,sysvsem,sysvshm,tidy,tokenizer,uuid,wddx,xml,xmlreader,xmlrpc,xmlwriter,xsl,zip,zlib

The Evidence Hub is not necessarily dependent on all these modules.

We will try and have a more reduced list before release 2.0.

NOTE: In your php.ini make sure set allow-url-fopen = on.

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:

0 2 * * * php path to code/admin/cron-follow-daily.php

0 1 * * 4 php path to code/www/admin/cron-follow-weekly.php

0 1 25 * * php path to code/www/admin/cron-follow-monthly.php

A Quick What’s Where

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.

  • api – This folder holds the Evidence Hub services file that processes incoming service request,
    (see core/apilib.php for the actual guts).
  • core – This is where the server side code resides.
    • 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.
    • pages – This holds the secondary page files, like login and logout, register, conditionsofuse etc..
    • 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.

Setting up an Evidence Hub

  1. Creating the Database:
    1. 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.

    2. Create a MySQL user for the Evidence Hub to use.
    3. Load the database schema from /install/db.sql into your new Evidence Hub Database to create all the required tables.
  2. Adding the Default Data:
    1. 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 ‘/’)
      • $databaseaddress = the address of your mysql database – usually localhost;
      • $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;
    2. 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:


      $nextID1 = getUniqueID();
      $qry .= "INSERT INTO `NodeType` VALUES ($nextID1,'".$userid."','<name of new Evience Type>',0,'images/nodetypes/Default/<new image filename>');";

      You will then need to also add the new evidence type to it’s group:


      $qry .= "INSERT INTO `NodeTypeGrouping` VALUES ('13710825192130',$nextID1,'".$userid."',0);";

      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

    3. Now run the adddefaultdata.php file on your server. You can do this in two ways:
      1. 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.
      2. 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.

  3. Copy /config-sample.php to /config.php
  4. 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.

    All config file settings are explained below in Config Settings.

    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’!)
  5. 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.
  6. 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).
  7. 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.
    1. Login as the System Admin user (using the details you used in 2a above).
    2. You should now see an ‘Admin’ link at the top-right of the website. Click on this link.
    3. On the admin page click on the ‘Manage Themes’ link.
    4. 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.

Config Settings

All setting have comments explaining their use.

$CFG->SITE_TITLE = "The title of your Evidence Hub";

( This is used in the header title as well as being displayed to the user in various places. )

$CFG->ADMIN_USERID = "the database user id number of your System administrator";

( This person is the owner of the Theme nodes in the system and you have to log in as them to manage themes.)

$CFG->defaultUserID = "the database user id number of your Default user";

( This person acts as a template for new users. Thier node and link types are copied into new user accounts.)

Node Types

$CFG->BASE_TYPES = array("Challenge","Issue","Solution","Claim","Organization","Project","Theme");

( 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.)

$CFG->HAS_SOLUTION = in_array(‘Solution’, $CFG->BASE_TYPES);

( Leave this alone. It checks to see if you are using Solutions )

$CFG->HAS_CLAIM = in_array(‘Claim’, $CFG->BASE_TYPES);

( Leave this alone. It checks to see if you are using Claims )

$CFG->HAS_CHALLENGE = in_array(‘Challenge’, $CFG->BASE_TYPES);

( Leave this alone. It checks to see if you are using Challenges )

$CFG->COMMENT_TYPES = array("Comment");

( Leave this alone. )

$CFG->EVIDENCE_TYPES = array("Anecdote","Case Study","Policy","Research Finding");

( 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.)

$CFG->welcomeMovie = “http://www.youtube.com/watch?feature=player_embedded&v=0fB2Kd2La8g”;

(We supply a default movie about the eviednce Hub. If you want the Homepage to show a different movie, change this link.)

$CFG->homeTagCount = 20;

(How many tags to show in the home page tag cloud. We set 20 as the default.)

Site Registration

$CFG->SIGNUP_OPEN = “open”;

(Leave this alone. If you use this state for signup below, then users can register themselves for using the Hub)

$CFG->SIGNUP_REQUEST = “request”;

(Leave this alone. If you use this state for signup below, then users can request an account for using the Hub which is then validated by the Hub administrator)

$CFG->SIGNUP_CLOSED = “closed”;

(Leave this alone. If you use this state for signup below, then users cannot register, they must be sent login details. So by invitation only.)

$CFG->signupstatus = $CFG->SIGNUP_CLOSED;

(Set this to one of the 3 above states. The default is SIGNUP_CLOSED.)

$CFG->signuprequestemail = ”; //defaults to $CFG->EMAIL_REPLY_TO

(The email address of the Hub user managing the registration requests if SIGNUP_REQUEST is used. They must be ad admin user (IsAdmin set to ‘Y’ in Users table the database))

Site Logos

$CFG->headerlogo = “evidence-hub-net-logo.png”;

(The file name of the main site header logo. This should be located in the ‘images’ folder.)

$CFG->dialogheaderlogo = “evidence-hub-net-logo-sm.png”;

(The file name of the smaller site header logo used in the popup windows. This should be located in the ‘images’ folder.

We have found that around 180-200px wide works well.)

$CFG->emailheaderlogo = “evidence-hub-net-logo-sm.png”;

(The file name of the site logo used in emails sent by the Hub. This should be located in the ‘images’ folder.

We have found that around 180-200px wide works well.)

Node Icons

The file paths for the node type icons used.

These are currently only referenced in ui/datamodel.js.php

$CFG->challengeicon = $CFG->homeAddress.”images/nodetypes/Default/challenge.png”;

$CFG->issueicon = $CFG->homeAddress.”images/nodetypes/Default/issue.png”;

$CFG->claimicon = $CFG->homeAddress.”images/nodetypes/Default/claim.png”;

$CFG->solutionicon = $CFG->homeAddress.”images/nodetypes/Default/solution.png”;

$CFG->evidenceicon = $CFG->homeAddress.”images/nodetypes/Default/litertaure-alaysis.png”;

$CFG->resourceicon = $CFG->homeAddress.”images/nodetypes/Default/reference-32×32.png”;

$CFG->orgicon = $CFG->homeAddress.”images/nodetypes/Default/organization.png”;

$CFG->projecticon = $CFG->homeAddress.”images/nodetypes/Default/project.png”;

$CFG->proicon = $CFG->homeAddress.”images/nodetypes/Default/plus-32×32.png”;

$CFG->conicon = $CFG->homeAddress.”images/nodetypes/Default/minus-32×32.png”;

(Leave these alone.)

Background colours used in the Network Applet

These are the background colours used in the Network Applet.

They have the same names as styles in the styles.css file,
but we found we needed slightly darker shades than their stylesheet equivalents.

$CFG->challengebackpale = ‘#6FCBF5’;

$CFG->issuebackpale = ‘#C6ECFE’;

$CFG->solutionbackpale = ‘#FCD7BE’;

$CFG->claimbackpale = ‘#F0B288’;

$CFG->orgbackpale = ‘#A4AED4’;

$CFG->projectbackpale = ‘#DEE2F0’;

$CFG->peoplebackpale = ‘#EAECF5’;

$CFG->evidencebackpale =’#DFC7EB’;

$CFG->resourcebackpale = ‘#E1F1C9’;

$CFG->themebackpale = ‘#FAB8DA’;

$CFG->plainbackpale = ‘#D0D0D0’;

Browser Bookmarklet Tool

$CFG->buildername = “-Your Site- EH”;

(The name of the Tool for this site. A shortening of the main site name or something like that.)

$CFG->buildernamekey = ““;

(This needs to be a unique single word key that is used before all function names in the tool to avoid clashing with any other scripts loaded in wepages.)

$CFG->builderlogo = “grey-dot.png”;

(The image file name for the icon to use in the builder toolbar – links back to parent site. Something small, 16x16ish like a png version of your Hub favicon for example.)

For initializing the org geo map

These default settings show the world, zoomed out.

$CFG->orggeomapdefaultlat = “52.034”;

(The latitude to center the Organization/Project map on)

$CFG->orggeomapdefaultlong = “-0.709”;

(The longtitude to center the Organization/Project map on)

$CFG->orggeomapdefaultzoom = “12”;

(The zoom level to start Organization/Project map on. 12 is quite zoomed out. )

For initializing the user geo map

These default settings show the world, zoomed out.

$CFG->usergeomapdefaultlat = “52.034”;

(The latitude to center the User map on)

$CFG->usergeomapdefaultlong = “-0.709”;

(The longtitude to center the User map on)

$CFG->usergeomapdefaultzoom = “12”;

(The zoom level to start the User map on. 12 is quite zoomed out.)

Action types. Please do not touch these.

$CFG->actionAdd = “add”;

$CFG->actionEdit = “edit”;

$CFG->actionDelete = “delete”;

$CFG->DEFAULT_NODE_TYPE = “Issue”;

(Leave this alone. This is still required by the delete role code! – MB:look at removing)

Default nodetype (role) group id – as found in the database

Only edit these if you have changed them in the deafult data you loaded into the Database.

$CFG->defaultRoleGroupID = “13710825192129”;

(Leave this alone.)

$CFG->systemRoleGroupID = “13710825192132”;

(Leave this alone.)

$CFG->evidenceRoleGroupID = “13710825192130”;

(Leave this alone.)

$CFG->resourceRoleGroupID = “13710825192131”;

(Leave this alone.)

More Bits and Pieces

$CFG->AUTH_TYPE_EVHUB = “evhub”;

(Leave this alone.)

$CFG->STATUS_ACTIVE = 0;

(Leave this alone. The default status of an item.)

$CFG->STATUS_SPAM = 1;

(Leave this alone. The status of an item has been reported as spam – not used at present)

Image and Icon Settings

$CFG->IMAGE_MAX_FILESIZE = 1000000;

(Change this only if you really need to, depending on your server etc.)

$CFG->IMAGE_MAX_HEIGHT = 100;

(Leave this alone.)

$CFG->IMAGE_WIDTH = 60;

(Leave this alone.)

$CFG->ICON_WIDTH = 32;

(Leave this alone.)

$CFG->DEFAULT_USER_PHOTO= ‘profile.png’;

(Leave this alone.)

$CFG->DEFAULT_GROUP_PHOTO= ‘groupprofile.png’;

(Leave this alone.)

Emailing

$CFG->send_mail = true;

(whether or not to send emails. For example if your server can’t do emailing – true/false, default ‘true’)

$CFG->EMAIL_FROM_ADDRESS = “”;

(The email address to show system emails as being sent from)

$CFG->EMAIL_FROM_NAME = $CFG->SITE_TITLE.” Admin”;

(The email from name to show system emails as being sent by. Defaults to your site title plus ‘Admin’)

$CFG->EMAIL_REPLY_TO = “kmi-edfutures@open.ac.uk”;

(The email address to show system emails should be replied to)

Proxy Settings

if the server needs a proxy to access internet, set it here.

$CFG->PROXY_HOST = “”;

$CFG->PROXY_PORT = “”;

Context Types

$CFG->GLOBAL_CONTEXT = “global”;

(Leave this alone.)

$CFG->NODE_CONTEXT = “node”;

(Leave this alone.)

$CFG->USER_CONTEXT = “user”;

(Leave this alone.)

Captcha

$CFG->CAPTCHA_ON = false;

(If you want to use Capthca set this to ‘true. (‘true’ or ‘false’))

If this is set to ‘true’ you must also complete CAPTCHA_PUBLIC and CAPTCHA_PRIVATE below.

We strongly recommend that you use Captch on your registration forms to stop automated registrations.

$CFG->CAPTCHA_PUBLIC = "<add recaptcha public key here>";

$CFG->CAPTCHA_PRIVATE = "<add recaptcha private key here>";

(If you want to use Captcha on your site, you can get the public and private keys from the Captcha website (http://www.captcha.net/))

Google

$CFG->GOOGLE_ANALYTICS_ON = false;

(If you want to use Google Analytics set this to ‘true. (‘true’ or ‘false’))

If this is set to ‘true’ you must also complete the GOOGLE_ANALYTICS_KEY below.

$CFG->GOOGLE_ANALYTICS_KEY = "";

(Google analytics key: You will need to go and get a Google analytics key for your site, if you want the analytics to work)

$CFG->GOOGLE_MAPS_KEY = "<add google map key here>";

(Google maps: You will need to go and get a Google maps key for your site)

Activity Email Alerts

$CFG->ACTIVITY_EMAIL_SENDING_ON = ‘Y’;

(If email sending should be on or off by default for new user – ‘Y’ == on / ‘N’ = off)

$CFG->ACTIVITY_EMAIL_SENDING_INTERVAL = ‘daily’;

(When to send email alerts by default for new users – ‘daily’/’weekly’/’monthly’)

MailChimp Newsletter System

$CFG->MAILCHIMP_ON = false;

(Is MailChimp Newsletter service being used on this hub? – true/false)

$CFG->MAILCHIMP_KEY = “”;

(The main API Key for the Evidence Hub to use the MailChimp service you have set up)

$CFG->MAILCHIMP_LISTID = “”;

(The MailChimp List id for the list you have setup for the Evidence Hub to subscribe users to)

$CFG->MAILCHIMP_NEWSLETTER_INFO_URL = “”;

(If you want to point to an additional page with more information about your newsletter, put the url to use here. If this is empty, the link will not be displayed in the apporpraite pages.)

Language

The current language system allows you to do two important things:

  1. Add another language: You can change the language you are using by translating all the language files into another language.
  2. 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:

  1. 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

     

  2. Copy the language files from inside the default ‘en’ language folder into you new folder.
  3. 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.
  4. 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.

Site specific text

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

  1. Locate the term you wish to replace in the language files.
  2. 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’.
  3. 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:

  1. 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.
  2. 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.

Tailoring your Evidence Hub

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.

Additional Developer Notes

RESTful API

In theory the Evidence Hub has a RESTful API. The API documentation can be found in the ‘docs’ folder in the ‘code-doc’ subfolder.

The API is currently limited to the calls that the Evidence Hub code itself needs to make.

But in the future we would like to make the API more extensive and add a
Developer Key type system to make it more secure.

Database Schema

As well as the install/db.sql file which has the sql for the database schema, there are two additional documents:

  • ‘docs/EvidenceHubDatabaseSchema.htm’, which describes the schema in an easy to read format.
  • ‘docs/EvidenceHubSchema.pdf’, which shows a graphics model of the Evidence Hub database schema and how the tables relate.

Datamodel Rules

If you are interested in the connection rules for the Datamodel that the Evidence Hub uses these are listed in ‘docs/EvidenceHubConnectionRules.pdf’

NOTE: We realize that these notes are not complete or very detailed.
We hope to supply more extensive documentation for the next release.

In the mean time, if you need more help at present, please ask your questions through our Evidence Hub Reporting System, or join our Google email group (see below for details).