Participant

Extends \LSActiveRecord

This is the model class for table "{{participants}}".

The followings are the available columns in table '{{participants}}':

package

Default

Methods

addSurveyFilter

addSurveyFilter( $conditions) 

Arguments

$conditions

attributeLabels

attributeLabels() : array

Response

array

customized attribute labels (name=>label)

Lists the behaviors of this model

behaviors() : array
inherited

Below is a list of all behaviors we register:

see \CTimestampBehavior \PluginEventBehavior

Response

array

Check for column duplicates from CPDB to token attributes Throws error message if an attribute already exists; otherwise false.

checkColumnDuplicates(integer $surveyId, array<mixed,string> $newAttributes) : boolean
Throws
\CPDBException

with error message

Arguments

$surveyId

integer

$newAttributes

array<mixed,string>

Array of CPDB attributes ids like ['42', '32', ...]

Response

boolean

The purpose of this function is to check for duplicate in participants

checkforDuplicate(string $fields, string $output = "bool") : string

Arguments

$fields

string

$output

string

Response

string

Copies central attributes/participants to an individual survey survey participants table

copyCPDBAttributesToTokens(integer $surveyId, string $participantIds, array $mappedAttributes, array $newAttributes, array $options) : array

Arguments

$surveyId

integer

The survey id

$participantIds

string

Array containing the participant ids of the participants we are adding

$mappedAttributes

array

An array containing a list of /mapped attributes in the form of "token_field_name" => "participant_attribute_id"

$newAttributes

array

An array containing new attributes to create in the tokens table

$options

array

Array with following options: overwriteauto - If true, overwrite automatically mapped data overwriteman - If true, overwrite manually mapped data overwritest - If true, overwrite standard fields (ie: names, email, participant_id, token) createautomap - If true, rename the fieldnames of automapped attributes so that in future they are automatically mapped

Response

array

Copies token participants to the central participants table, and also copies token attribute values where applicable. It checks for matching entries using firstname/lastname/email combination.

copyToCentral(integer $surveyid, array $aAttributesToBeCreated, array $aMapped, boolean $overwriteauto = false, boolean $overwriteman = false, boolean $createautomap = true) : array

TODO: Most of this belongs in the participantsaction.php controller file, not here in the model file. Portions of this should be moved out at some stage.

Arguments

$surveyid

integer

The id of the survey, used to find the appropriate tokens table

$aAttributesToBeCreated

array

An array containing the names of token attributes that have to be created in the cpdb

$aMapped

array

An array containing the names of token attributes that are to be mapped to an existing cpdb attribute

$overwriteauto

boolean

If true, overwrites existing automatically mapped attribute values

$overwriteman

boolean

If true, overwrites manually mapped attribute values (where token fieldname=attribute_n)

$createautomap

boolean

If true, updates tokendescription field with new mapping

Response

array

An array contaning list of successful and list of failed ids

Create new "fields"? in which table?

createColumnsInTokenTable(integer $surveyId, array $newAttributes) : array

Arguments

$surveyId

integer

$newAttributes

array

Response

array

[addedAttributes, addedAttributeIds]

deleteAllByAttributes

deleteAllByAttributes(array $attributes, string $condition = '', array $params = array()) : integer
inherited
todo

This should also be moved to the behavior at some point. This method overrides the parent in order to raise PluginEvents for Bulk delete operations.

Filter Criteria are wrapped into a CDBCriteria instance so we have a single instance responsible for holding the filter criteria to be passed to the PluginEvent, this also enables us to pass the fully configured CDBCriteria instead of the original Parameters.

See {@link find()} for detailed explanation about $condition and $params.

Arguments

$attributes

array

list of attribute values (indexed by attribute names) that the active records should match. An attribute value can be an array which will be used to generate an IN condition.

$condition

string

query condition or criteria.

$params

array

parameters to be bound to an SQL statement.

Response

integer

number of rows affected by the execution.

This function deletes the participant from the participants table, references in the survey_links table (but not in matching tokens tables) and then all the participants attributes.

