Portal Questions In Main Form Developer Guide

Portal questions in the main form - Developer Guide

How the portal's New ticket page can ask its custom field questions in the main column, between the subject and the description, instead of in the side panel - and the layout work underneath, because the page was built never to scroll. Built for #218 part C (changelog #2720, 4.9.0).

For what it does from a user's point of view, see Custom ticket fields - where the portal asks. The agreed spec is Simpler ticket and task forms - design, part C. How custom fields themselves work (definitions, required rules, storage) is in Custom ticket fields - Developer Guide; the portal's general rules are in the Self-Service Developer Guide.

---

The shape of it

One install-wide setting and one page. Nothing about loading, keeping or submitting answers changed:

File	Job
includes/services/ticket_fields.php	TicketFieldsService::portalAskPlace() - reads ticket_portal_field_ask, answers 'side' or 'main'
tickets/settings/index.php	The Where the portal asks these questions dropdown on Tickets -> Settings -> Custom fields, and its load and save
tickets/settings/manifest.php	Lists ticket_portal_field_ask under the Custom fields tab, which is what lets that tab's permission save it
self-service/new-ticket.php	The feature. Reads the setting before the header, adds the body class, prints the questions in one place or the other, and the .ss-ask-main CSS
lang/*/tickets.php	tickets.settings.custom_fields.portal_ask_*

Commits: d990ca02b (the setting and the first layout), then three layout fixes found by looking at it - ba7e71b1c (two to a row, no gap above Description), ff7fdc881 (the page could not scroll), 5bb0e4a1d (the editor lines up with the side panel). Each is explained below.

---

The setting

system_settings.ticket_portal_field_ask, side or main. Install-wide, like the other portal settings, and like ticket_portal_field_answers (Where requesters see their answers) that sits beside it.

    public static function portalAskPlace(PDO $conn): string
    {
        try {
            $v = $conn->query("SELECT setting_value FROM system_settings WHERE setting_key = 'ticket_portal_field_ask'")->fetchColumn();
            return $v === 'main' ? 'main' : 'side';
        } catch (Throwable) {
            return 'side';
        }
    }

side is never saved as a requirement. A missing row, an empty value, anything unexpected and a failed query all answer side, which is the page as it was before 4.9.0. Only the exact string main changes anything. So an upgrade needs no migration and no DB Verify entry - an install that has never seen the setting behaves as before.

The settings screen shares one loader and saver with the answers setting. The two used to be separate copies; now they are rows in a table:

        [['portalFieldAnswers', 'ticket_portal_field_answers', ['off', 'header', 'side'], 'header'],
         ['portalFieldAsk', 'ticket_portal_field_ask', ['side', 'main'], 'side']].forEach(([id, key, allowed, fallback]) => {
            const sel = document.getElementById(id);
            if (!sel) return;
            fetch(API_SETTINGS + 'get_system_settings.php').then(r => r.json()).then(d => {
                const v = d && d.settings ? d.settings[key] : '';
                sel.value = allowed.includes(v) ? v : fallback;
            }).catch(() => {});

⚠️ The fallback is written twice and must agree. The comment above that block says it: Never saved = 'side'; must match TicketFieldsService::portalAskPlace(). If one side defaulted to main and the other to side, the dropdown would show one placement while the portal used the other.

The save goes through the generic api/settings/save_system_settings.php. What lets the Custom fields tab's permission write this key is one line in the manifest - includes/settings_keys.php builds its key-to-owner map from every tab's setting_keys:

            'setting_keys' => ['ticket_portal_field_answers', 'ticket_portal_field_ask', 'ticket_department_shown', 'ticket_department_default'],

Leave the key out of the manifest and the save is refused for anyone who holds only the Custom fields capability.

---

Reading it before the header

$bodyClass    = 'portal-app';

// GH #218 part C: where the questions are asked. 'main' puts the request type and
// the questions in the main column, between the subject and the description, and
// the PAGE scrolls instead of the editor filling the height - several questions
// and their error messages need room the app shell cannot give them. Read here,
// before header.php, because it decides the body class. Same order the header
// uses: session first, then config. A failure keeps today's side panel.
if (session_status() === PHP_SESSION_NONE) session_start();
require_once __DIR__ . '/../config.php';
require_once __DIR__ . '/../includes/functions.php';
require_once __DIR__ . '/../includes/services/ticket_fields.php';
try { $ssAskMain = TicketFieldsService::portalAskPlace(connectToDatabase()) === 'main'; }
catch (Throwable) { $ssAskMain = false; }
if ($ssAskMain) $bodyClass .= ' ss-ask-main';

Why it has to be here. Every portal page sets $bodyClass, $pageStyles, $pageHead and $pageScripts and then includes self-service/includes/header.php, which prints <head> and the opening <body class="..."> from them. Once the header has run, the <body> tag has been sent. The one switch that frees the page to scroll is a class on <body> (see below), so the setting has to be known before that include, near the top of the page - not where the questions are printed, much further down.

Why it repeats the header's own start-up. header.php begins with session_start() and require_once config.php. Reading the setting earlier needs a database connection earlier, so the page does the same two steps first, in the same order. Both are idempotent - the session_status() check and require_once - so the header doing them again is harmless.

It runs before sign-in is checked. self-service/includes/auth.php, which redirects a signed-out visitor to the sign-in page, is required from inside the header. So this query also runs for a visitor who is about to be redirected. That is acceptable only because it reads one non-sensitive display setting and prints nothing; do not grow this block into anything that reads or prints user data.

A failure keeps the side panel. portalAskPlace() already catches its own query errors; the outer try also covers connectToDatabase(). A database problem gives the page as it always was, rather than a half-applied layout.

---

One function, printed in one of two places

$ssQuestions = function () { ?>
                <div class="form-group" id="ticketTypeGroup" hidden>
                    <label for="ticketType"><?php echo htmlspecialchars(t('self-service.new_ticket.ticket_type')); ?></label>
                    <select id="ticketType" onchange="loadTicketFields()">
                        <option value=""><?php echo htmlspecialchars(t('self-service.new_ticket.ticket_type_none')); ?></option>
                    </select>
                </div>
                <div id="ticketCustomFields"></div>
<?php };

It is printed first inside the compose grid when the setting is main:

                <div class="compose-body<?php echo $ssAskMain ? ' compose-ask-main' : ''; ?>">
                    <?php if ($ssAskMain): ?>
                    <!-- GH #218 part C, "Main form": the request type and its questions
                         between the subject and the description - the order a person
                         explains a request in. First in the DOM, so a phone stacks them
                         there too. -->
                    <div class="compose-questions" id="composeQuestions"><?php $ssQuestions(); ?></div>
                    <?php endif; ?>

and in the side panel, after Category, otherwise:

                <?php if (!$ssAskMain) $ssQuestions(); ?>

🔑 The same ids in both places is the whole trick. loadTicketFields() and handleSubmit() find the picker and the questions by id, wherever they are:

                    ticket_type_id: (document.getElementById('ticketType') || {}).value || null,
                    custom_fields: window.TicketFields ? TicketFields.collect(document.getElementById('ticketCustomFields')) : {},
``` So the script that fills the questions, keeps answers across a change of type, and sends them, is untouched - and so are validation and storage. A closure rather than two copies of the markup means the two placements cannot drift apart.

**The type picker moves with the questions**, because choosing a type decides which questions are asked. It is still `hidden` until `loadTicketFields()` finds there are types to choose from.

**DOM order is the phone order.** The questions are the grid's first child, so when the grid falls back to one column they come first, then the Description label, the editor, and the side panel with Submit at the bottom. On a desktop the grid places them explicitly (below), so the DOM order only has to be right for the narrow layout.

---

## The layout: why the page could not just take the questions

Read the comments at the top of `$pageStyles` first. The New ticket page is an **app shell**: it fills the viewport exactly, and the editor takes whatever height is left, through a flex chain with `min-height: 0` at every link:

```css
        body.portal-app .portal-layout {
            display: flex;
            flex-direction: column;
            height: calc(100vh - var(--ss-chrome, 48px));   /* the bar, plus the logo band if shown - see self-service.css */
            padding: 20px 24px;
            box-sizing: border-box;
            overflow: hidden;
        }

        .compose-body {
            flex: 1;
            display: grid;
            /* 340, not 300: the panel also carries 32px of padding (the gap to its
               border, and room for its own scrollbar), and at 300 the selects and
               the Confidential note were cramped. The editor takes what is left. */
            grid-template-columns: 1fr 340px;
            grid-template-rows: auto 1fr;   /* label sized to content; editor takes the rest */
            gap: 18px;
            align-items: stretch;
            min-height: 0;
        }

