Skip to content
Merged
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
2 changes: 1 addition & 1 deletion ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ The TypeScript library (`@correlaid/formtransform`), split into **format modules

- **`src/instrument/`** — the parsed survey model (`types.ts`) and its parsers (`fromXlsform.ts`, `fromLstsv.ts`). Shared by every pipeline; it imports no format module or pipeline. See [The Instrument model](#the-instrument-model-69).

- **`src/conventions/`** — one module per registry convention (`other.ts`, `fromFile.ts`, `exclusive.ts`, `grid.ts`, `metadata.ts`). Each reads its values from `src/generated/conventions` and exposes helpers; every format module and pipeline imports them from here. No convention value (suffix, choice code, label, prefix) is written out anywhere else, which `tests/ts/unit/conventionLiterals.test.ts` enforces.
- **`src/conventions/`** — one module per registry convention (`other.ts`, `fromFile.ts`, `exclusive.ts`, `grid.ts`, `metadata.ts`). Each reads its values from `src/generated/conventions` and exposes helpers; every format module and pipeline imports them from here. No convention value (suffix, choice code, label, prefix) is written out anywhere else, which `tests/ts/unit/conventionLiterals.test.ts` enforces. `questionTheme.ts` is the one module for a registry field rather than a convention: an appearance's LimeSurvey question theme (`lsQuestionTheme`), shared by the forward emitter and the reverse type resolver.

#### Pipelines

Expand Down
11 changes: 6 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -334,11 +334,12 @@ codes (`DE`). Any other code (a 12-digit regional key, `059700040040`) gets a
file is reordered or rows are added or removed (`convention:externalCodeList`,
`limesurveyCodes`). The mapping beside the TSV (see `--sanitize` below) records
each derived code, and `lstsv2ddi --data` writes the file's own codes back.
`appearance: minimal` or `autocomplete` makes the question a LimeSurvey
dropdown instead of a radio list. LimeSurvey's dropdown has no search: its
`cssclass` `cdlvocab-<vocabulary>` records where the options came from (the
way back reads it), and it is where a LimeSurvey theme can hook in a
searchable dropdown. formtransform ships no such theme.
`appearance: minimal` makes the question a LimeSurvey dropdown instead of a
radio list. `appearance: autocomplete` makes it a dropdown the respondent can
search by typing: LimeSurvey's core question theme `bootstrap_dropdown` with
`show_search=true` (no plugin needed), which suits a long list. Its `cssclass`
`cdlvocab-<vocabulary>` only records where the options came from (the way
back reads it).

An exclusive answer in a `select_multiple` ("Keine Angabe", "Nichts davon")
is marked with an `exclusive` column (`yes`) on the choices sheet, not a
Expand Down
11 changes: 7 additions & 4 deletions codegen/emit_ts.py
Original file line number Diff line number Diff line change
Expand Up @@ -259,8 +259,11 @@ def generate_appearances(registry: dict[str, Any], output: Path):
" lsTypeOverride?: string;",
" /** False when a row bearing this appearance stores no response (matrix header). */",
" carriesData?: boolean;",
" /** False when the way back from LimeSurvey writes another appearance for its override. */",
" lsReverse?: boolean;",
" /**",
" * LimeSurvey question theme the appearance selects: `name` goes to the Q row's",
" * `question_theme_name`, each of `attributes` to a column of its own.",
" */",
" lsQuestionTheme?: { name: string; attributes?: Record<string, string> };",
"}",
"",
"export const APPEARANCES: Record<string, AppearanceSpec> = {",
Expand Down Expand Up @@ -302,8 +305,8 @@ def expand_types(types: list[str]) -> list[str]:
# Only emitted when explicitly false — absence means "carries data".
if data.get("carriesData") is False:
lines.append(" carriesData: false,")
if data.get("lsReverse") is False:
lines.append(" lsReverse: false,")
if data.get("lsQuestionTheme"):
lines.append(f" lsQuestionTheme: {json.dumps(data['lsQuestionTheme'])},")
lines.append(" },")
lines.append("};")
lines.append("")
Expand Down
4 changes: 2 additions & 2 deletions registry/conventions/externalCodeList.jsonld
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,9 @@
"xlsformTypePattern": "^select_(one|multiple)_from_file (?P<filename>[^ ]+\\.csv)$",
"ddiVocabFromFilename": "stripExtension",
"ddiEmission": "concept[@vocab='<vocab>'] in place of inline catgry; catgry MUST NOT be emitted",
"limesurveyEmission": "base select (L/M) with the vocabulary's options inlined as A/SQ rows + cssclass='cdlvocab-<vocab>' carrying provenance (a registered LimeSurvey question attribute, so it survives import). appearance minimal or autocomplete makes a select_one a dropdown (!) instead of a radio list",
"limesurveyEmission": "base select (L/M) with the vocabulary's options inlined as A/SQ rows + cssclass='cdlvocab-<vocab>' carrying provenance (a registered LimeSurvey question attribute, so it survives import). appearance minimal makes a select_one a dropdown (!) instead of a radio list; appearance autocomplete makes it a searchable dropdown: ! with LimeSurvey's core question theme bootstrap_dropdown and show_search=true (appearance:autocomplete lsQuestionTheme), which suits a long list",
"limesurveyCssClassPrefix": "cdlvocab-",
"limesurveyCssClassPurpose": "A machine hook, not styling: it records which vocabulary the options came from (the way back reads it as select_*_from_file <vocab>.csv), and it is where a LimeSurvey theme can attach a searchable dropdown to a long list (`.cdlvocab-<vocab> select`). formtransform ships no such theme",
"limesurveyCssClassPurpose": "A machine hook, not styling: it records which vocabulary the options came from (the way back reads it as select_*_from_file <vocab>.csv). It has no styling effect and is not needed for search: the searchable dropdown comes from appearance autocomplete",
"limesurveyCodes": {
"rule": "An option code that already fits LimeSurvey (convention:sanitization choiceCode: pattern and maxLength) is kept. Every other one gets a code derived from the code itself, never from its row: hash(code) in base 36, maxLength characters. The codes are the same whatever the order of the file or which rows are added or removed; a collision (with a kept code or an earlier hashed one, case-insensitively, codes taken in sorted order) re-hashes `<code><collisionSeparator><n>`, n = 1, 2, …",
"hash": "fnv1a32",
Expand Down
9 changes: 7 additions & 2 deletions registry/root.jsonld
Original file line number Diff line number Diff line change
Expand Up @@ -137,9 +137,14 @@
"select_one",
"select_one_from_file"
],
"lsEffect": "Override LS type from L to ! (a dropdown; LimeSurvey has no built-in search, see convention:externalCodeList limesurveyCssClassPurpose)",
"lsEffect": "Override LS type from L to ! with LimeSurvey's core question theme bootstrap_dropdown and its show_search attribute: a dropdown the respondent can search by typing",
"lsTypeOverride": "!",
"lsReverse": false
"lsQuestionTheme": {
"name": "bootstrap_dropdown",
"attributes": {
"show_search": "true"
}
}
},
{
"@id": "appearance:multiline",
Expand Down
6 changes: 3 additions & 3 deletions registry/schema.jsonld
Original file line number Diff line number Diff line change
Expand Up @@ -899,13 +899,13 @@
],
"description": "False when a row bearing this appearance is presentation-only and stores no response (the matrix header row): it must not become a DDI variable. Absent means the row carries data as usual."
},
"lsReverse": {
"type": "boolean",
"lsQuestionTheme": {
"type": "object",
"required": false,
"consumedBy": [
"ls-transformer"
],
"description": "False when the way back from LimeSurvey must not write this appearance for its lsTypeOverride, because another appearance has the same override (autocomplete and minimal both give `!`; the way back writes minimal). Absent means it does."
"description": "`{name, attributes?}`: the LimeSurvey question theme this appearance selects, written to the Q row as `question_theme_name` = `name`, plus each of `attributes` (theme attribute → value) as a column of its own; LimeSurvey's TSV import sets the theme from `question_theme_name` and stores the other columns as question attributes. Applies where `validForTypes` allows, together with `lsTypeOverride` if any (autocomplete: `!` + bootstrap_dropdown + show_search=true). The way back writes this appearance for a Q row whose `question_theme_name` and attributes match (and whose type is `lsTypeOverride`, when set); a row with the override but not the theme reads back as the appearance that has the override and no theme (minimal)."
}
}
},
Expand Down
53 changes: 53 additions & 0 deletions src/conventions/questionTheme.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
/**
* An appearance can select a LimeSurvey question theme (registry Appearance
* `lsQuestionTheme`): `name` goes to the Q row's `question_theme_name`, each
* theme attribute to a column of its own. `autocomplete` → `!` +
* `bootstrap_dropdown` + `show_search=true`, LimeSurvey's searchable dropdown
* (#226). LimeSurvey's TSV import sets the theme from `question_theme_name`
* and stores the other columns as question attributes.
*/
import { APPEARANCES } from '../generated/Appearances.js';