deleteParticipants(string $rows, boolean $bFilter = true) : integer

Arguments

$rows

string

Participants ID separated by comma

$bFilter

boolean

Response

integer

number of deleted participants

Deletes CPDB participants identified by their participant ID from survey participants tables

deleteParticipantToken(string $sParticipantsIDs) : integer

Arguments

$sParticipantsIDs

string

Response

integer

Number of deleted participants

This function deletes the participant from the participants table, the participant from any tokens table they're in (using the survey_links table to find them), all responses in surveys they've been linked to, and then all the participants attributes.

deleteParticipantTokenAnswer(string $sParticipantsIDs) : integer

Arguments

$sParticipantsIDs

string

Response

integer

Number of deleted participants

Filter an array of participants IDs according to permissions of the person being logged in

filterParticipantIDs(mixed $aParticipantIDs) : array<mixed,integer>

Arguments

$aParticipantIDs

mixed

Response

array<mixed,integer>

Finds all active records satisfying the specified condition but returns them as array

findAllAsArray(\CDbCriteria $condition = '', array $params = array()) : array
inherited

See \find() for detailed explanation about $condition and $params.

Arguments

$condition

\CDbCriteria

query condition or criteria.

$params

array

parameters to be bound to an SQL statement.

Response

array

list of active records satisfying the specified condition. An empty array is returned if none is found.

Takes result from model->getErrors() and creates a long string of all messages.

flattenErrorMessages(array $errors) : string

Arguments

$errors

array

Response

string

Function for generation of unique id

gen_uuid() : string
static

Response

string

getAllExtraAttributes

getAllExtraAttributes() : array

Response

array

getAllUsedLanguagesWithRealName

getAllUsedLanguagesWithRealName() 

getBlacklistSwitchbutton

getBlacklistSwitchbutton() : string

Response

string

HTML

getButtons

getButtons() : string

Response

string

getCheckbox

getCheckbox() : string

Response

string

html

getColumns

getColumns() : array

Response

array

getCountActiveSurveys

getCountActiveSurveys() : integer|string

Response

integer|string

'created' field formatted; empty string if no timestamp in database

getCreatedFormatted() : string

Response

string

Return the max value for a field

getMaxId(string $field = null, boolean $forceRefresh = false) : false|integer
inherited

This is a convenience method, that uses the primary key of the model to retrieve the highest value.

Throws
\Exception

Arguments

$field

string

The field that contains the Id, when null primary key is used if it is a single field

$forceRefresh

boolean

Don't use value from static cache but always requery the database

Response

false|integer

Return the min value for a field

getMinId(string $field = null, boolean $forceRefresh = false) : false|integer
inherited

This is a convenience method, that uses the primary key of the model to retrieve the highest value.

Throws
\Exception

Arguments

$field

string

The field that contains the Id, when null primary key is used if it is a single field

$forceRefresh

boolean

Don't use value from static cache but always requery the database

Response

false|integer

Get options for a drop-down attribute

getOptionsForAttribute(string $attribute_id) : array

Arguments

$attribute_id

string

Response

array

getOwnersList

getOwnersList(integer $selected) : string

Arguments

$selected

integer

Owner id

Response

string

HTML

getParticipantAttribute

getParticipantAttribute(string $attributeTextId, mixed $attribute_id = false) : string

Arguments

$attributeTextId

string

E.g. ea_145

$attribute_id

mixed

Response

string

getParticipants

getParticipants(integer $page, integer $limit, array $attid, string|null $order = null, \CDbCriteria $search = null, integer $userid = null) : array
Throws
\CException

Arguments

$page

integer

$limit

integer

$attid

array

$order

string|null

$search

\CDbCriteria

$userid

integer

Response

array

Duplicated from getparticipants, only to have a count

getParticipantsCount(array $attid, \CDbCriteria $search = null, integer $userid = null) : integer

Arguments

$attid

array

$search

\CDbCriteria

$userid

integer

Response

integer

Get the number of participants, no restrictions

getParticipantsCountWithoutLimit() : string