With the side panel that is right: the questions scroll inside the panel (overflow-y: auto), and the editor is as tall as the window allows. Put four questions and their error messages above the editor in that shell and they would have to come out of the editor's height - on a laptop, a toolbar with a sliver under it. So Main form swaps the model: the page scrolls, and the editor gets a height of its own.

All of it is behind .ss-ask-main on <body> or .compose-ask-main on the grid. Without the setting not one of these rules matches, and the side-panel page is the one it was (checked pixel-identical before and after).

1. Release the body and the layout

        /* TRAP: release the BODY too. self-service.css locks `body.portal-app` to
           height 100vh with overflow hidden (the app shell other pages scroll a pane
           inside). Freeing only .portal-layout let it grow, and the body clipped it:
           nothing below the fold could be reached (found by Ed - screenshots taken in
           a window tall enough to hold the whole page never showed it). */
        body.portal-app.ss-ask-main { height: auto; overflow: visible; }
        body.portal-app.ss-ask-main .portal-layout { height: auto; overflow: visible; }
        .ss-ask-main .form-card,
        .ss-ask-main .form-card form,
        .compose-ask-main { flex: none; }

There are two locks, in two files, and both have to go:

• assets/css/self-service.css: body.portal-app { height: 100vh; overflow: hidden; } - shared by every app-shell portal page, where a pane inside scrolls and the page must not.
• This page's own body.portal-app .portal-layout { height: calc(...); overflow: hidden; }.

