Package: topic-type-gift

Source: api/packages/topic-type-gift · imported version 0.0.28. The sections after the README are extracted from the code on every docs build.

README

What does it do

This package is another TopicType. It is used to make knowledge tests. If you want to learn more about this format then see Moodle GIFT format

This package supports the following types of questions:

• multiple choice
• multiple choice with multiple right answers
• true-false
• short answers
• matching
• numerical question
• essay
• description

Each question is stored in the database as a string. In the tests you can see examples of questions of different types. See examples

The quiz can have a set maximum number of attempts for the user to solve the test and a maximum time for each attempt. If the user doesn’t complete the attempt then it is closed automatically after the time set by the variable Config::get('ulams_gift_quiz.max_quiz_time') (an administrable setting, 120 minutes when unset). A quiz’s own max_execution_time wins. The user will see the results when the attempt is finished.

The answer to an essay type question is not automatically graded. The teacher should do it.

When the quiz has randomize_order enabled, both the order of questions and the order of the answer options within each question are randomized per attempt (single/multiple choice options, and the two columns of matching questions). The shuffle is seeded with the attempt id, so the whole layout is random but stable for a given attempt (refreshing the page returns the same order), while different attempts of the same user may get a different one. When it is disabled (the default) the questions keep their configured order and choice options keep their source order (matching questions still shuffle their columns, as they always have, otherwise the pairs would line up).

Installing

• composer require ulams/topic-type-gift
• php artisan migrate
• php artisan db:seed --class="Ulams\TopicTypeGift\Database\Seeders\TopicTypeGiftPermissionSeeder"

Endpoints

The endpoints are defined in

Database

See the database schema snippet for a better understanding of how it is made.

classDiagram
direction BT
class topic_gift_attempt_answers {
   bigint topic_gift_quiz_attempt_id
   bigint topic_gift_question_id
   json answer
   varchar feedback
   double precision score
   bigint id
}
class topic_gift_questions {
   bigint topic_gift_quiz_id
   text value
   varchar type
   integer score
   integer order
   integer category_id
   bigint id
}
class topic_gift_quiz_attempts {
   timestamp started_at
   timestamp end_at
   bigint user_id
   bigint topic_gift_quiz_id
   bigint id
}
class topic_gift_quizzes {
   text value
   integer max_attempts
   integer max_execution_time
   double precision min_pass_score
   boolean counts_to_grade
   boolean randomize_order
   bigint id
}

topic_gift_attempt_answers  -->  topic_gift_questions : topic_gift_question_id.id
topic_gift_attempt_answers  -->  topic_gift_quiz_attempts : topic_gift_quiz_attempt_id.id
topic_gift_questions  -->  topic_gift_quizzes : topic_gift_quiz_id.id
topic_gift_quiz_attempts  -->  topic_gift_quizzes : topic_gift_quiz_id.id

Student flow

See diagram of how student flow works.

graph TD
A[Start] --> B[Is attempt active?]
B -- Yes --> E
B -- No --> C[Is attempt limit exceeded?]
C -- Yes --> K
C -- No --> D[Create new attempt]
D --> E[Return questions]
E -- Sequential saving --> F[End attempt]
E -- All-at-once saving --> G[Attempt closes automatically]
F --> H
G --> H[Show results]
H --> K[End]

Tests

Run ./vendor/bin/phpunit to run tests. Test details

Events

• QuizAttemptStartedEvent - This event is dispatched when the user starts a new attempt to solve the test.
• QuizAttemptFinishedEvent - This event is dispatched when the user has finished solving the test.

Listeners

This package does not listen for any events.

Permissions

Permissions are defined in seeder.

More documentation in the package

• api/packages/topic-type-gift/ADMIN.md

Topic types

• GiftQuiz

API endpoints

