mirror of
https://github.com/wekan/wekan.git
synced 2026-11-20 09:45:04 -05:00
Nullboard's formatter writes its JSON as text, so the nested writer reads it as JSON (text: true) and ends the file with its newline. Its lists - the board's, then one per title of a list its cards name that is not exported - are found over the whole board, so every page has the same lists, and the pages come list by list with those cards grouped by the title (byList: 'listIdsThenTitles'). tests/exportPaging.test.cjs checks every page size; the import/export audit (173) and the admin-only custom field specs (12) pass. Thanks to xet7 !
193 lines
8.9 KiB
JavaScript
193 lines
8.9 KiB
JavaScript
// Nullboard board files (.nbx), read and written in plain JavaScript so
|
||
// tests/nullboardFormat.test.cjs runs the round trip in Node.
|
||
//
|
||
// Nullboard (apankrat/nullboard, nullboard.html) exports a board as plain
|
||
// JSON despite the .nbx extension: JSON.stringify of one board object, or of
|
||
// an array of them for "Export all boards". Its importer, checkImport(),
|
||
// requires every board to have the keys format, id, revision, title and lists,
|
||
// a non-empty id and revision, an array of lists, and format 20190412
|
||
// (NB.blobVersion); anything else is refused. A board is
|
||
// { format: 20190412, id: <epoch ms>, revision: <int>, title,
|
||
// lists: [ { title, notes: [ { text, raw, min } ] } ] }
|
||
// and that is all there is: no dates, labels, people, comments, attachments
|
||
// or checklists.
|
||
//
|
||
// A note is free text with line breaks. It maps to a card:
|
||
// list -> a list, in order (a repeated or empty title is
|
||
// made unique, since WeKan matches lists by title)
|
||
// note text, first line -> the card's title (the first non-blank line)
|
||
// note text, the rest -> the card's description
|
||
// raw: true -> the label "raw" (a raw note is drawn without a
|
||
// card frame, as a heading inside the list)
|
||
// min: true -> reported once: collapsed is Nullboard's view
|
||
// state and a WeKan card has no collapsed state
|
||
// board title -> the board's title
|
||
// An array of boards imports its first board; the others are reported, since
|
||
// one import creates one board.
|
||
//
|
||
// Export writes one board object Nullboard's importer accepts. A note's text
|
||
// is the card title, then the description on the following lines, then each
|
||
// checklist as a title line and "[ ]" / "[x]" item lines, so checklist items
|
||
// survive as readable text. A card labelled "raw" becomes a raw note. Other
|
||
// labels, dates, people and comments have no place in a Nullboard note and
|
||
// are not written.
|
||
|
||
export const NULLBOARD_FORMAT = 20190412;
|
||
export const NULLBOARD_RAW_LABEL = 'raw';
|
||
import { pagingOf } from './exportPaging.js';
|
||
const REQUIRED = ['format', 'id', 'revision', 'title', 'lists'];
|
||
|
||
// The checks of Nullboard's own checkImport(), with its messages.
|
||
function checkBoard(board, at) {
|
||
if (!board || typeof board !== 'object' || Array.isArray(board)) {
|
||
throw new Error(`Nullboard file${at}: a board must be a JSON object`);
|
||
}
|
||
for (const key of REQUIRED) {
|
||
if (!Object.prototype.hasOwnProperty.call(board, key)) {
|
||
throw new Error(`Nullboard file${at}: required board properties are missing (${key})`);
|
||
}
|
||
}
|
||
if (!board.id || !board.revision || !Array.isArray(board.lists)) {
|
||
throw new Error(`Nullboard file${at}: required board properties are empty`);
|
||
}
|
||
if (Number(board.format) !== NULLBOARD_FORMAT) {
|
||
throw new Error(`Nullboard file${at}: unsupported blob format "${board.format}", expecting "${NULLBOARD_FORMAT}"`);
|
||
}
|
||
}
|
||
|
||
// The first non-blank line is the title; everything after it the description.
|
||
export function splitNoteText(text) {
|
||
const lines = String(text).split(/\r\n|\r|\n/);
|
||
const first = lines.findIndex(line => line.trim());
|
||
if (first === -1) return { title: '', description: '' };
|
||
return { title: lines[first].trim(), description: lines.slice(first + 1).join('\n').replace(/\s+$/, '') };
|
||
}
|
||
|
||
export function parseNullboard(input) {
|
||
let data = input;
|
||
if (typeof input === 'string') {
|
||
try {
|
||
data = JSON.parse(input.replace(/^/, ''));
|
||
} catch (error) {
|
||
throw new Error('Nullboard file is not valid JSON');
|
||
}
|
||
}
|
||
const boards = Array.isArray(data) ? data : [data];
|
||
if (!boards.length) throw new Error('Nullboard file holds no board');
|
||
boards.forEach((board, index) => checkBoard(board, Array.isArray(data) ? ` board ${index + 1}` : ''));
|
||
const [board] = boards;
|
||
const unsupported = boards.slice(1).map((other, index) => ({
|
||
path: `/${index + 1}`,
|
||
reason: `Nullboard board "${String(other.title || '')}" is not imported: one import creates one board, import its own export`,
|
||
}));
|
||
|
||
const columns = [];
|
||
const tasks = [];
|
||
let collapsed = 0;
|
||
board.lists.forEach((list, listIndex) => {
|
||
const at = `/lists/${listIndex}`;
|
||
const base = (list && typeof list.title === 'string' && list.title.trim()) || 'Untitled list';
|
||
let title = base;
|
||
for (let n = 2; columns.includes(title); n += 1) title = `${base} (${n})`;
|
||
if (list && typeof list.title === 'string' && list.title.trim() && title !== base) {
|
||
unsupported.push({ path: `${at}/title`, reason: `a second Nullboard list "${base}" is imported as "${title}"` });
|
||
}
|
||
columns.push(title);
|
||
const notes = list && Array.isArray(list.notes) ? list.notes : [];
|
||
if (list && list.notes !== undefined && !Array.isArray(list.notes)) {
|
||
unsupported.push({ path: `${at}/notes`, reason: 'Nullboard list notes are not an array and are not imported' });
|
||
}
|
||
notes.forEach((note, noteIndex) => {
|
||
const path = `${at}/notes/${noteIndex}`;
|
||
if (!note || typeof note.text !== 'string') {
|
||
unsupported.push({ path, reason: 'a Nullboard note without text is not imported' });
|
||
return;
|
||
}
|
||
const { title: cardTitle, description } = splitNoteText(note.text);
|
||
if (!cardTitle) {
|
||
unsupported.push({ path, reason: 'an empty Nullboard note is not imported' });
|
||
return;
|
||
}
|
||
if (note.min === true) collapsed += 1;
|
||
tasks.push({
|
||
title: cardTitle,
|
||
description,
|
||
column_name: title,
|
||
swimlane_name: 'Default',
|
||
tags: note.raw === true ? [NULLBOARD_RAW_LABEL] : [],
|
||
});
|
||
});
|
||
});
|
||
if (collapsed) {
|
||
unsupported.push({ path: '/lists/notes/min',
|
||
reason: `${collapsed} collapsed Nullboard note(s) are imported expanded: a WeKan card has no collapsed state` });
|
||
}
|
||
return {
|
||
board: { name: (typeof board.title === 'string' && board.title.trim()) || 'Imported Nullboard' },
|
||
columns: columns.map(name => ({ title: name })),
|
||
swimlanes: [{ name: 'Default' }],
|
||
tasks,
|
||
warnings: [],
|
||
unsupported,
|
||
};
|
||
}
|
||
|
||
function noteText(item) {
|
||
const parts = [String(item.title || '').replace(/\s*[\r\n]+\s*/g, ' ').trim() || 'Untitled'];
|
||
const description = String(item.description || '').replace(/\s+$/, '');
|
||
if (description) parts.push(description);
|
||
for (const checklist of Array.isArray(item.checklists) ? item.checklists : []) {
|
||
const entries = Array.isArray(checklist.items) ? checklist.items : [];
|
||
if (!entries.length) continue;
|
||
parts.push([String(checklist.title || '').trim() || 'Checklist',
|
||
...entries.map(entry => `[${entry.done ? 'x' : ' '}] ${String(entry.title || '').trim()}`)].join('\n'));
|
||
}
|
||
// The title is the first line; a blank line separates the blocks after it.
|
||
return [parts[0], parts.slice(1).join('\n\n')].filter(Boolean).join('\n');
|
||
}
|
||
|
||
// One board object that Nullboard's importer accepts. The id is the board's
|
||
// creation time in epoch milliseconds, as Nullboard makes its own ids, so a
|
||
// second export of the same board is offered as an overwrite in Nullboard.
|
||
// The whole board, or one page of it (models/lib/exportPaging.js): the lists -
|
||
// the board's, then one per title of the lists its cards name that are not
|
||
// exported - are found over the whole board, so every page has the same
|
||
// lists; each page fills in its own cards.
|
||
export function formatNullboard(collected) {
|
||
const { board, lists } = collected;
|
||
const { items, all } = pagingOf(collected);
|
||
const created = board && board.createdAt ? new Date(board.createdAt).getTime() : NaN;
|
||
const out = {
|
||
format: NULLBOARD_FORMAT,
|
||
id: Number.isFinite(created) && created > 0 ? created : Date.now(),
|
||
revision: 1,
|
||
title: String((board && board.title) || 'WeKan board'),
|
||
lists: [],
|
||
};
|
||
const boardLists = Array.isArray(lists) ? lists : [];
|
||
const matches = (list, item) => (list._id && item.listId ? item.listId === list._id : item.listTitle === list.title);
|
||
const noteOf = item => ({
|
||
text: noteText(item),
|
||
raw: (Array.isArray(item.labels) ? item.labels : []).includes(NULLBOARD_RAW_LABEL),
|
||
min: false,
|
||
});
|
||
for (const list of boardLists) out.lists.push({ title: String(list.title || ''), notes: [] });
|
||
// Cards whose list was not passed are kept in a list of their own name.
|
||
const extra = new Map();
|
||
for (const item of all) {
|
||
if (boardLists.some(list => matches(list, item))) continue;
|
||
const title = String(item.listTitle || 'List');
|
||
if (!extra.has(title)) { extra.set(title, out.lists.length); out.lists.push({ title, notes: [] }); }
|
||
}
|
||
for (const item of items) {
|
||
const at = boardLists.findIndex(list => matches(list, item));
|
||
if (at !== -1) {
|
||
// A card of two lists of one title (no ids) is in each, as before.
|
||
boardLists.forEach((list, i) => { if (matches(list, item)) out.lists[i].notes.push(noteOf(item)); });
|
||
} else {
|
||
out.lists[extra.get(String(item.listTitle || 'List'))].notes.push(noteOf(item));
|
||
}
|
||
}
|
||
return `${JSON.stringify(out)}\n`;
|
||
}
|