type Row = Record<string, string>;

/** The structure-TSV column naming a Q row's LimeSurvey question theme. */
export const QUESTION_THEME_COLUMN = 'question_theme_name';

function cell(row: Row, key: string): string {
return (row[key] ?? '').trim();
}

/** Appearances that select a LimeSurvey question theme (registry `lsQuestionTheme`). */
const THEMED_APPEARANCES = Object.entries(APPEARANCES).filter(
([, spec]) => spec.lsQuestionTheme,
);

/** A theme attribute value as LimeSurvey may store a boolean (`true` / `1`). */
function themeValue(value: string): string {
const v = value.trim().toLowerCase();
return v === '1' ? 'true' : v;
}

/**
* The appearance whose question theme and theme attributes this Q row carries
* (`!` + `bootstrap_dropdown` + `show_search=true` → `autocomplete`), if any.
*/
export function themedAppearanceOf(
lsCode: string,
base: string,
row: Row,
): string | undefined {
const theme = cell(row, QUESTION_THEME_COLUMN);
if (!theme) return undefined;
for (const [name, spec] of THEMED_APPEARANCES) {
const t = spec.lsQuestionTheme!;
if (t.name !== theme) continue;
if (spec.lsTypeOverride && spec.lsTypeOverride !== lsCode) continue;
if (spec.validForTypes && !spec.validForTypes.includes(base)) continue;
const attrs = Object.entries(t.attributes ?? {});
if (attrs.every(([k, v]) => themeValue(cell(row, k)) === themeValue(v))) {
return name;
}
}
return undefined;
}
11 changes: 7 additions & 4 deletions src/generated/Appearances.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,11 @@ export interface AppearanceSpec {
lsTypeOverride?: string;
/** False when a row bearing this appearance stores no response (matrix header). */
carriesData?: boolean;
/** False when the way back from LimeSurvey writes another appearance for its override. */
lsReverse?: boolean;
/**
* LimeSurvey question theme the appearance selects: `name` goes to the Q row's
* `question_theme_name`, each of `attributes` to a column of its own.
*/
lsQuestionTheme?: { name: string; attributes?: Record<string, string> };
}

