Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
ee6a7b8
feat: rating question type
global-prog Sep 9, 2026
5074020
refactor: build the rating on the linear scale's settings and validation
global-prog Sep 11, 2026
348add1
implement review comments
Chartman123 Nov 16, 2026
b759398
fix(rating): check rating answers against the scale, not ranking answers
AndyScherzinger Nov 19, 2026
ac8fdb6
fix(rating): reject booleans and lists as answers on a scale
AndyScherzinger Nov 19, 2026
8daab99
fix(rating): name each option of a rating by its value
AndyScherzinger Nov 19, 2026
1e73e58
fix(rating): keep the rating in view when one of its options gets focus
AndyScherzinger Nov 19, 2026
837f3e1
fix(rating): keep the answer to a rating in drafts and edited responses
AndyScherzinger Nov 19, 2026
5cb0705
fix(rating): focus a new rating question and keep its insert menu
AndyScherzinger Nov 19, 2026
94f1a0e
fix(rating): show why a required rating cannot be submitted
AndyScherzinger Nov 19, 2026
05914b8
fix(rating): move on from a rating on Enter instead of submitting
AndyScherzinger Nov 19, 2026
dc5e1a2
fix(rating): name the picker for the highest rating
AndyScherzinger Nov 19, 2026
daa4582
refactor(rating): drop the clear-button leftovers and a second icon l…
AndyScherzinger Nov 19, 2026
482e8f6
style: format the list of date and time answer types
AndyScherzinger Nov 19, 2026
3658d8d
fix(rating): reject answers on a scale written with leading zeros
AndyScherzinger Nov 19, 2026
a7d3d4f
fix(rating): accept only the icons a rating can draw
AndyScherzinger Nov 19, 2026
bf8998d
docs: describe the rating question and its settings
AndyScherzinger Nov 19, 2026
16d6091
refactor(rating): name the rating by the question title
AndyScherzinger Nov 19, 2026
758cc07
test(e2e): cover the rating question
AndyScherzinger Nov 19, 2026
082876e
fix(rating): pass the hint on the name of a rating option to translators
AndyScherzinger Nov 19, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/DataStructure.md
Original file line number Diff line number Diff line change
Expand Up @@ -238,6 +238,7 @@ Currently supported Question-Types are:
| `time` | Showing a dropdown menu to select a time. |
| `file` | One or multiple files. It is possible to specify which mime types are allowed |
| `linearscale` | A linear or Likert scale question where you choose an option that best fits your opinion |
| `rating` | A rating from 1 to the highest value, shown as stars, hearts or thumbs up. The answer is the number of the chosen icon. |
| `color` | A color answer, hex string representation (e. g. `#123456`) |
| `ranking` | Using pre-defined options, the user ranks them from most to least preferred. Needs at least one option available. Answers are stored in ranked order (one answer row per option). |

