feat: add/clone question at position

Signed-off-by: Christian Hartmann <chris-hartmann@gmx.de>

Author: Chartman123

docs/API_v3.md

@@ -370,6 +370,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. |
+  | _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.
 
 ```
@@ -506,6 +507,10 @@ Creates a clone of a question with all its options.
   |-----------|---------|-------------|
   | _formId_ | Integer | ID of the form containing the question |
   | _questionId_ | Integer | ID of the question to clone |
+- Parameters:
+  | Parameter | Type | Optional | Description |
+  |-----------|---------|----------|-------------|
+  | _position_ | Integer | yes | _(optional)_ 1-based position to insert the cloned question. When omitted the clone is appended at the end. |
 - Response: Returns cloned question object with the new ID set.
 
 ```

lib/Controller/ApiController.php

@@ -485,6 +485,7 @@ public function getQuestion(int $formId, int $questionId): DataResponse {
 	 * @param FormsQuestionGridCellType $subtype the new question subtype
 	 * @param string $text the new question title
 	 * @param ?int $fromId (optional) id of the question that should be cloned
+	 * @param ?int $position (optional) the position of the new question
 	 * @return DataResponse<Http::STATUS_CREATED, FormsQuestion, array{}>
 	 * @throws OCSBadRequestException Invalid type
 	 * @throws OCSBadRequestException Datetime question type no longer supported
@@ -499,7 +500,7 @@ public function getQuestion(int $formId, int $questionId): DataResponse {
 	#[NoAdminRequired()]
 	#[BruteForceProtection(action: 'form')]
 	#[ApiRoute(verb: 'POST', url: '/api/v3/forms/{formId}/questions')]
-	public function newQuestion(int $formId, ?string $type = null, ?string $subtype = null, string $text = '', ?int $fromId = null): DataResponse {
+	public function newQuestion(int $formId, ?string $type = null, ?string $subtype = null, string $text = '', ?int $fromId = null, ?int $position = null): DataResponse {
 		$form = $this->formsService->getFormIfAllowed($formId, Constants::PERMISSION_EDIT);
 		$this->formsService->obtainFormLock($form);
 
@@ -526,13 +527,20 @@ public function newQuestion(int $formId, ?string $type = null, ?string $subtype
 				throw new OCSBadRequestException('Datetime question type no longer supported');
 			}
 
-			// Retrieve all active questions sorted by Order. Takes the order of the last array-element and adds one.
+			// Retrieve all active questions sorted by Order.
 			$questions = $this->questionMapper->findByForm($formId);
-			$lastQuestion = array_pop($questions);
-			if ($lastQuestion) {
-				$questionOrder = $lastQuestion->getOrder() + 1;
+
+			if ($position !== null) {
+				$position = $this->shiftQuestionsForInsert($questions, $position);
+				$questionOrder = $position;
 			} else {
-				$questionOrder = 1;
+				// Append at the end
+				$lastQuestion = array_pop($questions);
+				if ($lastQuestion) {
+					$questionOrder = $lastQuestion->getOrder() + 1;
+				} else {
+					$questionOrder = 1;
+				}
 			}
 
 			$question = new Question();
@@ -574,7 +582,13 @@ public function newQuestion(int $formId, ?string $type = null, ?string $subtype
 
 			$questionData = $sourceQuestion->read();
 			unset($questionData['id']);
-			$questionData['order'] = end($allQuestions)->getOrder() + 1;
+
+			if ($position !== null) {
+				$position = $this->shiftQuestionsForInsert($allQuestions, $position);
+				$questionData['order'] = $position;
+			} else {
+				$questionData['order'] = end($allQuestions)->getOrder() + 1;
+			}
 
 			$newQuestion = Question::fromParams($questionData);
 			$this->questionMapper->insert($newQuestion);
@@ -1992,4 +2006,36 @@ private function handleOwnerTransfer(Form $form, int $formId, string $currentUse
 		$this->formMapper->update($form);
 		return new DataResponse($form->getOwnerId());
 	}
+
+	/**
+	 * Shift existing question orders to make room for an insertion at $position.
+	 * Normalizes the given $position to the valid range and updates all questions
+	 * with order >= $position by incrementing their order by one.
+	 *
+	 * @param Question[] $questions
+	 * @param int $position 1-based desired position
+	 * @return int normalized position
+	 */
+	private function shiftQuestionsForInsert(array $questions, int $position): int {
+		$maxOrder = 0;
+		if (count($questions) > 0) {
+			$maxOrder = end($questions)->getOrder();
+		}
+		if ($position < 1) {
+			$position = 1;
+		}
+		if ($position > $maxOrder + 1) {
+			$position = $maxOrder + 1;
+		}
+
+		for ($i = count($questions) - 1; $i >= 0; $i--) {
+			$q = $questions[$i];
+			if ($q->getOrder() >= $position) {
+				$q->setOrder($q->getOrder() + 1);
+				$this->questionMapper->update($q);
+			}
+		}
+
+		return $position;
+	}
 }

openapi.json

@@ -1686,6 +1686,13 @@
                                         "nullable": true,
                                         "default": null,
                                         "description": "(optional) id of the question that should be cloned"
+                                    },
+                                    "position": {
+                                        "type": "integer",
+                                        "format": "int64",
+                                        "nullable": true,
+                                        "default": null,
+                                        "description": "(optional) the position of the new question"
                                     }
                                 }
                             }