🔴 This was a real bug in the first build (ff7fdc881). Only the layout was released: .portal-layout grew to fit the form, and the body, still 100vh and overflow: hidden, clipped it. In a short window the description and Submit could not be reached at all. Every screenshot taken while building it was in a window tall enough to hold the whole form, so none of them showed it - it took someone using it on a normal laptop screen. Test a scrolling layout in a window shorter than the page.

Specificity. body.portal-app.ss-ask-main .portal-layout is (0,3,1), so it beats this page's body.portal-app .portal-layout (0,2,1) and the shared stylesheet's body.portal-app .portal-layout wherever the rules sit in the file. The Self-Service Developer Guide has the background: a bare .portal-layout override has lost this fight before.

flex: none on the card, the form and the grid ends the flex chain. In the app shell each was flex: 1 to share out the viewport's height; with the page scrolling there is no fixed height to share, and flex: 1 with min-height: 0 would try to squash them into the old box.

2. Three rows on the left, the panel spanning them

        /* TRAP: the last row is 1fr, not auto. The side panel spans every row and is
           usually the taller column; with three auto rows the grid shared that extra
           height between them, opening gaps above and below "Description". */
        .compose-ask-main { grid-template-rows: auto auto 1fr; }
        .compose-ask-main .compose-questions { grid-column: 1; grid-row: 1; min-width: 0; }
        .compose-ask-main .compose-label-row { grid-row: 2; }
        .compose-ask-main .compose-editor    { grid-row: 3; }

