GemsTracker library API
Back to top  

Object class for checking and changing tokens.

package Gems
subpackage Tracker
copyright Copyright (c) 2011 Erasmus MC
license New BSD License
since Class available since version 1.4
inherited_from \Gems_Registry_TargetAbstract

 Methods

Creates the token object

__construct(mixed $gemsTokenData) 

Parameters

$gemsTokenData

mixed

Token Id or array containing token record

Returns a callable if a method is called as a variable

__get(string $name) : Callable
Inherited

Parameters

$name

string

Returns

Callable

Set menu parameters from this token

applyToMenuSource(\Gems_Menu_ParameterSource $source) : \Gems_Tracker_Token

Parameters

$source

\Gems_Menu_ParameterSource

Returns

\Gems_Tracker_Token(continuation pattern)

Assign this token to a specific relation

assignTo(integer $respondentRelationId, integer $relationFieldId) : integer

Parameters

$respondentRelationId

integer

$relationFieldId

integer

Returns

integer1 if data changed, 0 otherwise

Retrieve a certain $key from the local cache

cacheGet(string $key, mixed $defaultValue = null) : mixed

For speeding up things the token can hold a local cache, living as long as the token object exists in memory. Sources can use this to store reusable information.

To reset the cache on an update, the source can use the cacheReset method or the setCache method to update the changed value.

Parameters

$key

string

The key used in the cache

$defaultValue

mixed

The optional default value to use when it is not present

Returns

mixed

find out if a certain key is present in the cache

cacheHas(string $key) : boolean

Parameters

$key

string

Returns

boolean

Reset the local cache for this token

cacheReset(string|null $key = null) 

You can pass in an optional $key parameter to reset just that key, otherwise all the cache will be reset

Parameters

$key

stringnull

The key to reset

Set a $key in the local cache

cacheSet(string $key, mixed $value) 

Parameters

$key

string

$value

mixed

Should be called after answering the request to allow the Target to check if all required registry values have been set correctly.

checkRegistryRequestsAnswers() : boolean

Returns

booleanFalse if required are missing.

Checks whether the survey for this token was completed and processes the result

checkTokenCompletion(integer $userId) : integer

Parameters

$userId

integer

The id of the gems user

Returns

integerself::COMPLETION_NOCHANGE || (self::COMPLETION_DATACHANGE | self::COMPLETION_EVENTCHANGE)

Creates an almost exact copy of this token at the same place in the track, only without answers and other source data

createReplacement(string $newComment, integer $userId) : string

Returns the new token id

Parameters

$newComment

string

Description of why the token was replaced

$userId

integer

The current user

Returns

stringThe new token

Get all unanswered tokens for the person answering this token

getAllUnansweredTokens($where = '') : array

Similar to @see $this->getNextUnansweredToken() Similar to @see $this->getTokenCountUnanswered()

Parameters

$where

Returns

arrayof tokendata

Returns a field from the raw answers as a date object.

getAnswerDateTime(string $fieldName) : \MUtil_Date

Parameters

$fieldName

string

Name of answer field

Returns

\MUtil_Datedate time or null

Returns a snippet name that can be used to display the answers to this token.

getAnswerSnippetNames() : string

Returns

string

A copy of the data array

getArrayCopy() : array

Returns

array

Returns the staff or respondent id of the person who last changed this token.

getChangedBy() : integer

Returns

integer

Return the comment for this token

getComment() : string

Returns

string

getCompletionTime() 

getCompletionTime() : \MUtil_Date

Returns

\MUtil_DateCompletion time as a date or null

getConsentCode() 

getConsentCode() : string

Returns

string

Returns the staff or respondent id of the person who created this token.

getCreatedBy() : integer

Returns

integer

getDateTime() 

getDateTime(string $fieldName) : \MUtil_Date

Parameters

$fieldName

string

Returns

\MUtil_Date

Returns an array of snippet names that can be used to delete this token.

