Concerto R package

general concept

Since Concerto v4 has a code auto-complete function and an R function documentation (available for any R package installed on your system) available for users writing code, we decided to include Concerto built-in functions also as an R package.

Concerto session variables list

This list consist of chosen Concerto session internal variables. The list should NOT be modified by test logic. However there are some variables which can prove helpful for user and can be read.

• concerto$db$connection - MySQL database connection object
• concerto$db$name - current session main MySQL database name
• concerto$mediaPath - path to private media directory (use to save media files that should be accessible from within browser)
• concerto$mediaURL - URL to private media directory (use to access media files saved earlier in browser)
• concerto$sessionID - test session id
• concerto$testID - parent test id
• concerto$userIP - IP of test participant
• concerto$workspaceID - parent test workspace id
• concerto$workspacePrefix - workspace prefixes used in system

Please keep in mind that when the Concerto session is initialized, your working directory is set to your workspace private directory. You can check what is the full path to directory by typing:

getwd()

concerto.qti.get

Retrieves specific QTI object info.

arguments

• qtiID - ID or name of the QTI you want to get
• workspaceID - if you want to get a QTI from a different workspace than where the test is located, specify the relevant workspace ID here.

returns

List with QTI object properties:

• id - QTI object ID
• name - QTI object name
• ini_r_code - QTI object R code evaluated at QTI initialization
• response_proc_r_code - QTI object R code evaluated at QTI response processing

example

qti <- concerto.qti.get(1)

qti <- concerto.qti.get("second_qti")

concerto.qti.initialize

Initializes QTI object.

arguments

• qtiID - ID or name of the QTI object you want to initialize
• params - named list with parameters you want to pass to the QTI initialization
• workspaceID - if you want to use a QTI from a different workspace than where the test is located, specify the relevant workspace ID here

returns

Named list with QTI session state and:

• QTI_HTML - HTML generated by QTI logic which can be inserted into a template

example

ini <- concerto.qti.initialize(1)

ini <- concerto.qti.initialize("first_qti")

concerto.qti.responseProcessing

QTI response processing.

arguments

• qtID - QTI object id or name
• ini - result of QTI initialization function
• userResponse - test participant response (result of show template function)
• workspaceID - if you want to use a QTI from a different workspace than where the test is located, specify the relevant workspace ID here

return

Named list with elements declared in QTI XML.

example

qti_init <- concerto.qti.initialize(1)

response <- concerto.template.show(1, params = list(qti = qti_init$QTI_HTML))

qti_proc <- concerto.qti.responseProcessing(1, qti_init, response)

concerto.table.fillSQL

Fills SQL code with given parameters.

arguments

• sql - SQL code
• params - named list with parameters

return

SQL code with inserted parameters.

example

id <- 123

sql <- "SELECT * FROM `db`.`table` WHERE `id`={{id_value}}"

sql <- concerto.table.fillSQL(sql, list(id_value = id))

concerto.table.get

Retrieves specific table object info.

arguments

• tableID - ID or name of the table you want to get
• workspaceID - if you want to get a table from a different workspace than where the test is located, specify the relevant workspace ID here.

returns

List with table object properties:

• id - table object ID
• name - table name

example

table <- concerto.table.get(1)

table <- concerto.table.get("second_table")

concerto.table.query

Perform query on Concerto database.

arguments

• sql - SQL query to perform
• params - named list with parameters

return

Returns result set.

example

sql <- "SELECT * FROM `itam_bank`"

items <- concerto.table.query(sql)

concerto.template.fillHTML

Fills HTML code with given parameters.

arguments

• html - HTML code
• params - named list with parameters

return

HTML code with inserted parameters.

example

index <- 12

html <- "<input type='text' name='inp{{index}}' />"

html <- concerto.template.fillHTML(html , list(index = index))

concerto.template.get

Retrieves specific template object info.

arguments

• templateID - ID or name of the template you want to get
• workspaceID - if you want to get a template from a different workspace than where the test is located, specify the relevant workspace ID here.

returns

List with template object properties:

• id - template object ID
• name - template object name
• head - head tag of HTML template
• HTML - template HTML

example

template <- concerto.template.get(1)

template <- concerto.template.get("second_template")

concerto.template.loader

Sets a template that will be shown when the proper templates are loaded.

arguments

• templateID - ID or name of the template you want to show
• HTML - HTML entered directly
• head - head tag entered directly
• params - named list with parameters you want to pass to the template
• workspaceID - if you want to use a template from a different workspace than where the test is located, specify the relevant workspace ID here
• effectShow - template show effect entered directly
• effectHide - template hide effect entered directly
• effectShowOptions - template show effect options entered directly
• effectHideOptions - template hide effect options entered directly

example

response1 <- concerto.template.loader(1)

response2 <- concerto.template.loader(HTML="<div align="center">loading ... please wait ...</div>")

concerto.template.show

The most important of all functions in the package. It informs your test logic that it's time to show a specific HTML template to test participants.

arguments

• templateID - ID or name of the template you want to show
• HTML - HTML entered directly
• head - head tag entered directly
• params - named list with parameters you want to pass to the template
• timeLimit - number of seconds after which template will be auto submitted (0 for no limit)
• finalize - set to TRUE if there is nothing more to do for your test logic after this template
• workspaceID - if you want to use a template from a different workspace than where the test is located, specify the relevant workspace ID here
• effectShow - template show effect entered directly
• effectHide - template hide effect entered directly
• effectShowOptions - template show effect options entered directly
• effectHideOptions - template hide effect options entered directly

returns

Returns named list with the variable gathered from the template and:

• LAST_PRESSED_BUTTON_NAME - name of the button that submitted the template
• OUT_OF_TIME - 1 if the set time limit has been reached, 0 if not
• TIME_TAKEN - how much time has it taken user to submit the template

example

response <- concerto.template.show(1)

response <- concerto.template.show("first_template")

response <- concerto.template.show(HTML="Please click the button: <button>click me</button>")

concerto.test.get

Retrieves specific test object info.

arguments

• testID - ID or name of the test you want to get
• workspaceID - if you want to get a test from a different workspace than where the test is located, specify the relevant workspace ID here.

returns

List with test object properties:

• id - test object ID
• name - test object name
• code - test logic code

example

test <- concerto.test.get(1)

test <- concerto.test.get("second_test")

concerto.test.run

Runs Concerto test.

arguments

• testID - test ID or name
• params - named list of parameters you want to pass to the test logic
• workspaceID - Concerto workspace ID where the test object is located

return

Named list with the test specific return variables.

example

result <- concerto.test.run(1)

concerto.workspace.get

Gets workspace name.

arguments

• workspaceID - Concerto workspace ID

return

Name of the workspace.

example

dbName <- concerto.workspace.get(1)