Expand All @@ -264,9 +265,10 @@ Optional extra settings for some [Question Types](#question-types)
| `timeMin` | `time` | string | - | Minimum allowed time to be chosen (as `HH:mm` string) |
| `timeRange` | `time` | Boolean | `true/false` | The time picker should query a time range |
| `optionsLowest` | `linearscale` | Integer | `0, 1` | Set the lowest value of the scale, default: `1` |
| `optionsHighest` | `linearscale` | Integer | `2, 3, 4, 5, 6, 7, 8, 9, 10` | Set the highest value of the scale, default: `5` |
| `optionsHighest` | `linearscale, rating` | Integer | `2, 3, 4, 5, 6, 7, 8, 9, 10` | Set the highest value of the scale, default: `5` |
| `optionsLabelLowest` | `linearscale` | string | - | Set the label of the lowest value, default: `'Strongly disagree'` |
| `optionsLabelHighest` | `linearscale` | string | - | Set the label of the highest value, default: `'Strongly agree'` |
| `ratingIcon` | `rating` | string | `'star', 'heart', 'thumb'` | Set the icon of the rating, default: `'star'` |
| `columns` | `grid` | Array | - | Array of column identifiers / labels for grid questions |
| `rows` | `grid` | Array | - | Array of row identifiers / labels for grid questions |
| `questionType` | `grid` | String | `checkbox`, `number`, `radio` | Type of cell for grid questions (checkbox, numeric input, or radio) |
Expand Down
34 changes: 27 additions & 7 deletions lib/Constants.php
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,7 @@ class Constants {
public const ANSWER_TYPE_MULTIPLE = 'multiple';
public const ANSWER_TYPE_MULTIPLEUNIQUE = 'multiple_unique';
public const ANSWER_TYPE_RANKING = 'ranking';
public const ANSWER_TYPE_RATING = 'rating';
public const ANSWER_TYPE_SHORT = 'short';
public const ANSWER_TYPE_TIME = 'time';

Expand All @@ -131,10 +132,18 @@ class Constants {
self::ANSWER_TYPE_MULTIPLE,
self::ANSWER_TYPE_MULTIPLEUNIQUE,
self::ANSWER_TYPE_RANKING,
self::ANSWER_TYPE_RATING,
self::ANSWER_TYPE_SHORT,
self::ANSWER_TYPE_TIME,
];
Comment thread
Chartman123 marked this conversation as resolved.
Resolved

// AnswerTypes for date/time questions
public const ANSWER_TYPES_DATETIME = [
self::ANSWER_TYPE_DATE,
self::ANSWER_TYPE_DATETIME,
self::ANSWER_TYPE_TIME,
];

// AnswerTypes, that need/have predefined Options
public const ANSWER_TYPES_PREDEFINED = [
self::ANSWER_TYPE_DROPDOWN,
Expand All @@ -145,18 +154,17 @@ class Constants {
self::ANSWER_TYPE_RANKING,
];

// AnswerTypes for date/time questions
public const ANSWER_TYPES_DATETIME = [
self::ANSWER_TYPE_DATE,
self::ANSWER_TYPE_DATETIME,
self::ANSWER_TYPE_TIME
// AnswerTypes for scale questions
// TODO: add linearscale
public const ANSWER_TYPES_SCALE = [
self::ANSWER_TYPE_RATING,
];

// Formats for AnswerTypes date/datetime/time
public const ANSWER_PHPDATETIME_FORMAT = [
self::ANSWER_TYPE_DATE => 'Y-m-d',
self::ANSWER_TYPE_DATETIME => 'Y-m-d H:i',
self::ANSWER_TYPE_TIME => 'H:i'
self::ANSWER_TYPE_TIME => 'H:i',
];

/**
Expand All @@ -168,7 +176,7 @@ class Constants {
'phone',
'email',
'regex',
'number'
'number',
];

// This are allowed extra settings
Expand Down Expand Up @@ -229,6 +237,18 @@ class Constants {
'rows' => ['array'],
];

public const EXTRA_SETTINGS_RATING = [
'optionsHighest' => ['integer', 'NULL'],
'ratingIcon' => ['string', 'NULL'],
];

// should be in sync with ICON_CHOICES in QuestionRating.vue
public const EXTRA_SETTINGS_RATING_ICONS = [
'star',
'heart',
'thumb',
];

public const EXTRA_SETTINGS_RANKING = [
'shuffleOptions' => ['boolean'],
];
Expand Down
1 change: 1 addition & 0 deletions lib/ResponseDefinitions.php
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
* optionsLimitMax?: int,
* optionsLimitMin?: int,
* optionsLowest?: 0|1,
* ratingIcon?: "star"|"heart"|"thumb",
* shuffleOptions?: bool,
* timeMax?: string,
* timeMin?: string,
Expand Down
10 changes: 7 additions & 3 deletions lib/Service/FormsService.php
Original file line number Diff line number Diff line change
Expand Up @@ -909,6 +909,7 @@ public function areExtraSettingsValid(array $extraSettings, string $questionType
Constants::ANSWER_TYPE_DATE => Constants::EXTRA_SETTINGS_DATE,
Constants::ANSWER_TYPE_GRID => Constants::EXTRA_SETTINGS_GRID,
Constants::ANSWER_TYPE_RANKING => Constants::EXTRA_SETTINGS_RANKING,
Constants::ANSWER_TYPE_RATING => Constants::EXTRA_SETTINGS_RATING,
Constants::ANSWER_TYPE_TIME => Constants::EXTRA_SETTINGS_TIME,
Constants::ANSWER_TYPE_LINEARSCALE => Constants::EXTRA_SETTINGS_LINEARSCALE,
default => [],
Expand Down Expand Up @@ -1045,10 +1046,13 @@ public function areExtraSettingsValid(array $extraSettings, string $questionType
}

// Special handling of linear scale validation
} elseif ($questionType === Constants::ANSWER_TYPE_LINEARSCALE) {
// Ensure limits are sane
} elseif ($questionType === Constants::ANSWER_TYPE_LINEARSCALE
|| $questionType === Constants::ANSWER_TYPE_RATING) {
// Ensure limits are sane. A rating cannot set optionsLowest at all, so for it
// only the top end is checked.
if (isset($extraSettings['optionsLowest']) && ($extraSettings['optionsLowest'] < 0 || $extraSettings['optionsLowest'] > 1)
|| isset($extraSettings['optionsHighest']) && ($extraSettings['optionsHighest'] < 2 || $extraSettings['optionsHighest'] > 10)) {
|| isset($extraSettings['optionsHighest']) && ($extraSettings['optionsHighest'] < 2 || $extraSettings['optionsHighest'] > 10)
|| isset($extraSettings['ratingIcon']) && !in_array($extraSettings['ratingIcon'], Constants::EXTRA_SETTINGS_RATING_ICONS, true)) {
return false;
}
}
Expand Down
37 changes: 30 additions & 7 deletions lib/Service/SubmissionService.php
Original file line number Diff line number Diff line change
Expand Up @@ -695,7 +695,14 @@ public function validateSubmission(array $questions, array $answers, string $for
* Otherwise, validate the single answer for the date/time question
*/
if (in_array($question['type'], Constants::ANSWER_TYPES_DATETIME)) {
$this->validateDateTime($answers[$questionId], Constants::ANSWER_PHPDATETIME_FORMAT[$question['type']], $question['text'] ?? null, $question['extraSettings'] ?? null);
$this->validateDateTimeQuestion($answers[$questionId], Constants::ANSWER_PHPDATETIME_FORMAT[$question['type']], $question['text'] ?? null, $question['extraSettings'] ?? null);
}

// Check if answers to scale questions are within the limits
if (in_array($question['type'], Constants::ANSWER_TYPES_SCALE)) {
foreach ($answers[$questionId] as $answer) {
$this->validateScaleQuestion($question, $answer);
}
}

// Check if all answers are within the possible options
Expand All @@ -705,12 +712,9 @@ public function validateSubmission(array $questions, array $answers, string $for

foreach ($answers[$questionId] as $answer) {
// Handle linear scale questions
// TODO: move to scale question check
if ($question['type'] === Constants::ANSWER_TYPE_LINEARSCALE) {
$optionsLowest = $question['extraSettings']['optionsLowest'] ?? 1;
$optionsHighest = $question['extraSettings']['optionsHighest'] ?? 5;
if (!is_scalar($answer) || is_bool($answer) || !ctype_digit((string)$answer) || intval($answer) < $optionsLowest || intval($answer) > $optionsHighest) {
throw new \InvalidArgumentException(sprintf('The answer for question "%s" must be an integer between %d and %d.', $question['text'], $optionsLowest, $optionsHighest));
}
$this->validateScaleQuestion($question, $answer);
}
// Check if all grid rows, columns and values match the configured grid subtype
elseif ($question['type'] === Constants::ANSWER_TYPE_GRID) {
Expand Down Expand Up @@ -791,14 +795,33 @@ public function validateSubmission(array $questions, array $answers, string $for
}
}

/**
* Check one answer to a question answered on a numbered scale.
*
* Shared by the linear scale and the rating, which differ only in how the scale is
* drawn. The bounds and their defaults are the linear scale's; a rating does not
* accept optionsLowest, so its lowest end always falls back to 1.
*
* @param array $question the question being answered
* @param mixed $answer one submitted value
* @throws \InvalidArgumentException if the answer is not a whole number within range, written without leading zeros
*/
private function validateScaleQuestion(array $question, mixed $answer): void {
$optionsLowest = $question['extraSettings']['optionsLowest'] ?? 1;
$optionsHighest = $question['extraSettings']['optionsHighest'] ?? 5;
if (!is_scalar($answer) || is_bool($answer) || !ctype_digit((string)$answer) || (string)intval($answer) !== (string)$answer || intval($answer) < $optionsLowest || intval($answer) > $optionsHighest) {
throw new \InvalidArgumentException(sprintf('The answer for question "%s" must be an integer between %d and %d.', $question['text'], $optionsLowest, $optionsHighest));
}
}

/**
* Validate correct date/time formats
* @param array $answers Array with date from answer
* @param string $format String with the format to validate
* @param string|null $text String with the title of the question
* @param array|null $extraSettings Array with extra settings for validation
*/
private function validateDateTime(array $answers, string $format, ?string $text = null, ?array $extraSettings = null): void {
private function validateDateTimeQuestion(array $answers, string $format, ?string $text = null, ?array $extraSettings = null): void {
$previousDate = null;

foreach ($answers as $dateStr) {
Expand Down
8 changes: 8 additions & 0 deletions openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -575,6 +575,14 @@
1
]
},
"ratingIcon": {
"type": "string",
"enum": [
"star",
"heart",
"thumb"
]
},
"shuffleOptions": {
"type": "boolean"
},
Expand Down
144 changes: 144 additions & 0 deletions playwright/e2e/rating-question.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
/**
* SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
* SPDX-License-Identifier: AGPL-3.0-or-later
*/

import { expect, mergeTests } from '@playwright/test'
import { test as formTest } from '../support/fixtures/form.ts'
import { test as appNavigationTest } from '../support/fixtures/navigation.ts'
import { test as randomUserTest } from '../support/fixtures/random-user.ts'
import { test as resultsTest } from '../support/fixtures/results.ts'
import { test as submitTest } from '../support/fixtures/submit.ts'
import { test as topBarTest } from '../support/fixtures/topBar.ts'
import { QuestionType } from '../support/sections/QuestionType.ts'
import { FormsView } from '../support/sections/TopBarSection.ts'

const test = mergeTests(
randomUserTest,
appNavigationTest,
formTest,
topBarTest,
submitTest,
resultsTest,
)

test.describe('Rating question', () => {
test.beforeEach(async ({ page, appNavigation, form }) => {
await page.goto('apps/forms')
await page.waitForURL(/apps\/forms\/?$/)
await appNavigation.clickNewForm()
await form.fillTitle('Rating test form')

await form.addQuestion(QuestionType.Rating)
const questions = await form.getQuestions()
await questions[0].fillTitle('Rate the service')
await questions[0].fillDescription('One star is poor')
})

test('Names the rating by its question and each option by its value', async ({
topBar,
submitView,
}) => {
await topBar.toggleView(FormsView.View)

const group = submitView.getQuestion('Rate the service').getByRole('group')
await expect(group).toHaveAttribute('aria-labelledby', 'q1_title')
await expect(group).toHaveAttribute('aria-describedby', 'q1_desc')
const options = group.getByRole('radio')
await expect(options).toHaveCount(5)
for (let value = 1; value <= 5; value++) {
await expect(options.nth(value - 1)).toHaveAccessibleName(
`${value} of 5`,
)
}
})

test('Restores the rating from local storage on reload', async ({
topBar,
submitView,
page,
}) => {
await topBar.toggleView(FormsView.View)
await submitView.checkRadio('Rate the service', '4 of 5')

await page.reload()

await expect(
submitView
.getQuestion('Rate the service')
.getByRole('radio', { name: '4 of 5' }),
).toBeChecked()
})

test('Restores the rating when editing a submission', async ({
topBar,
submitView,
resultsView,
page,
}) => {
await topBar.toggleView(FormsView.View)
await submitView.checkRadio('Rate the service', '4 of 5')
await submitView.submit()
await expect(submitView.successMessage).toBeVisible()

await page.goto(page.url().replace(/\/submit.*$/, '/results'))
await resultsView.switchToResponses()
await resultsView.editSubmission()

await expect(
submitView
.getQuestion('Rate the service')
.getByRole('radio', { name: '4 of 5' }),
).toBeChecked()
})

test('Moves on from a rating on Enter instead of submitting', async ({
topBar,
submitView,
}) => {
await topBar.toggleView(FormsView.View)
await submitView.checkRadio('Rate the service', '4 of 5')

const question = submitView.getQuestion('Rate the service')
await question.getByRole('radio', { name: '4 of 5' }).press('Enter')

await expect(question.getByRole('radio', { name: '5 of 5' })).toBeFocused()
await expect(submitView.successMessage).toHaveCount(0)
})

test('Shows an error when a required rating is left empty', async ({
form,
topBar,
submitView,
}) => {
const questions = await form.getQuestions()
await questions[0].toggleRequired()
await topBar.toggleView(FormsView.View)

await submitView.submitButton.click()

const question = submitView.getQuestion('Rate the service')
await expect(
question.getByText('You must answer this question'),
).toBeVisible()
await expect(question.getByRole('radio').first()).toHaveAttribute(
'aria-invalid',
'true',
)
})

test('Focuses a new rating question and offers to insert a question after it', async ({
form,
page,
}) => {
await form.addQuestion(QuestionType.Rating)

const questions = await form.getQuestions()
await expect(questions[1].titleInput).toBeFocused()
await expect(
page.getByRole('button', {
name: 'Insert question after question 1',
}),
).toHaveCount(1)
})
})
1 change: 1 addition & 0 deletions playwright/support/sections/QuestionType.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ export enum QuestionType {
LinearScale = 'Linear scale',
LongAnswer = 'Long text',
Ranking = 'Ranking',
Rating = 'Rating',
RadioButtons = 'Radio buttons',
ShortAnswer = 'Short answer',
}
Expand Down
Loading