
# 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, 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`. `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
* 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, allow_names, allow_anonymous, allow_changes, timestamp_start, timestamp_end, delete_responses)
```

Returns `true, s_id` 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, {"UUID1", "UUID2", ...}` 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(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.answer(playername, s_id)
```

Returns `boolean, number or string`. `boolean` indicates whether the survey was found and displayed to 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.

```
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 teh 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
