yl_survey

Purpose

This mod allows the creation, delivery and answering of surveys

Download

Get it from https://gitea.your-land.de/your-land/yl_survey

Installation

1. Copy the "yl_survey" folder to your mod directory.
2. Make sure the dependencies are satisfied, if any.
3. Enable the mod in your world.mt file.

Configuration

yl_survey.debug = false

Set to true to enable debug mode

yl_survey.save_path

Set this to where in the worldfolder you want the JSON files stored.

yl_survey.surveyedit_privs
yl_survey.surveyanswer_privs
yl_survey.surveyevaluate_privs

Set those to the list of privs you want to allow the execution of the corresponding commands

Usage

This mod targets servers, but should work in singleplayer, too.

Chatcommands

TODO - IF we can do it.

Modmakers

See the datastructure

A s_id (survey_id) is a UUID, a q_id is a positive integer. An owner is the person who is responsible for one survey, a respondent is a person who takes part in the survey and answers its questions. The {survey} table refers to the whole data structure of a survey, {question} refers to the data structure of a single question including its answers.

Use the following public functions to get, set, list, remove and evaluate surveys

yl_survey.get_record(s_id)

Returns a table {survey} with the values of this UUID or nil, if it does not exist

yl_survey.create_survey(owner, title, description, allow_names, allow_anonymous, allow_changes, timestamp_start, timestamp_end)

Returns true, s_id if successful, false, "errormessage" if not.

Creates a survey owned by owner. title, description are strings, allow_names, allow_anonymous, allow_changes are booleans, timestamp_start and timestamp_end are utc timestamps.

• owner: string, required. This is the person who is responsible for this survey
• title: string, optional, defaults to "". This is displayed in every frame of the survey
• description: string, optional, defaults to "". This is displayed on the front page of the survey
• allow_names: boolean, optional, default true. If true, respondents can choose whether to answer with their name recorded. If false, respondents cannot answer with their name recorded.
• allow_anonymous: boolean, optional, default true. If true, respondents can choose whether to answer anonymously. If false, respondents cannot answer anonymously.
• allow_changes: boolean, optional, default true. If true, the survey may be altered. If false, the survey and its questions are fixed.
• allow_reconsider : boolean, optional, default false. If true, the respondent may change his answers anytime before the deadline. If false, the answers are fixed once answered.
• timestamp_start: positive integer, optional, default nil. Timestamp beyond which the survey can be answered.
• timestamp_end: positive integer, optional, default nil. Timestamp beyond which the survey can no longer be answered.

If both allow_names and allow_anonymous are false, then noone can answer this survey. To allow_changes and still allow_anonymous, the playername is hashed. This is no 100% protection against finding out who answered!

yl_survey.edit_survey(s_id, owner, title, description, allow_names, allow_anonymous, allow_changes, timestamp_start, timestamp_end, delete_responses)

Returns true, s_id, amount_deleted_records if successful, false, "errormessage" if not.

Changes the properties of the survey s_id to the values given. delete_responses is boolean, optional and defaults to false, but if true it deletes all prior responses of the survey. See create_survey for the other values.

yl_survey.remove_record(s_id)

Returns true, {survey} if the survey was successfully removed, false, "errormessage" otherwise.

yl_survey.get_data()

Returns true, {{survey1}, {survey2}, ...} if one or more surveys were found, false, {} if none were found.

yl_survey.evaluate(s_id)

??? How do we evaluate that stuff ???

yl_survey.create_question(s_id, question, category, sort, {options}, {answers}, enabled)

Returns true, q_id if successful, false, "errormessage" if not.

Adds a question to the survey identified by s_id.

• s_id: string, required. This is the survey/UUID the question is added to.
• question: string, required. This is the question text the survey asks its respondents.
• category: string, optional, default empty. Use it for additonal explanation, category, help. Is displayed near the question. May be nil or empty.
• sort: integer, optional, defaults to the next free number. Use this to order your questions.
• {options}: table of options with defaults {"has_freetext" : true, "min_responses" : 0, "max_responses" : 0}, optional. max_responses : 0 means there is no limit on the maximum number of answers. Example: "singlechoice question without freetext": {"has_freetext" : false, "min_responses" : 0, "max_responses" : 1}
• {answers}: table of strings, optional. Holds the answers to a singlechoice or multiplechoice question.
• enabled: boolean, optional, defaults to true. If true, the question is delivered to a participant. If false, the question is hidden.

yl_survey.edit_question(s_id, q_id, question, sort, category, {options}, {answers}, enabled, delete_responses)

Returns true, q_id if successful, false, "errormessage" if not.

Changes in the survey s_id the properties of the question q_id to the values given. delete_responses is boolean, optional and defaults to false, but if true it deletes all prior responses to this particular question. See create_question for the other values.

yl_survey.remove_question(s_id, q_id, delete_responses)

Returns true, {question} if the question was successfully removed, false, "errormessage" otherwise. delete_responses is boolean, optional and defaults to false, but if true it deletes all prior responses to this particular question.

yl_survey.list_questions(s_id, include_responses)

Returns true, {{question1}, {question2}, ... } if one or more questions were found, false, {} if none were found.

yl_survey.get_question(s_id, q_id, include_responses, playername)

• s_id: string, required. This is the survey/UUID the question is added to.
• q_id: number, required.
• include_responses: boolean, optional, defaults to false. If true, the responses to that question are included.
• playername: string, optional. If given, adds only the responses of this player. May be empty {} if the player did not answer this question yet. No effect if include_responses is not true.

Returns true, {question} if successful, false, "errormessage" if not.

yl_survey.get_response(s_id, q_id, playername, include_question, include_freetext)

• s_id: string, required. This is the survey/UUID the question is added to.
• q_id: number, required.
• playername: string, required.
• include_question: boolean, optional, defaults to false. If true, the question to that response is included.
• include_freetext: boolean, optional, defaults to false. If true, the freetext of that response is included.

Returns true, {response} if successful, false, "errormessage" if not. May be {}, if the player did not yet respond to that question.

yl_survey.answer_question(s_id, q_id, playername, {responses}, overwrite)

The {responses} need to be in a format like {"0" = "the freetext answer, "4" = "The fourth answer", "5" = "Fifth answer"}

If overwrite is true, the responses are stored even if the same playername already answered that question. The old reponses are removed.

Returns true, {overwritten responses} if successful. overwritten responses is the table that was stored before this function replaced it with {responses}. May be {} if no responses were written over. Returns false, "errormessage" if not successful.

yl_survey.create_book(playername, s_id)

Returns boolean, number or string. boolean indicates whether the survey was found and the book was created for the player or not. If false, then string is the errormessage. If true, then number is the amount of answers this survey has on record from that player.

Creates a book of the answers of the survey and places it in the player's inventory.

yl_survey.validate_questions(s_id)

Returns true, number if successfully validated number amount of questions, false, "errormessage" if the validation was not successful.

Limitations

• No conditional questions

Alternatives

• Not tested, but maybe https://github.com/edu-minetest/quiz

Supported versions

If you use yl_survey, but something is wrong, please file a bug. PRs also welcome.

There is no reason to believe it doesn't work anywhere, but you never know.

Allied projects

If you know a project that uses this mod tell us and we will add it to the list.

Uninstall

Remove it from your mod folder or deactivate it in your world.mt

Mods that depend on it will cease to work, if the mod is removed without proper replacement.

Also remove the data folder. Look at the save_path setting where that is.

License

See LICENSE.md

• Code MIT Developername
• Screenshot CC0 Styxcolor

Thank you