getDeleteSnippetNames() : array

Returns

arrayof strings

Returns an array of snippet names that can be used to edit this token.

getEditSnippetNames() : array

Returns

arrayof strings

Get the email address of the person who needs to fill out this survey.

getEmail() : string | null

This method will return null when no address available

Returns

stringnullEmail address of the person who needs to fill out the survey or null

getMailSentDate() 

getMailSentDate() : string

Returns

stringLast mail sent date

Returns a model that can be used to save, edit, etc. the token

getModel() : \Gems_Tracker_Model_StandardTokenModel

Returns

\Gems_Tracker_Model_StandardTokenModel

Returns the next token in this track

getNextToken() : \Gems_Tracker_Token

Returns

\Gems_Tracker_Token

Returns the next unanswered token for the person answering this token

getNextUnansweredToken() : \Gems_Tracker_Token

Returns

\Gems_Tracker_Token

getOrganization() 

getOrganization() : \Gems_User_Organization

Returns

\Gems_User_Organization

getOrganizationId() 

getOrganizationId() : integer

Returns

integer

getPatientNumber() 

getPatientNumber() : string

Returns

stringThe respondents patient number

Returns the previous token that has succes in this track

getPreviousSuccessToken() : \Gems_Tracker_Token

Returns

\Gems_Tracker_Token

Returns the previous token in this track

getPreviousToken() : \Gems_Tracker_Token

Returns

\Gems_Tracker_Token

Returns the answers in simple raw array format, without value processing etc.

getRawAnswers() : array

Function may return more fields than just the answers.

Returns

arrayField => Value array

Return the \Gems_Util_ReceptionCode object

getReceptionCode() : \Gems_Util_ReceptionCode

Returns

\Gems_Util_ReceptionCodereception code

Get the relation object if any

getRelation() : \Gems_Model_RespondentRelationInstance

Returns

\Gems_Model_RespondentRelationInstance

Return the id of the relation field

getRelationFieldId() : integer

This is not the id of the relation, but the id of the trackfield that defines the relation.

Returns

integer

Get the name of the relationfield for this token

getRelationFieldName() : string

Returns

string

Return the id of the relation currently assigned to this token

getRelationId() : integer

Returns

integer

Get the respondent linked to this token

getRespondent() : \Gems_Tracker_Respondent

Returns

\Gems_Tracker_Respondent

Returns the gender as a letter code

getRespondentGender() : string

Returns

string

Returns the gender for use as part of a sentence, e.g. Dear Mr/Mrs

getRespondentGenderHello() : string

Returns

string

getRespondentId() 

getRespondentId() : integer

Returns

integer

Return the default language for the respondent

getRespondentLanguage() : string

Returns

stringTwo letter language code

getRespondentLastName() 

getRespondentLastName() : string

Returns

string

Get the name of the person answering this token

getRespondentName() : string

Could be the patient or the relation when assigned to one

Returns

string

getRespondentTrack() 

getRespondentTrack() : \Gems_Tracker_RespondentTrack

Returns

\Gems_Tracker_RespondentTrack

getRespondentTrackId() 

getRespondentTrackId() : integer

Returns

integer

The full return url for a redirect

getReturnUrl() : string

Returns

string

Get the round code for this token

getRoundCode() : string | null

Returns

stringnullNull when no round id is present or round no longer exists

getRoundDescription() 

getRoundDescription() : string

Returns

stringRound description

getRoundId() 

getRoundId() : integer

Returns

integerround id

getRoundOrder() 

getRoundOrder() : integer

Returns

integerround order

Returns a snippet name that can be used to display this token.

getShowSnippetNames() : string

Returns

string

Returns a string that tells if the token is open, completed or any other status you might like. This will not be interpreted by the tracker it is for display purposes only

getStatus() : string

Returns

stringToken status description

Return the name of the respondent

getSubjectname() : string