The left column is now questions, then the Description label, then the editor; the side panel keeps its grid-row: 1 / -1 from the base rules and spans all three. Stated placement, not auto-placement, because the base rules explain how a fourth child once went into the wrong cell (#122).

Why 1fr for the last row (ba7e71b1c). The side panel - mailbox, category, priority, Confidential, equipment, attachments, recording, Submit - is usually taller than the left column. A spanning item that is taller than the rows it spans has its extra height shared between those rows. With auto auto auto, part of it went into the questions row and the label row, opening gaps above and below Description. With auto auto 1fr, the two auto rows stay the size of their content and all of the spare height goes to the editor's row.

min-width: 0 on the questions stops a long unbroken answer or option text from forcing the left column wider than 1fr.

3. The editor: a minimum, and stretched to the panel

        /* At least a comfortable box, like the ticket note box; and when the side panel
           is the taller column, the editor stretches down its 1fr row so its bottom
           lines up with the panel's (Ed). How many questions sit above it does not
           matter: few, and the row takes the panel's spare height; many, and the left
           column is the taller one and the editor stays at its minimum. */
        body:not(.ss-compose-full) .compose-ask-main .compose-editor { min-height: 320px; align-self: stretch; }
        .compose-ask-main .compose-side { overflow: visible; align-self: start; }

The first build gave the editor a fixed height: 320px. That left it ending short of the side panel's bottom whenever there were few questions, with a block of empty page beside the panel. 5bb0e4a1d changed it to a minimum plus align-self: stretch, which together with the 1fr row above means:

• Few questions: the left column is shorter than the panel, the 1fr row takes the difference, and the editor stretches down it - its bottom lines up with the panel's.
• Many questions: the left column is the taller one, the row is only as tall as the editor needs, and the editor stays at 320px.

TinyMCE is initialised with height: '100%', and the base rule .compose-editor .tox-tinymce { flex: 1 !important; height: auto !important; } makes the editor chrome fill .compose-editor, so the editor follows its box in both cases.

body:not(.ss-compose-full) leaves the phone's Full screen editor alone, which positions .compose-editor fixed over the whole screen; a 320px minimum there would be meaningless.

The side panel stops scrolling on its own (overflow: visible) because the page scrolls now - two nested scroll areas would trap the wheel. align-self: start keeps it at its natural height at the top of its span instead of being stretched; that is what lets the editor, not the panel, be the thing that lines up.

4. Two questions to a row, one on a phone

        .compose-questions .form-group { margin-bottom: 16px; }
        .compose-questions:empty { display: none; }
        /* Two to a row: every kind of question is one line (text, number, date,
           yes/no, list, address, email), and a date across the whole column is a
           lot of empty box. `display: contents` lets the type picker and each
           question share the one grid. One to a row on a phone. */
        .compose-questions { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); column-gap: 16px; align-items: start; }
        .compose-questions #ticketCustomFields { display: contents; }
        @media (max-width: 640px) { .compose-questions { grid-template-columns: minmax(0, 1fr); } }

• Why two. Every question kind the portal asks is a single line, and the main column on a wide screen is wide. A date picker the width of the whole column is mostly empty box.
• display: contents on #ticketCustomFields. TicketFields.render() draws each question as its own div.form-group.tf-field inside that box, and the type picker is a sibling of the box. Without contents, the grid would have two items - the picker and the whole box of questions - and the questions would sit one under another in the second cell. With it, the box generates no box of its own, so the picker and every question are grid items side by side. The element is still in the DOM with its id, so the scripts that find it are unaffected.
• minmax(0, 1fr), not 1fr, for the same reason as min-width: 0 above: a plain 1fr has an automatic minimum of its content's width, and one long option would make its column wider than the other.
• align-items: start so a question with a hint or an error message under it does not stretch the question beside it.
• One to a row below 640px. A phone has no room for two.
• .compose-questions:empty never matches today. The closure always prints the (hidden) type picker and the #ticketCustomFields box, plus whitespace, so the container is never :empty. When there are no types and no questions it still renders with no visible content, because the picker is hidden and the box is display: contents with nothing in it - but its grid row exists, so the grid's 18px gap still sits above Description.

5. Below 900px: back to DOM order

        @media (max-width: 900px) {
            /* One column: back to DOM order - questions, description, then the panel
               with Submit - the same undoing the block above does for the others. */
            .compose-ask-main .compose-questions,
            .compose-ask-main .compose-label-row,
            .compose-ask-main .compose-editor { grid-column: auto; grid-row: auto; }
        }

