Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
3 changes: 2 additions & 1 deletion docs/API_v3.md
Original file line number Diff line number Diff line change
Expand Up @@ -377,7 +377,7 @@ Returns the questions and options of the given form (without submissions).
|-----------|---------|----------|-------------|
| _type_ | [QuestionType](DataStructure.md#question-types) | | The question-type of the new question |
| _text_ | String | yes | _Optional_ The text of the new question. |
| _subtype_ | String | yes | _Optional_ The sub type, stored as `extraSettings.questionType`: `checkbox`, `number` or `radio` for `grid`, `rating` for `linearscale` (a 1 to N scale drawn as icons). Any other value is rejected. |
| _subtype_ | String | yes | _Optional_ The sub type, stored as `extraSettings.questionType`: `checkbox`, `number` or `radio` for `grid`, `rating` (a 1 to N scale drawn as icons) or `promoter` (a fixed 0 to 10 scale) for `linearscale`. Any other value is rejected. |
| _position_ | Integer | yes | _(optional)_ 1-based position to insert the new question. When omitted the question is appended at the end. |
- Response: The new question object.

Expand Down Expand Up @@ -456,6 +456,7 @@ Update a single or multiple properties of a question-object.
- Restrictions:
- It is **not allowed** to update one of the following key-value pairs: _id, formId, order, type_.
- The sub type `extraSettings.questionType` is fixed when the question is created. An `extraSettings` value that adds, removes or changes `questionType` is rejected with **403 Forbidden**, so send the stored `questionType` with every `extraSettings` update.
- A promoter score question (`questionType` `promoter`) keeps `optionsLowest` at `0` and `optionsHighest` at `10`; send both with every `extraSettings` update, or it is rejected with **400 Bad Request**.
- Response: **Status-Code OK**, as well as the id of the updated question.

```
Expand Down
10 changes: 5 additions & 5 deletions docs/DataStructure.md
Original file line number Diff line number Diff line change
Expand Up @@ -263,14 +263,14 @@ Optional extra settings for some [Question Types](#question-types)
| `timeMax` | `time` | string | - | Maximum allowed time to be chosen (as `HH:mm` string) |
| `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`; always `1` for the `rating` sub type |
| `optionsHighest` | `linearscale` | 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'`; not allowed for the `rating` sub type |
| `optionsLabelHighest` | `linearscale` | string | - | Set the label of the highest value, default: `'Strongly agree'`; not allowed for the `rating` sub type |
| `optionsLowest` | `linearscale` | Integer | `0, 1` | Set the lowest value of the scale, default: `1`; always `1` for the `rating` sub type, always `0` for the `promoter` sub type |
| `optionsHighest` | `linearscale` | Integer | `2, 3, 4, 5, 6, 7, 8, 9, 10` | Set the highest value of the scale, default: `5`; always `10` for the `promoter` sub type |
| `optionsLabelLowest` | `linearscale` | string | - | Set the label of the lowest value, default: `'Strongly disagree'`, `'Not at all likely'` for the `promoter` sub type; not allowed for the `rating` sub type |
| `optionsLabelHighest` | `linearscale` | string | - | Set the label of the highest value, default: `'Strongly agree'`, `'Extremely likely'` for the `promoter` sub type; not allowed for the `rating` sub type |
| `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) |
| `questionType` | `linearscale` | String | `rating` | Sub type, fixed at creation; `rating` is a 1 to N scale drawn as icons; absent for a plain scale |
| `questionType` | `linearscale` | String | `rating`, `promoter` | Sub type, fixed at creation; `rating` is a 1 to N scale drawn as icons, `promoter` is a 0 to 10 scale whose results show the promoter score; absent for a plain scale |
| `ratingIcon` | `linearscale` with `questionType` `rating` | string | `'star', 'heart', 'thumb'` | Set the icon of the rating, default: `'star'` |

### Option Types
Expand Down
10 changes: 10 additions & 0 deletions lib/Constants.php
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,7 @@ class Constants {
public const ANSWER_GRID_TYPE_RADIO = 'radio';

public const ANSWER_LINEARSCALE_TYPE_RATING = 'rating';
public const ANSWER_LINEARSCALE_TYPE_PROMOTER = 'promoter';

// All AnswerTypes
public const ANSWER_TYPES = [
Expand Down Expand Up @@ -251,6 +252,15 @@ class Constants {

public const EXTRA_SETTINGS_LINEARSCALE_QUESTION_TYPE = [
self::ANSWER_LINEARSCALE_TYPE_RATING,
self::ANSWER_LINEARSCALE_TYPE_PROMOTER,
];

/**
* The fixed range of a linear scale with the promoter score sub type
*/
public const LINEARSCALE_PROMOTER_RANGE = [
'optionsLowest' => 0,
'optionsHighest' => 10,
];

/**
Expand Down
3 changes: 3 additions & 0 deletions lib/Controller/ApiController.php
Original file line number Diff line number Diff line change
Expand Up @@ -577,6 +577,9 @@ public function newQuestion(int $formId, ?string $type = null, ?string $subtype
}

$extraSettings = $subtype ? ['questionType' => $subtype] : [];
if ($type === Constants::ANSWER_TYPE_LINEARSCALE && $subtype === Constants::ANSWER_LINEARSCALE_TYPE_PROMOTER) {
$extraSettings += Constants::LINEARSCALE_PROMOTER_RANGE;
}
if (!$this->formsService->areExtraSettingsValid($extraSettings, $type)) {
throw new OCSBadRequestException('Invalid subtype');
}
Expand Down
2 changes: 1 addition & 1 deletion lib/ResponseDefinitions.php
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@
* }
*
* @psalm-type FormsQuestionType = "dropdown"|"multiple"|"multiple_unique"|"date"|"time"|"short"|"long"|"file"|"datetime"|"grid"|"linearscale"|"color"|"ranking"
* @psalm-type FormsQuestionSubtype = "checkbox"|"number"|"radio"|"rating"
* @psalm-type FormsQuestionSubtype = "checkbox"|"number"|"radio"|"rating"|"promoter"
*
* @psalm-type FormsQuestion = array{
* id: int,
Expand Down
6 changes: 6 additions & 0 deletions lib/Service/FormsService.php
Original file line number Diff line number Diff line change
Expand Up @@ -1061,6 +1061,12 @@ public function areExtraSettingsValid(array $extraSettings, string $questionType
return false;
}

if ($subtype === Constants::ANSWER_LINEARSCALE_TYPE_PROMOTER
&& (($extraSettings['optionsLowest'] ?? null) !== Constants::LINEARSCALE_PROMOTER_RANGE['optionsLowest']
|| ($extraSettings['optionsHighest'] ?? null) !== Constants::LINEARSCALE_PROMOTER_RANGE['optionsHighest'])) {
return false;
}

if (isset($extraSettings['ratingIcon'])
&& ($subtype !== Constants::ANSWER_LINEARSCALE_TYPE_RATING || !in_array($extraSettings['ratingIcon'], Constants::RATING_ICONS, true))) {
return false;
Expand Down
3 changes: 2 additions & 1 deletion openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -612,7 +612,8 @@
"checkbox",
"number",
"radio",
"rating"
"rating",
"promoter"
]
},
"QuestionType": {
Expand Down
195 changes: 195 additions & 0 deletions playwright/e2e/results-scale-figures.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,195 @@
/**
* SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
* SPDX-License-Identifier: AGPL-3.0-or-later
*/

import type { APIRequestContext } from '@playwright/test'

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 { api, waitForApiResponse } from '../support/helpers.ts'
import {
LinearScaleSubtype,
QuestionType,
} from '../support/sections/QuestionType.ts'

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

/**
* Create a form with the linear scale "Recommend" and one submission per answer
*
* @param request the request context of the page
* @param subtype the sub type of the scale, or null for a plain scale
* @param extraSettings further extra settings of the scale
* @param answers the answers to submit, one submission each
*/
async function createScaleForm(
request: APIRequestContext,
subtype: string | null,
extraSettings: Record<string, unknown>,
answers: string[] = [],
) {
const form = await api(request, 'POST', '/forms')
await api(request, 'PATCH', `/forms/${form.id}`, {
keyValuePairs: { submitMultiple: true },
})
const scale = await api(request, 'POST', `/forms/${form.id}/questions`, {
type: 'linearscale',
subtype,
text: 'Recommend',
})
if (Object.keys(extraSettings).length > 0) {
await api(request, 'PATCH', `/forms/${form.id}/questions/${scale.id}`, {
keyValuePairs: {
extraSettings: { ...scale.extraSettings, ...extraSettings },
},
})
}
for (const answer of answers) {
await api(request, 'POST', `/forms/${form.id}/submissions`, {
answers: { [scale.id]: [answer] },
})
}
return form
}

test('Scale figures and the promoter score are shown above the bars', async ({
page,
resultsView,
}) => {
const form = await createScaleForm(page.request, 'promoter', {}, [
'10',
'9',
'7',
'3',
])
await page.goto(`apps/forms/${form.hash}/results`)
await page.waitForURL(/\/results\/summary$/)

const summary = resultsView.getSummaryForQuestion('Recommend')
await expect(
summary.getByText(
'Linear scale (0: Not at all likely, 10: Extremely likely)',
{ exact: true },
),
).toBeVisible()
const figure = (label: string) => summary.locator(`dt:text-is("${label}") + dd`)
await expect(figure('Answers')).toHaveText('4')
await expect(figure('Average')).toHaveText('7.3')
await expect(figure('Median')).toHaveText('8')
await expect(figure('Minimum')).toHaveText('3')
await expect(figure('Maximum')).toHaveText('10')
const promoterLabel = summary.locator('dt', { hasText: 'Promoter score' })
await expect(promoterLabel).toBeVisible()
await expect(promoterLabel.locator('.hidden-visually')).toHaveText(
'(promoters βˆ’ detractors)',
)
await expect(promoterLabel.locator('+ dd')).toHaveText('+25')
await expect(
summary.getByText('25% detractors Β· 25% passives Β· 50% promoters'),
).toBeVisible()
await expect(summary.locator('dl + ol meter')).not.toHaveCount(0)
})

test('A plain 0 to 10 scale shows no promoter score', async ({
page,
resultsView,
}) => {
const form = await createScaleForm(
page.request,
null,
{ optionsLowest: 0, optionsHighest: 10 },
['10', '3'],
)
await page.goto(`apps/forms/${form.hash}/results`)
await page.waitForURL(/\/results\/summary$/)

const summary = resultsView.getSummaryForQuestion('Recommend')
await expect(summary.locator('dt:text-is("Average") + dd')).toHaveText('6.5')
await expect(summary.getByText(/Promoter score/)).toHaveCount(0)
})

test('A rating shows its average rating and no scale figures', async ({
page,
resultsView,
}) => {
const form = await createScaleForm(page.request, 'rating', {}, ['5', '4'])
await page.goto(`apps/forms/${form.hash}/results`)
await page.waitForURL(/\/results\/summary$/)

const summary = resultsView.getSummaryForQuestion('Recommend')
await expect(summary.getByText('4.5 of 5', { exact: true })).toBeVisible()
await expect(
summary.getByText('Average rating 4.5 of 5, from 2 ratings'),
).toHaveCount(1)
await expect(summary.locator('dl')).toHaveCount(0)
await expect(summary.getByText(/Promoter score/)).toHaveCount(0)
})

test('A promoter score question from the menu is a fixed 0 to 10 scale', async ({
page,
appNavigation,
form,
}) => {
await page.goto('apps/forms')
await appNavigation.clickNewForm()
await form.fillTitle('Promoter form')

const created = waitForApiResponse(page, 'POST')
await form.addQuestion(QuestionType.LinearScale, LinearScaleSubtype.Promoter)
const response = await created
expect(response.request().postDataJSON()).toMatchObject({
type: 'linearscale',
subtype: 'promoter',
})
expect((await response.json()).ocs.data.extraSettings).toEqual({
questionType: 'promoter',
optionsLowest: 0,
optionsHighest: 10,
})

const [question] = await form.getQuestions()
await expect(question.section.getByRole('radio')).toHaveCount(11)
await expect(question.section.getByRole('radio').first()).toHaveAccessibleName(
'0',
)
await expect(question.section.getByRole('radio').last()).toHaveAccessibleName(
'10',
)
await expect(
question.section.getByRole('textbox', { name: 'Label for lowest value' }),
).toHaveValue('Not at all likely')
await expect(
question.section.getByRole('textbox', { name: 'Label for highest value' }),
).toHaveValue('Extremely likely')

await question.openActionsMenu()
await expect(page.getByRole('checkbox', { name: 'Required' })).toBeVisible()
await expect(page.getByRole('combobox', { name: 'Lowest value' })).toHaveCount(0)
await expect(page.getByRole('combobox', { name: 'Highest value' })).toHaveCount(
0,
)
})

test('A numbers question from the menu has no sub type', async ({
page,
appNavigation,
form,
}) => {
await page.goto('apps/forms')
await appNavigation.clickNewForm()
await form.fillTitle('Numbers form')

const created = waitForApiResponse(page, 'POST')
await form.addQuestion(QuestionType.LinearScale, LinearScaleSubtype.Numbers)
const response = await created
expect(response.request().postDataJSON().subtype).toBeNull()
expect((await response.json()).ocs.data.extraSettings).toEqual({})

const [question] = await form.getQuestions()
await question.openActionsMenu()
await expect(page.getByRole('combobox', { name: 'Lowest value' })).toBeVisible()
})
1 change: 1 addition & 0 deletions playwright/support/sections/QuestionType.ts
Original file line number Diff line number Diff line change
Expand Up @@ -33,4 +33,5 @@ export enum GridSubtype {
export enum LinearScaleSubtype {
Numbers = 'Numbers',
Rating = 'Rating',
Promoter = 'Promoter score',
}
15 changes: 11 additions & 4 deletions src/components/Questions/QuestionLinearScale.vue
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
:warningInvalid="answerType.warningInvalid"
:errorMessage="errorMessage"
v-on="commonListeners">
<template #actions>
<template v-if="!isPromoter" #actions>
<NcActionInput
v-if="!isRating"
:modelValue="optionsLowest"
Expand Down Expand Up @@ -206,7 +206,10 @@ import {
QUESTION_PROPS,
useQuestion,
} from '../../composables/useQuestion.ts'
import { LinearScaleType } from '../../models/Constants.ts'
import {
getLinearScaleDefaultLabels,
LinearScaleType,
} from '../../models/Constants.ts'
import { getRatingIcon, RATING_ICONS } from '../../models/RatingIcons.ts'

type LinearScaleExtraSettings = {
Expand Down Expand Up @@ -259,11 +262,14 @@ export default defineComponent({
? t('forms', 'Highest rating')
: t('forms', 'Highest value'),
)
const isPromoter = computed<boolean>(
() => extraSettings.value.questionType === LinearScaleType.Promoter,
)
const lowest = ref<{ $refs: { input: HTMLTextAreaElement } } | null>(null)
const highest = ref<{ $refs: { input: HTMLTextAreaElement } } | null>(null)

const defaultLowestLabel = t('forms', 'Strongly disagree')
const defaultHighestLabel = t('forms', 'Strongly agree')
const { lowest: defaultLowestLabel, highest: defaultHighestLabel } =
getLinearScaleDefaultLabels(extraSettings.value.questionType)

const optionsLowest = computed<number>({
get: () => {
Expand Down Expand Up @@ -443,6 +449,7 @@ export default defineComponent({
ratingIcons: RATING_ICONS,
ratingValue,
onRatingIconChange,
isPromoter,
validate,
onChange,
onOptionsLowestChange,
Expand Down
Loading
Loading