Response

string

This function is responsible for showing all the participant's shared by a particular user based on the user id

getParticipantShared(integer $userid) : array

Arguments

$userid

integer

Response

array

This function is responsible for showing all the participant's shared to the superadmin

getParticipantSharedAll() : array

Response

array

This function returns a list of participants who are either owned or shared with a specific user

getParticipantsOwner(integer $userid) : array<mixed,\Participant>

Arguments

$userid

integer

The ID of the user that we are listing participants for

Response

array<mixed,\Participant>

objects containing all the users

getParticipantsOwnerCount

getParticipantsOwnerCount(integer $userid) : integer

Arguments

$userid

integer

Response

integer

Function builds a select query for searches through participants using the $condition field passed which is in the format "firstfield||sqloperator||value||booleanoperator||secondfield||sqloperator||value||booleanoperator||etc||etc||etc" for example: "firstname||equal||Jason||and||lastname||equal||Cleeland" will produce SQL along the lines of "WHERE firstname = 'Jason' AND lastname=='Cleeland'"

getParticipantsSearchMultiple(array $condition, integer $page, integer $limit) : array

Arguments

$condition

array

an array containing the search string exploded using || so that "firstname||equal||jason" is $condition(1=>'firstname', 2=>'equal', 3=>'jason')

$page

integer

Which page number to display

$limit

integer

The limit/number of reords to return

Response

array

$output

Function builds a select query for searches through participants using the $condition field passed which is in the format "firstfield||sqloperator||value||booleanoperator||secondfield||sqloperator||value||booleanoperator||etc||etc||etc" for example: "firstname||equal||Jason||and||lastname||equal||Cleeland" will produce SQL along the lines of "WHERE firstname = 'Jason' AND lastname=='Cleeland'"

getParticipantsSearchMultipleCondition(array $condition) : \CDbCriteria

Arguments

$condition

array

an array containing the search string exploded using || so that "firstname||equal||jason" is $condition(1=>'firstname', 2=>'equal', 3=>'jason')

Response

\CDbCriteria

$output

getParticipantsSelectCommand

getParticipantsSelectCommand(boolean $count = false, array $attid, \CDbCriteria $search = null, integer $userid = null, integer $page = null, integer $limit = null, string|null $order = null) : \CDbCommand

Arguments

$count

boolean

$attid

array

$search

\CDbCriteria

$userid

integer

$page

integer

$limit

integer

$order

string|null

Response

\CDbCommand

This function combines the shared participant and the central participant table and searches for any reference of owner id in the combined record of the two tables

getParticipantsSharedCount(integer $userid) : integer

Arguments

$userid

integer

The id of the owner

Response

integer

The number of participants owned by $userid who are shared

getParticipantsWithoutLimit

getParticipantsWithoutLimit() : array<mixed,\Participant>

Response

array<mixed,\Participant>

getSurveyCount

getSurveyCount( $participant_id) : integer

Arguments

$participant_id

Response

integer

Get column names from token attributes for a survey.

getTokenAttributes(integer $surveyId) : array

A token attribute has id (auto increment), attribute field (always "attribte_" + number), and field description (e.g. "my attribute" or "gender")

Arguments

$surveyId

integer

Response

array

E.g. [11 => 'attribute_36', ...]

This function is responsible for adding the participant to the database

insertParticipant(array $aData) : string|\Participant

Arguments

$aData

array

Participant data

Response

string|\Participant

Error message on failure, participant object on success

insertParticipantCSV

insertParticipantCSV(array $data) : void

Arguments

$data

array

Returns true if participant_id has ownership or shared rights over this participant false if not

is_owner(string $participant_id) : boolean

Arguments

$participant_id

string

Response

boolean

Returns true if user is either owner of this participant or superadmin Used to decide is user can change owner of participant

isOwnerOrSuperAdmin() : boolean

Response

boolean

model

model( $class = __CLASS__) : \Participant
static
inheritdoc

Arguments

$class

Response

\Participant

Returns the primary key of this table

primaryKey() : string
access

public

