From 3ed8dfc06bc658a829920c22370a08bd153898d3 Mon Sep 17 00:00:00 2001 From: Toastie Date: Fri, 27 Dec 2024 03:48:56 +1300 Subject: [PATCH] Finished template documentation for now --- docs/InterviewTemplates.md | 327 +++++++++++++++++++++++++------------ docs/img/buttonExample.png | Bin 0 -> 6278 bytes 2 files changed, 227 insertions(+), 100 deletions(-) create mode 100644 docs/img/buttonExample.png diff --git a/docs/InterviewTemplates.md b/docs/InterviewTemplates.md index 86b78da..b223bda 100644 --- a/docs/InterviewTemplates.md +++ b/docs/InterviewTemplates.md @@ -1,37 +1,49 @@ -# Writing interview templates +# Writing Interview Templates + The bot can automatically interview users when they open a ticket. These interviews are defined in interview templates. The templates each apply to a single ticket category so you can have different interviews depending on the type of ticket. -## Interview template commands + +## Interview Template Commands + Whether you already have a template or not the first step is always to use the `/interviewtemplate get ` command on the ticket category you want to edit. If you haven't yet, use the `/addcategory` command on the category to register it with the bot. + The bot will reply with a JSON template file which you can edit and upload using the `/interviewtemplate set` command. + You can also delete an interview template using the `/interviewtemplate delete` command. -## Writing your first interview template + +## Writing Your First Interview Template + Use the get command to get a default template for the ticket category you want to edit: ``` /interviewtemplate get ``` + The bot will reply with a JSON template file for you to edit using your preferred text editor. + **Note:** It is highly recommended to use integrated template validation in your text editor, see below. + When you are done editing it you can upload it to the bot using the set command: ``` /interviewtemplate set ``` + The bot will check that your template is correctly formatted and provide feedback if it is not. -### Automatic validation and suggestions in your text editor + +## Automatic Template Validation and Suggestions in Text Editors + It is highly recommended to use the interview template JSON schema to get live validation of your template while you write it: -#### Guides for different editors: + +### Guides for Different Editors: +
+ VS Code 1. Go to `File->Preferences->Settings`. - 2. Search for `json schema`. - 3. Click `Edit in settings.json` on the schema setting. - 4. Set the `json.schemas` property to the following to automatically validate template files: - ```json { "json.schemas": @@ -41,124 +53,239 @@ It is highly recommended to use the interview template JSON schema to get live v [ "interview-template*.json" ], - "url": "https://toastielab.dev/Emotions-stuff/SupportChild/raw/branch/main/Interviews/interview_template.schema.json" + "url": "https://raw.githubusercontent.com/KarlOfDuty/SupportBoi/refs/heads/main/Interviews/interview_template.schema.json" } ] } ``` - 5. Open an interview template, you should now get suggestions for things like message types and color names, and error highlighting for any invalid sections. +
+
+ Jetbrains Editors 1. Go to `File->Settings->Languages & Frameworks->Schemas->JSON Schema Mapping`. - -2. Add a new schema with the following URL: `https://toastielab.dev/Emotions-stuff/SupportChild/raw/branch/main/Interviews/interview_template.schema.json`. - +2. Add a new schema with the following URL: `https://raw.githubusercontent.com/KarlOfDuty/SupportBoi/refs/heads/main/Interviews/interview_template.schema.json`. 3. Restart your editor and all interview templates should now automatically be set to the correct schema in the bottom right of the window. +
-## Interview template format +## Interview Template Format + This section lists all the properties that can be used in an interview template. If you have set up your editor as suggested above it will handle a lot of this for you automatically. -All templates start with the following properties at the top level: - -| Property                 | Required | Description | -|----------------------------------------------------------------------------------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------| -| `category-id` | Yes | The id of the category this template applies to. You can change this and re-upload the template to apply it to a different category. | -| `interview` | Yes | Contains the first step of the interview, see below. | -The rest of the template is a series of interview steps, with the following parameters: - -| Property                                       | Required | Description | -|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `message` | Yes | The text in the embed message that will be sent to the user when they reach this step. | -| `message-type` | Yes | The type of message, decides what the bot will do when the user gets to this step.
Must be one of: ERROR, END_WITH_SUMMARY, END_WITHOUT_SUMMARY, BUTTONS, TEXT_SELECTOR, USER_SELECTOR, ROLE_SELECTOR,MENTIONABLE_SELECTOR, CHANNEL_SELECTOR, TEXT_INPUT | -| `color` | Yes | Colour of the message embed. | -| `paths` | Yes | One or more interview steps. The name of the step is used as a regex match against the user's answer, except for selection boxes and buttons where each step becomes a button or selection option. | -| `heading` | No | The title of the embed message. | -| `summary-field` | No | | -| `button-style` | No | | -| `selector-description` | No | | -| `selector-placeholder` | No | | -| `max-length` | No | | -| `min-length` | No | | -## Example template ```json { - "category-id": "1005612326340272169", + "category-id": "1006863882301755503", "interview": { - "message": "Are you appealing your own ban or on behalf of another user?", + "message": "What is your favourite colour?", "message-type": "BUTTONS", - "color": "AQUAMARINE", + "color": "BLUE", + "summary-field": "Favourite colour", "paths": { - "My own ban": + "PRIMARY": { - "message": "Please write your appeal below, motivate why you think you should be unbanned.", - "message-type": "TEXT_INPUT", - "color": "CYAN", - "summary-field": "Ban appeal", - "paths": - { - ".*": - { - "heading": "Appeal Summary", - "message": "Thank you, a staff member will review your appeal.", - "message-type": "END_WITH_SUMMARY", - "color": "GREEN", - "paths": {} - } - } + "message": "Summary", + "message-type": "END_WITH_SUMMARY", + "color": "BLUE", + "button-style": "PRIMARY", + "paths": {} }, - "Another user's ban": + "SECONDARY": { - "message": "Whose ban are you appealing?", - "message-type": "USER_SELECTOR", - "color": "CYAN", - "summary-field": "User", - "paths": - { - "<@170904988724232192>": - { - "message": "Not allowed", - "message-type": "ERROR", - "color": "RED", - "paths": {} - }, - ".*": - { - "message": "What is their role?", - "message-type": "ROLE_SELECTOR", - "color": "CYAN", - "summary-field": "Their Role", - "paths": - { - ".*": - { - "message": "Please write the appeal below.", - "message-type": "TEXT_INPUT", - "color": "CYAN", - "summary-field": "Ban appeal", - "paths": - { - ".*": - { - "heading": "Appeal Summary", - "message": "Thank you, a staff member will review the appeal.", - "message-type": "END_WITH_SUMMARY", - "color": "GREEN", - "paths": {} - } - } - } - } - } - } + "message": "Summary", + "message-type": "END_WITH_SUMMARY", + "color": "GRAY", + "button-style": "SECONDARY", + "paths": {} + }, + "SUCCESS": + { + "message": "Summary", + "message-type": "END_WITH_SUMMARY", + "color": "GREEN", + "button-style": "SUCCESS", + "paths": {} + }, + "DANGER": + { + "message": "Summary", + "message-type": "END_WITH_SUMMARY", + "color": "RED", + "button-style": "DANGER", + "paths": {} } } } } -``` \ No newline at end of file +``` + +### Template Root + +| Property            | Required | Description | +|----------------------------------------------------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------| +| `category-id` | Yes | The id of the category this template applies to. You can change this and re-upload the template to apply it to a different category. | +| `interview` | Yes | Contains the interview conversation tree, starting with one path which branches into many. | + +### Interview Paths + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Property                             RequiredTypeDescription
+ + +`message` + YesString +The text in the embed message that will be sent to the user when they reach this step. +
+`message-type` + YesString +The type of message, decides what the bot will do when the user gets to this step. + + +
+ + +`color` + YesString + +Colour of the message embed. You can either enter a colour name or a hexadecimal RGB value. +
+`paths` + YesSteps +One or more interview steps. The name of the step is used as a regex match against the user's answer, +except for selection boxes and buttons where each step becomes a button or selection option. +
+`heading` + YesString +The title of the embed message. +
+`summary-field` + YesString +When an interview ends all previous answers with this property will be put in a summary. +If this property is not specified the answer will not be shown in the summary. +The value of this property is the name which will be displayed next to the answer in the summary. +
+`button-style` + YesString +The style of this path's button. Requires that the parent path is a `BUTTONS` path. +Must be one of the following: +- `PRIMARY` +- `SECONDARY` +- `SUCCESS` +- `DANGER` + +Default style is `SECONDARY`. + +![Button Example](./img/buttonExample.png) +
+`selector-description` + YesString +Description for this option in the parent path's selection box. Requires that the parent path is a `TEXT_SELECTOR`. +
+`selector-placeholder` + YesString +The placeholder text shown before a value is selected in the selection box. Requires that this path is a `TEXT_SELECTOR`. +
+`max-length` + YesNumber +The maximum length of the user's response message. Requires that this path is a `TEXT_INPUT`. +
+`min-length` + YesNumber +The minimum length of the user's response message. Requires that this path is a `TEXT_INPUT`. +
+ +### Message Types + +| Message Type | Description | +|------------------------|------------------------------------------------------------------------------------------------------------------------------------------| +| `ERROR` | Sends an error message but does not stop the interview. The interview remains on the same step as before allowing the user to try again. | +| `END_WITH_SUMMARY` | End the interview and create a summary of the answers. | +| `END_WITHOUT_SUMMARY` | End the interview with a simple message without a summary. | +| `BUTTONS` | Creates a message with one button per child path where the button text is the name of the child path. | +| `TEXT_SELECTOR` | Creates a selection box with one option per child path where the option text is the name of the child path. | +| `USER_SELECTOR` | Creates a selection box where the user can select a user from the Discord server. The value used for the summary is the user's mention. | +| `ROLE_SELECTOR` | Same as above but for a role. | +| `MENTIONABLE_SELECTOR` | Same as above but works for both roles and users. | +| `CHANNEL_SELECTOR` | Same as above but for channels and categories. | +| `TEXT_INPUT` | Lets the user reply to the bot message with their own text. | \ No newline at end of file diff --git a/docs/img/buttonExample.png b/docs/img/buttonExample.png new file mode 100644 index 0000000000000000000000000000000000000000..7c1d5515379d7b716e7e498a373ab4358f148c61 GIT binary patch literal 6278 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 T@t^*pe}J;Qnp~BPdD#B}>|98t literal 0 HcmV?d00001