The base page already has a 900px block that turns the grid into one column and resets each child's placement to auto - with a long comment about why the placement has to be undone, not just the column count changed. The .compose-ask-main placements above are more specific (0,2,0) than those resets (0,1,0), so without this block they would survive into the one-column layout. Today that would happen to give the same order, but only by accident of the row numbers; this block puts the Main form back on plain auto-placement like the rest of the page, so the four children stack in DOM order - questions, Description, editor, side panel with Submit - whatever is added later.

Note that the block resets the children's placement, not the grid's grid-template-rows: auto auto 1fr. In one column the rows are filled in order, the side panel goes into an implicit fourth row, and with the page's height auto the 1fr row is simply as tall as the editor.

🔑 It sits at 900px, the width where the single-column layout starts, not at a phone width - the base CSS records what happened when a fix for this page's single-column layout was put one breakpoint too low.

---

A submit error, now that the page scrolls

            } else {
                errEl.textContent = data.error;
                errEl.style.display = 'block';
                errEl.scrollIntoView({ block: 'nearest' });   // the Main form scrolls (GH #218): the error is above Submit

The error box #errorMsg sits above the form card. In the app shell it was always on screen. With the page scrolling, a requester who has scrolled down to Submit would press it, see nothing happen, and not know the server had refused. Both error paths - a refusal from the server and a failed request - now scroll the box into view. block: 'nearest' does nothing when it is already visible, so the side-panel page is unaffected.

A refused submit keeps the subject, the description and every answer, because nothing on the page is redrawn on an error.

---

Traps

• Anything that changes the <body> class must be decided before header.php is included. See Reading it before the header.
• Releasing the layout is not enough. body.portal-app is locked in self-service.css; a scrolling variant of any app-shell portal page has to release the body too.
• Check a scrolling layout in a short window. A tall window hides an unreachable bottom half.
• Keep the ids. The questions move by printing the same closure in a different place. Renaming #ticketType or #ticketCustomFields in one placement, or adding a wrapper the scripts query by a different id, breaks loading and submitting answers in that placement only.
• Do not drop display: contents without changing how the questions are rendered, or the two-to-a-row grid becomes one cell holding everything.

---

Testing it

There is no automated test for the placement: nothing under tests/ refers to ticket_portal_field_ask, portalAskPlace() or .ss-ask-main. (tests/portal-field-answers.php covers the neighbouring where requesters see their answers setting, not this one.) It was checked by hand in a browser on a test install with four sample questions, at 1400px, 520px and, for the scrolling fix, 1400x600, 1900x900 and 520x800. To check it again:

1. Make at least two custom fields Ask the requester, one of them Required on create, and if you can, two ticket types that ask different questions.
2. Tickets -> Settings -> Custom fields -> Where the portal asks these questions: In the main form. Reload and check the dropdown kept the choice.
3. Sign in to the portal and open New ticket in a window shorter than the page (around 1400x600). Expect: Subject, then the type picker and the questions two to a row, then Description, then the editor; the side panel on the right without the questions; and the page scrolls down to Submit.
4. With one or two questions the editor's bottom lines up with the side panel's. With many, the editor is 320px tall and the left column is the longer one.
5. Choose a type, answer a question, change the type: answers to questions the new type still asks are kept.
6. Scroll down and submit with a required question empty: the error scrolls into view, and the subject, description and answers are all still there.
7. At about 520px wide: one question to a row; the order is questions, Description, editor, then the panel with Submit at the bottom. On a phone, Full screen on the editor still opens and closes.
8. Set the setting back to In the side panel: the page is exactly as before - questions in the panel, the editor filling the height, the page not scrolling.

---

Related

• Custom ticket fields - the user page, including both portal settings
• Custom ticket fields - Developer Guide - definitions, required rules, storage
• Self-Service Developer Guide - the portal's rules and layout traps
• Mobile-friendly self-service - the phone layout and the Full screen editor
• Simpler ticket and task forms - design - #218, parts A to D