PhenoTips » Administration Guide » Integration

Integration

The easiest way of integrating PhenoTips into another web-based system is through an embedded HTML iframe.

Stripping the PhenoTips skin

The default skin of PhenoTips is not well suited for embedding into another application, since it comes with its own header, footer, and extra padding. However, there already is a special skin useful for embedding. To activate it:

  • Open PhenoTips in a browser
  • Log in with an administrative account
  • Click on the Administration link displayed in the top left corner
  • Select the Look & Feel / Presentation entry from the left menu
  • Type PhenoTips.EmbeddableSkin in the Skin field, click Save

You should now see only the essential elements of the page. Unfortunately, this doesn't include links back to the homepage, or to the administration. Fortunately, you can configure the skin only for a specific user, too, though the UI for doing that is not easily discoverable:

  • Open http://localhost:8080/phenotips/bin/edit/XWiki/Admin?editor=object&classname=XWiki.XWikiUsers&object=0&property=skin - using the right protocol, host name, optional port, optional application name, and the right username
  • Type PhenoTips.Skin in the skin field, click one of the Save buttons

Displaying a patient record

Display http[s]:<hostname>[:<port>]/<appname>/bin/PhenoTips/OpenPatientRecord?[e]id=<identifier>[&mode=<mode>][&create=true] in an iframe.

Where:

hostname
the actual hostname where PhenoTips is reachable
port
the port, if needed
appname
the name of the webapp (missing in the standalone zip)
id
the PhenoTips identifier of an existing patient record, for example P0000001
eid
the external identifier that users can set for a patient; either one already set in an existing patient record, or a new identifier to set for a new record when create=true
(only one of id or eid is required in the URL)
mode
view or edit; optional, default is view
create
use to force the creation of a new record when passing an eid and no record was found with that identifier; optional, by default an error message is returned when the requested patient is not found

For example:

http://localhost:8080/bin/PhenoTips/OpenPatientRecord?eid=Patient15&mode=edit&create=true

Passing data from an external application into the PhenoTips record

When opening the patient record, it is possible to pass in values for the fields in PhenoTips.PatientClass. Send in the request, either as GET parameters in the URL, or as POST parameters, key-value pairs where the key is the name of the PatientClass property, such as date_of_birth, last_name, global_mode_of_inheritance, indication_for_referral, and the value is the value you want to assign, with the following rules:

  • BooleanClass fields accept 0 for false/no, 1 for true/yes, and -1 for unsetting the value: miscarriages=1&consanguinity=0
  • NumberClass fields accept normal arabic numerals, such as 42 or 123.45, always using the dot as the decimal separator: gestation=37
  • DateClass fields accept dates in the ISO 8601 format: date_of_birth=1984-06-13
  • For fields that accept a list of values, such as phenotype or maternal_ethnicity, send multiple key-value pairs with the same key: maternal_ethnicity=Irish&maternal_ethnicity=Italian
  • Strings should be sent using the UTF-8 character encoding, URL-encoded if sent in the URL: first_name=Herg%C3%A9
  • StringClass fields, and individual values in a list field, must be at most 255 characters long
  • TextAreaClass fields must be at most 60,000 characters long

For example:

http://localhost:8080/bin/PhenoTips/OpenPatientRecord?eid=Patient15&mode=edit&create=true&gender=M&first_name=John&last_name=Doe&date_of_birth=1984-06-13&maternal_ethnicity=Irish&maternal_ethnicity=Italian&paternal_ethnicity=Irish&consanguinity=1

Getting a patient's data

Call http[s]:<hostname>[:<port>]/<appname>/bin/get/PhenoTips/ExportPatient?[e]id=<identifier> from your application and parse the returned JSON.

For example:

http://localhost:8080/bin/get/PhenoTips/ExportPatient?eid=Patient15

Getting a pedigree image

Starting with version 1.0, PhenoTips provides a service allowing users to export pedigree images in SVG or PNG format.

Usage

Call http[s]:<hostname>[:<port>]/<appname>/bin/get/PhenoTips/PedigreeImageService?[e]id=<identifier>[&format=raster] from your application.

If the format parameter is missing or is different than raster, the service returns the vectorial image in SVG format, otherwise it returns a PNG.

This feature is not currently exposed in the user interface, but adding action buttons to export the pedigree as an image is planned for one of our future releases.

Changing the skin to better emulate the wrapping application

The recommended way of styling PhenoTips is through a custom Color Theme.

  • Open PhenoTips in a browser
  • Log in with an administrative account
  • Click on the Administration link displayed in the top left corner
  • Select the Look & Feel / Presentation entry from the left menu
  • Select one of the existing Color Themes, or click on Manage color themes to create a new one
  • From the color theme management interface, you can create a new color theme by typing a name for it and clicking the Create new theme button
  • The colors for the different elements of the page can now be modified using an in-place editor, though this doesn't cover other aspects of the skin, such as fonts, paddings and margins, shadows and gradients...
  • To add extra CSS, while on your custom color theme page, hover over the Edit menu and select the Objects option
  • From the New object drop down, select XWiki / StyleSheetExtension, click Add
  • Type your custom CSS code in the Code text area, save when done
    • While still developing the CSS rules, change the Caching policy to forbid so that you don't save the old version of the code in the browser's cache; don't forget to change it back to long when the site is ready for production use

If you do not see the drop down list under the Edit menu, then the currently logged in user is marked as a Simple user, and only Advanced users can see that menu. To change your user type:

  • Click on your username in the top right corner
  • Select Preferences from the left side menu
  • Click the pencil icon on the right of Display Preferences
  • From the Editor Preferences / User type drop down, select Advanced
  • Click one of the Save buttons

You should now see the edit options.