generated from your-land/yl_template
222 lines
9.1 KiB
Markdown
222 lines
9.1 KiB
Markdown
|
|
# 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](#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](https://gitea.your-land.de/your-land/yl_survey/src/branch/master/dev/whatdowedo.txt)
|
|
|
|
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 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, {allowed_types}, {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.
|
|
* {allowed_types}: table of enum("singlechoice","multiplechoice","freetext"), required. `singlechoice` and `multiplechoice` are mutually exclusive, while freetxt can be combined with either.
|
|
* {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, {allowed_types}, {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](https://gitea.your-land.de/your-land/yl_survey/issues/new). 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](https://gitea.your-land.de/your-land/yl_survey/src/LICENSE.md)
|
|
|
|
* Code MIT Developername
|
|
* Screenshot CC0 Styxcolor
|
|
|
|
## Thank you
|