Method	Path	Auth	Action
POST	/api/admin/gift-questions	yes	GiftQuestionApiAdminController@create
DELETE	/api/admin/gift-questions/{id}	yes	GiftQuestionApiAdminController@delete
PUT	/api/admin/gift-questions/{id}	yes	GiftQuestionApiAdminController@update
POST	/api/admin/gift-questions/sort	yes	GiftQuestionApiAdminController@sort
GET	/api/admin/gift-questions/export	yes	GiftQuestionApiAdminController@export
POST	/api/admin/gift-questions/import	yes	GiftQuestionApiAdminController@import
GET	/api/admin/quiz-attempts	yes	QuizAttemptApiAdminController@index
GET	/api/admin/quiz-attempts/export	yes	QuizAttemptApiAdminController@export
GET	/api/admin/quiz-attempts/{id}	yes	QuizAttemptApiAdminController@read
PATCH	/api/admin/quiz-attempts/{id}/feedback	yes	QuizAttemptApiAdminController@feedback
PATCH	/api/admin/quiz-answers/{id}	yes	AttemptAnswerApiAdminController@update
GET	/api/admin/gift-quizes	yes	GiftQuizApiAdminController@index
GET	/api/admin/gift-quizes/{id}	yes	GiftQuizApiAdminController@read
PUT	/api/admin/gift-quizes/{id}	yes	GiftQuizApiAdminController@update
GET	/api/quiz-attempts	yes	QuizAttemptApiController@index
POST	/api/quiz-attempts	yes	QuizAttemptApiController@getActiveAttempt
GET	/api/quiz-attempts/{id}	yes	QuizAttemptApiController@read
POST	/api/quiz-attempts/{id}/end	yes	QuizAttemptApiController@markAsEnded
POST	/api/quiz-answers	yes	AttemptAnswerApiController@saveAnswer
POST	/api/quiz-answers/all	yes	AttemptAnswerApiController@saveAllAnswers

Permissions

Permission	Seeded for roles	Constant
quiz-attempt_create-own	admin, student	TopicTypeGiftPermissionEnum::CREATE_OWN_QUIZ_ATTEMPT
quiz-attempt_list-own	admin, student	TopicTypeGiftPermissionEnum::LIST_OWN_QUIZ_ATTEMPT
quiz-attempt_read-own	admin, student	TopicTypeGiftPermissionEnum::READ_OWN_QUIZ_ATTEMPT
quiz-attempt_list	admin	TopicTypeGiftPermissionEnum::LIST_QUIZ_ATTEMPT
quiz-attempt_read	admin	TopicTypeGiftPermissionEnum::READ_QUIZ_ATTEMPT
quiz-attempt_update	admin	TopicTypeGiftPermissionEnum::UPDATE_QUIZ_ATTEMPT
quiz-attempt_list-self	admin, tutor	TopicTypeGiftPermissionEnum::LIST_SELF_QUIZ_ATTEMPT
gift-quiz_read	admin, tutor	TopicTypeGiftPermissionEnum::READ_GIFT_QUIZ
gift-quiz_update	admin, tutor	TopicTypeGiftPermissionEnum::UPDATE_GIFT_QUIZ
gift-quiz-question_create	admin	TopicTypeGiftPermissionEnum::CREATE_GIFT_QUIZ_QUESTION
gift-quiz-question_update	admin, tutor	TopicTypeGiftPermissionEnum::UPDATE_GIFT_QUIZ_QUESTION
gift-quiz-question_delete	admin, tutor	TopicTypeGiftPermissionEnum::DELETE_GIFT_QUIZ_QUESTION
gift-quiz-question_export	admin	TopicTypeGiftPermissionEnum::EXPORT_GIFT_QUIZ_QUESTION
gift-quiz-question_import	admin	TopicTypeGiftPermissionEnum::IMPORT_GIFT_QUIZ_QUESTION

Settings

Registered with AdministrableConfig::registerConfig (editable in the admin panel under Configuration → Settings).

Key	Rules	Public	Read-only
ulams_gift_quiz.max_quiz_time	required, integer, min:1	no

Events

Event	Description	Notification templates
QuizAttemptFinishedEvent
QuizAttemptJournalGradeReadyEvent	Emitted when a fully graded attempt of a quiz flagged counts_to_grade is ready to be reflected in the journal — on finish for auto-scored quizzes, or once a lecturer grades the last open question. Re-grading a graded attempt emits it again. Consumed (in pcg-grades) to upsert the partial grade for the journal.
QuizAttemptStartedEvent
QuizGradabilityChangedEvent	Emitted whenever a quiz’s counts_to_grade flag flips, in either direction. Consumed (in pcg-grades) to regenerate or delete the journal partial grade(s) derived from this quiz.

Artisan commands

Command	Description	Signature
gift:snapshot-max-scores	Freeze the maximum score of past quiz attempts (ADR 0033)	gift:snapshot-max-scores

Scheduled jobs

None.

Environment variables read

None.