To be used when there is a relation and you need to know the name of the respondent

Returns

string

getSurvey() 

getSurvey() : \Gems_Tracker_Survey

Returns

\Gems_Tracker_Survey

getSurveyAnswerModel() 

getSurveyAnswerModel(string $language) : \MUtil_Model_ModelAbstract

Parameters

$language

string

(ISO) language string

Returns

\MUtil_Model_ModelAbstract

getSurveyId() 

getSurveyId() : integer

Returns

integerGems survey id

getSurveyName() 

getSurveyName() : string

Returns

stringName of the survey

Returns the number of unanswered tokens for the person answering this token, minus this token itself

getTokenCountUnanswered() : integer

Returns

integer

getTokenId() 

getTokenId() : string

Returns

stringtoken

Get the track engine that generated this token

getTrackEngine() : \Gems_Tracker_Engine_TrackEngineInterface

Returns

\Gems_Tracker_Engine_TrackEngineInterface

getTrackId() 

getTrackId() : integer

Returns

integergems_tracks track id

getTrackName() 

getTrackName() 

getUrl() 

getUrl(string $language, integer $userId) 

Parameters

$language

string

The language currently used by the user

$userId

integer

The id of the gems user

Exceptions

\Gems_Tracker_Source_SurveyNotFoundException

getValidFrom() 

getValidFrom() : \MUtil_Date

Returns

\MUtil_DateValid from as a date or null

getValidUntil() 

getValidUntil() : \MUtil_Date

Returns

\MUtil_DateValid until as a date or null

Survey dependent calculations / answer changes that must occur after a survey is completed

handleAfterCompletion() : array

Returns

arrayThe changed values

Survey dependent calculations / answer changes that must occur after a survey is completed

handleBeforeAnswering() : array

Returns

arrayThe changed values

Returns true when the answers are loaded.

hasAnswersLoaded() : boolean

There may not be any answers, but the attemt to retrieve them was made.

Returns

boolean

hasRedoCode() 

hasRedoCode() : boolean
deprecated Use the ReceptionCode->hasRedoCode

Returns

boolean

True if the reception code is a redo survey copy.

hasRedoCopyCode() : boolean
deprecated Use the ReceptionCode->hasRedoCopyCode

Returns

boolean

Is this token linked to a relation?

hasRelation() : boolean

Returns

boolean

hasResult() 

hasResult() : boolean

Returns

boolean

hasSuccesCode() 

hasSuccesCode() : boolean
deprecated Use the ReceptionCode->isSuccess

Returns

boolean

True is this token was exported to the source.

inSource() : boolean

Returns

boolean

isCompleted() 

isCompleted() : boolean

Returns

boolean

True when the valid from is set and in the past and the valid until is not set or is in the future

isCurrentlyValid() : boolean

Returns

boolean

True when the valid until is set and is in the past

isExpired() : boolean

Returns

boolean

True when the valid from is in the future or not yet set

isNotYetValid() : boolean

Returns

boolean

isValidFromManual() 

isValidFromManual() : boolean

Returns

booleanTrue when this date was set by user input

isValidUntilManual() 

isValidUntilManual() : boolean

Returns

booleanTrue when this date was set by user input

refresh() 

refresh(array $gemsData = null) : \Gems_Tracker_Token

Parameters

$gemsData

array

Optional, the data refresh with, otherwise refresh from database.

Returns

\Gems_Tracker_Token(continuation pattern)

setCompletionTime() 

setCompletionTime(string|\MUtil_Date $completionTime, integer $userId) : \Gems_Tracker_Token

Parameters

$completionTime

string\MUtil_Date

Completion time as a date or null

$userId

integer

The current user

Returns

\Gems_Tracker_Token(continuation pattern)

Sets the next token in this track

setNextToken(\Gems_Tracker_Token $token) : \Gems_Tracker_Token

Parameters

$token

\Gems_Tracker_Token

Returns