export const APPEARANCES: Record<string, AppearanceSpec> = {
Expand All @@ -28,9 +31,9 @@ export const APPEARANCES: Record<string, AppearanceSpec> = {
supported: true,
behavior: "handled",
validForTypes: ["select_one", "select_one_from_file"],
lsEffect: "Override LS type from L to ! (a dropdown; LimeSurvey has no built-in search, see convention:externalCodeList limesurveyCssClassPurpose)",
lsEffect: "Override LS type from L to ! with LimeSurvey's core question theme bootstrap_dropdown and its show_search attribute: a dropdown the respondent can search by typing",
lsTypeOverride: "!",
lsReverse: false,
lsQuestionTheme: {"name": "bootstrap_dropdown", "attributes": {"show_search": "true"}},
},
"multiline": {
supported: true,
Expand Down
4 changes: 2 additions & 2 deletions src/generated/conventions.json
Original file line number Diff line number Diff line change
Expand Up @@ -428,9 +428,9 @@
"xlsformTypePattern": "^select_(one|multiple)_from_file (?P<filename>[^ ]+\\.csv)$",
"ddiVocabFromFilename": "stripExtension",
"ddiEmission": "concept[@vocab='<vocab>'] in place of inline catgry; catgry MUST NOT be emitted",
"limesurveyEmission": "base select (L/M) with the vocabulary's options inlined as A/SQ rows + cssclass='cdlvocab-<vocab>' carrying provenance (a registered LimeSurvey question attribute, so it survives import). appearance minimal or autocomplete makes a select_one a dropdown (!) instead of a radio list",
"limesurveyEmission": "base select (L/M) with the vocabulary's options inlined as A/SQ rows + cssclass='cdlvocab-<vocab>' carrying provenance (a registered LimeSurvey question attribute, so it survives import). appearance minimal makes a select_one a dropdown (!) instead of a radio list; appearance autocomplete makes it a searchable dropdown: ! with LimeSurvey's core question theme bootstrap_dropdown and show_search=true (appearance:autocomplete lsQuestionTheme), which suits a long list",
"limesurveyCssClassPrefix": "cdlvocab-",
"limesurveyCssClassPurpose": "A machine hook, not styling: it records which vocabulary the options came from (the way back reads it as select_*_from_file <vocab>.csv), and it is where a LimeSurvey theme can attach a searchable dropdown to a long list (`.cdlvocab-<vocab> select`). formtransform ships no such theme",
"limesurveyCssClassPurpose": "A machine hook, not styling: it records which vocabulary the options came from (the way back reads it as select_*_from_file <vocab>.csv). It has no styling effect and is not needed for search: the searchable dropdown comes from appearance autocomplete",
"limesurveyCodes": {
"rule": "An option code that already fits LimeSurvey (convention:sanitization choiceCode: pattern and maxLength) is kept. Every other one gets a code derived from the code itself, never from its row: hash(code) in base 36, maxLength characters. The codes are the same whatever the order of the file or which rows are added or removed; a collision (with a kept code or an earlier hashed one, case-insensitively, codes taken in sorted order) re-hashes `<code><collisionSeparator><n>`, n = 1, 2, …",
"hash": "fnv1a32",
Expand Down
4 changes: 2 additions & 2 deletions src/generated/conventions.ts
Original file line number Diff line number Diff line change
Expand Up @@ -437,9 +437,9 @@ const conventions = {
"xlsformTypePattern": "^select_(one|multiple)_from_file (?P<filename>[^ ]+\\.csv)$",
"ddiVocabFromFilename": "stripExtension",
"ddiEmission": "concept[@vocab='<vocab>'] in place of inline catgry; catgry MUST NOT be emitted",
"limesurveyEmission": "base select (L/M) with the vocabulary's options inlined as A/SQ rows + cssclass='cdlvocab-<vocab>' carrying provenance (a registered LimeSurvey question attribute, so it survives import). appearance minimal or autocomplete makes a select_one a dropdown (!) instead of a radio list",
"limesurveyEmission": "base select (L/M) with the vocabulary's options inlined as A/SQ rows + cssclass='cdlvocab-<vocab>' carrying provenance (a registered LimeSurvey question attribute, so it survives import). appearance minimal makes a select_one a dropdown (!) instead of a radio list; appearance autocomplete makes it a searchable dropdown: ! with LimeSurvey's core question theme bootstrap_dropdown and show_search=true (appearance:autocomplete lsQuestionTheme), which suits a long list",
"limesurveyCssClassPrefix": "cdlvocab-",
"limesurveyCssClassPurpose": "A machine hook, not styling: it records which vocabulary the options came from (the way back reads it as select_*_from_file <vocab>.csv), and it is where a LimeSurvey theme can attach a searchable dropdown to a long list (`.cdlvocab-<vocab> select`). formtransform ships no such theme",
"limesurveyCssClassPurpose": "A machine hook, not styling: it records which vocabulary the options came from (the way back reads it as select_*_from_file <vocab>.csv). It has no styling effect and is not needed for search: the searchable dropdown comes from appearance autocomplete",
"limesurveyCodes": {
"rule": "An option code that already fits LimeSurvey (convention:sanitization choiceCode: pattern and maxLength) is kept. Every other one gets a code derived from the code itself, never from its row: hash(code) in base 36, maxLength characters. The codes are the same whatever the order of the file or which rows are added or removed; a collision (with a kept code or an earlier hashed one, case-insensitively, codes taken in sorted order) re-hashes `<code><collisionSeparator><n>`, n = 1, 2, …",
"hash": "fnv1a32",
Expand Down
16 changes: 13 additions & 3 deletions src/instrument/lstsvTypes.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
*/
import { APPEARANCES } from '../generated/Appearances.js';
import { TYPE_MAPPINGS } from '../generated/TypeMappings.js';
import { themedAppearanceOf } from '../conventions/questionTheme.js';

type Row = Record<string, string>;

Expand Down Expand Up @@ -83,11 +84,14 @@ for (const [xfType, m] of Object.entries(TYPE_MAPPINGS)) {
}
}

/** Appearance name → LS type-override code it produces (e.g. `minimal` → `!`). */
/**
* Appearance name → LS type-override code it produces (e.g. `minimal` → `!`).
* An appearance that also selects a question theme is told apart by that
* theme (see `themedAppearanceOf`), so the bare code reads as the other one.
*/
const APPEARANCE_BY_OVERRIDE: Record<string, string> = {};
for (const [name, spec] of Object.entries(APPEARANCES)) {
// `lsReverse: false`: another appearance has the override (autocomplete → `!` → minimal).
if (spec.lsTypeOverride && spec.lsReverse !== false) {
if (spec.lsTypeOverride && !spec.lsQuestionTheme) {
APPEARANCE_BY_OVERRIDE[spec.lsTypeOverride] = name;
}
}
Expand All @@ -100,6 +104,12 @@ export interface ResolvedType {

/** Resolve a Q-row's `type/scale` (+ attribute hints) to an XLSForm type. */
export function resolveType(lsCode: string, row: Row): ResolvedType {
const resolved = resolveBaseType(lsCode, row);
const themed = themedAppearanceOf(lsCode, resolved.base, row);
return themed ? { ...resolved, appearance: themed } : resolved;
}

function resolveBaseType(lsCode: string, row: Row): ResolvedType {
const dateFormat = cell(row, 'date_format');
const overrideAppearance = APPEARANCE_BY_OVERRIDE[lsCode];
if (overrideAppearance) {
Expand Down
9 changes: 9 additions & 0 deletions src/lstsv/columns.ts
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,13 @@ export const BASE_COLUMNS = [
* - `other_replace_text`: the label of the native "other" answer's text box,
* carrying the XLSForm `<question>_other` companion's label (convention:other).
*
* - `question_theme_name`, `show_search`: the LimeSurvey question theme an
* appearance selects and that theme's attributes (registry
* `lsQuestionTheme`): `autocomplete` → `bootstrap_dropdown` with
* `show_search=true`, a searchable dropdown. LimeSurvey's import sets the
* theme from `question_theme_name` and stores the other columns as
* question attributes.
*
* A registry attribute missing here would be dropped silently; a test checks
* the registry against this list.
*/
Expand All @@ -72,6 +79,8 @@ export const ATTRIBUTE_COLUMNS = [
'array_filter',
'em_validation_q_tip',
'other_replace_text',
'question_theme_name',
'show_search',
] as const;

export type BaseColumn = (typeof BASE_COLUMNS)[number];
Expand Down
Loading
Loading