Response

string

Modified version that default to do the same as the original, but allows via a third parameter to retrieve the result as array instead of active records. This solves a joining problem. Usage via findAllAsArray method

query(\CDbCriteria $criteria, boolean $all = false, boolean $asAR = true) : mixed
inherited

Performs the actual DB query and populates the AR objects with the query result. This method is mainly internally used by other AR query methods.

since 1.1.7

Arguments

$criteria

\CDbCriteria

the query criteria

$all

boolean

whether to return all data

$asAR

boolean

Response

mixed

the AR objects populated with the query result

relations

relations() 
inheritdoc

rules

rules() 
inheritdoc

tableName

tableName() 
inheritdoc

Updates or creates a field in the survey participants table with a value from the participant attributes table

updateAttributeValueToken(integer $surveyId, integer $participantId, integer $participantAttributeId, integer $tokenFieldname) : boolean|null

Arguments

$surveyId

integer

Survey ID number

$participantId

integer

unique key for the participant

$participantAttributeId

integer

the unique key for the participant_attribute table

$tokenFieldname

integer

fieldname in the survey participants table

Response

boolean|null

true/false

This function updates the data edited in the view

updateRow(array $data) : void

Arguments

$data

array

Updates a field in the survey participants table with a value from the participant attributes table

updateTokenAttributeValue(integer $surveyId, string $participantId, integer $participantAttributeId, integer $tokenFieldname) : boolean

Arguments

$surveyId

integer

Survey ID number

$participantId

string

unique key for the participant

$participantAttributeId

integer

the unique key for the participant_attribute table

$tokenFieldname

integer

fieldname in the survey participants table

Response

boolean

true/false

Update stuff? If automapping is enabled then update the token field properties with the mapped CPDB field ID TODO: What is this?

updateTokenFieldProperties(integer $surveyId, array $mappedAttributes) : void

Arguments

$surveyId

integer

$mappedAttributes

array

Returns true if logged in user has edit rights to this participant

userHasPermissionToEdit() : boolean

Response

boolean

Write participants as tokens or something

writeParticipantsToTokenTable(integer $surveyId, array $participantIds, array $mappedAttributes, array $newAttributes, array $addedAttributes, array $addedAttributeIds, array $options) : array<mixed,integer>
Throws
\Exception

Arguments

$surveyId

integer

$participantIds

array

$mappedAttributes

array

$newAttributes

array

$addedAttributes

array

?? Result from createColumnsInTokenTable

$addedAttributeIds

array

?? Result from createColumnsInTokenTable

$options

array

As in calling function

Response

array<mixed,integer>

(success, duplicate, blacklistSkipped)

Properties

extraCondition

extraCondition : 

Type(s)

countActiveSurveys

countActiveSurveys : 

Type(s)

id

id : 

Type(s)

participant_id

participant_id : string

Primary Key

Type(s)

string

firstname

firstname : string

Type(s)

string

lastname

lastname : string

Type(s)

string

email

email : string

Type(s)

string

language

language : string

Type(s)

string

blacklisted

blacklisted : integer

Type(s)

integer

owner_uid

owner_uid : integer

Type(s)

integer

created_by

created_by : integer

Type(s)

integer

created

created : string

Date-time of creation

Type(s)

string

modified

modified : string

Date-time of modification

Type(s)

string

owner

owner : \User

Type(s)

\User

participantAttributes

participantAttributes : array<mixed,\ParticipantAttribute>

Type(s)

array<mixed,\ParticipantAttribute>

shares

shares : array<mixed,\ParticipantShare>

Type(s)

array<mixed,\ParticipantShare>

buttons

buttons : string

Type(s)

string

checkbox

checkbox : string

Type(s)

string

allExtraAttributes

allExtraAttributes : array

Type(s)

array

countActiveSurveys

countActiveSurveys : integer|string

Type(s)

integer|string

blacklistSwitchButton

blacklistSwitchButton : string

Type(s)

string

columns

columns : array

Type(s)

array

ownersList

ownersList : string

Type(s)

string