\Gems_Tracker_Token(continuation pattern)

Sets answers for this token to the values defined in the $answers array. Also handles updating the internal answercache if present

setRawAnswers(array $answers) 

Parameters

$answers

array

Set the reception code for this token and make sure the necessary cascade to the source takes place.

setReceptionCode(string $code, string $comment, integer $userId) : integer

Parameters

$code

string

The new (non-success) reception code or a \Gems_Util_ReceptionCode object

$comment

string

Comment False values leave value unchanged

$userId

integer

The current user

Returns

integer1 if the token has changed, 0 otherwise

Set a round description for the token

setRoundDescription(string $description, integer $userId) : integer

Parameters

$description

string

The new round description

$userId

integer

The current user

Returns

integer1 if data changed, 0 otherwise

setValidFrom() 

setValidFrom(mixed $validFrom, mixed $validUntil, integer $userId) : integer

Parameters

$validFrom

mixed

\Zend_Date or string

$validUntil

mixed

null, \Zend_Date or string. False values leave values unchangeds

$userId

integer

The current user

Returns

integer1 if the token has changed, 0 otherwise

Add relation to the select statement

_addRelation(\Gems_Tracker_Token_TokenSelect $select) 

Parameters

$select

\Gems_Tracker_Token_TokenSelect

Makes sure the respondent data is part of the $this->_gemsData

_ensureRespondentData() 

The maximum length of the result field

_getResultFieldLength() : integer

Returns

integer

Update the token, both in the database and in memory.

_updateToken(array $values, integer $userId) : integer

Parameters

$values

array

The values that this token should be set to

$userId

integer

The current user

Returns

integer1 if data changed, 0 otherwise

Returns the full url Gems should forward to after survey completion.

calculateReturnUrl() : string

This fix allows multiple sites with multiple url's to share a single installation.

Returns

string

Handle sending responses to the response database (if used)

toResponseDatabase(integer $userId) 

Triggered by checkTokenCompletion

Parameters

$userId

integer

The id of the gems user

 Properties

 

True when the token does exist.

$exists : boolean

Default

true
 

$translate

$translate : \Zend_Translate

Default

 

The gems token data

$_gemsData : array

Default

array()
 

Helper var for preventing infinite loops

$_loopCheck : boolean

Default

false
 

Holds the relation (if any) for this token

$_relation : array

Default

null
 

$_respondentObject

$_respondentObject : \Gems_Tracker_Respondent

Default

null
 

The id of the token

$_tokenId : string

Default

 

$db

$db : \Zend_Db_Adapter_Abstract

Default

 

$loader

$loader : \Gems_Loader

Default

 

$locale

$locale : \Zend_Locale

Default

 

Logger instance

$logger : \Gems_Log

Default

 

$project

$project : \Gems_Project_ProjectSettings

Default

 

$respTrack

$respTrack : \Gems_Tracker_RespondentTrack

Default

 

The size of the result field, calculated from meta data when null, but can be set by project specific class to fixed value

$resultFieldLength : integer

Default

null
 

Cache for storing the calculation of the length

$staticResultFieldLength : integer

Default

null
Static
 

$survey

$survey : \Gems_Tracker_Survey

Default

 

$tracker

$tracker : \Gems_Tracker

Default

 

$util

$util : \Gems_Util

Default

 

Can hold any data the source likes to store for the token

$_cache : array

Default

array()
 

$_nextToken

$_nextToken : \Gems_Tracker_Token

Default

null
 

$_previousToken

$_previousToken : \Gems_Tracker_Token

Default

null
 

The answers in raw format

$_sourceDataRaw : array

Default

 Constants

 

COMPLETION_DATACHANGE

COMPLETION_DATACHANGE = 1 
 

COMPLETION_EVENTCHANGE

COMPLETION_EVENTCHANGE = 2 
 

COMPLETION_NOCHANGE

COMPLETION_NOCHANGE = 0