Ваша главная

Ваша главная

Plank открывается на Главной. Приветствие и поле ввода наверху — собственные элементы Plank, их изменить нельзя. Всё, что ниже, — это один HTML-файл, и агент может его переписать. Именно про эту область говорит эта страница.

Сначала спросите: его личная или всего пространства?

Это первый вопрос, а не деталь, которую решают потом. С другой стороны ответ уже не отменить.

Обе — на одно пространство. Личная страница меняет Главную того пространства, для которого её написали, и никакого другого: в остальных пространствах у человека остаётся своя Главная, а Главная на / (все пространства) остаётся стандартной. «Поменяй мою главную», сказанное в пространстве «Журнал», — это Главная «Журнала».

Личная важнее — внутри своего пространства. Тот, у кого есть личная страница для пространства, общую страницу этого пространства не видит. Отсюда два следствия, и оба уже случались:

• Если написать общую страницу человеку, у которого есть личная, он не увидит никаких изменений. И скажет, что вы ничего не сделали.
• Если написать личную «просто попробовать», она молча скроет общую, которую сделал коллега. Общая никуда не делась — человек просто перестал её видеть.

Говорят «наша», «для команды», «для всех» — это файл пространства. Говорят «моя», «для меня», «хочу видеть» — это plank_home_set. Не понятно — спросите.

Как написать

plank_home_set({ filePath: "/spaces/acme/.plank/home-draft.html", space: "acme" })

• space — slug пространства, в котором просят (папка под /spaces/, в которой работает этот чат). Обязателен: значения по умолчанию нет, потому что именно угадывание однажды сделало страницу одного пространства Главной всех.
• Путь абсолютный, внутри контейнера, файл должен быть .html.
• Сначала запишите файл и передайте путь. Никогда не вставляйте страницу в сам вызов. Инструмент стоит одинаково при любом размере файла, а набрать страницу — это примерно минута на 6 КБ: страница на 12 КБ, вставленная в аргумент, это две минуты ожидания впустую.
• Страница должна быть самодостаточной: без внешних стилей, без внешних скриптов, без абсолютных URL. Она отображается в изолированном фрейме со своим origin.
• Фрейм по высоте страницы — прокручивается Главная, а не страница. Поэтому ничего не задавайте от высоты окна: 100vh растёт вместе с фреймом (Plank это замечает и возвращает прокрутку внутри), а position: fixed или sticky прилипают к странице, а не к экрану. Широкая таблица по-прежнему прокручивается вбок.
• Максимум 512 КБ. Пустой файл отклоняется — пустая главная это пустой экран.
• Начинайте со стандартной страницы (ниже), а не с нуля.

Для страницы пространства запишите /spaces/<slug>/.plank/home.html обычными файловыми инструментами. Правила о самодостаточности те же; ограничение размера — файловой системы.

Что страница может показывать

К собственному подписанному base фрейма привязаны четыре источника только для чтения, поэтому обычный fetch доходит до них без ключей и без настройки:

const rows = await fetch("me/pins").then((r) => r.json()).then((b) => b.data);

Каждый отвечает {data: …}, рассказывает про того, кто смотрит на страницу, и охватывает все пространства, где он состоит, а не только текущее.

Два null — это значения, а не ошибки:

• me/home равен null у всех, у кого нет личной страницы в этом пространстве, то есть у всех в первый день.
• title в строке me/attention равен null, когда чат принадлежит другому человеку и он приватный. Подставьте своё слово — «Чат», «Без названия», любое. Никогда не выводите слово «null».

Неизвестный путь me/… отвечает 400, и любой метод кроме GET тоже.

Таблицы данных приложения этого пространства доступны с того же base — fetch("apps/<table>"). Главная открывается при каждом заходе, поэтому запрашивайте только то, что она показывает: apps/journal_entries?orderBy= + encodeURIComponent(JSON.stringify({column: "date", direction: "desc"})) + &limit=7 вернёт семь новейших строк вместо всей таблицы. Параметры и отказы: Данные приложения.

Что страница может делать

// Открыть закреплённый дашборд. Передавайте ОБЕ половины из одной строки —
// me/pins охватывает пространства, и один путь откроет не то или ничего.
// На компьютере Ctrl/Cmd-клик или клик средней кнопкой по плитке сам откроет
// её В НОВОЙ ВКЛАДКЕ; newTab: true просит её и при обычном клике
// (на телефоне вкладок нет, там он игнорируется).
window.parent.postMessage(
  { type: "plank:open-file", path: pin.vmPath, workspaceId: pin.workspaceId, newTab: false },
  "*",
);

// Открыть один из его чатов.
window.parent.postMessage({ type: "plank:open-chat", sessionId: row.sessionId }, "*");

// Отправить в раздел приложения.
window.parent.postMessage({ type: "plank:open-surface", name: "schedules" }, "*");

// Положить фразу в поле ввода, чтобы человек её дописал.
window.parent.postMessage({ type: "plank:insert-chat-text", text: "Измени мою главную: " }, "*");

// Или отправить готовый запрос отдельным новым чатом.
window.parent.postMessage({ type: "plank:send-chat-message", text: "Собери отчёт за неделю" }, "*");

Два факта, которые экономят час отладки:

• Страницу, с которой человек ушёл, Plank игнорирует. Она продолжает работать — таймеры идут, запросы завершаются — и все перечисленные сообщения от неё отбрасываются. Действовать от имени человека может только страница на экране.
• plank:open-file нужен workspaceId из той же строки me/pins, что и путь. Назвать одно пространство и указать путь в другое — прямой отказ.

Всё остальное, что умеет дашборд — запуск скриптов рабочего пространства через @plank-button, навигация по нескольким страницам, изображения — описано в Интерактивных HTML-дашбордах. Здесь это не повторяется.

Стандартная страница

То, что человек видит, пока никто ничего не менял:

• «Сегодня по расписанию» — сегодняшние запуски, из me/schedules/today.
• «Ваши дашборды» — закреплённые HTML-файлы и таблицы, из me/pins.
• «Настроить главную» — кнопка, которая кладёт «Измени мою главную: » в поле ввода.

Блок, в котором ничего нет, не рисуется вообще. Новый человек без расписаний и без закреплённого видит одну кнопку — и это задуманное первое впечатление, а не три пустых заголовка.

Берите её за основу. Попросите человека открыть Главную и рассказать, что там нарисовано, либо напишите страницу с теми же тремя блоками: карточки для расписаний, плитки для закреплённого и кнопка.

Тема

Plank сообщает странице, в какой теме рисовать, и сообщает снова, когда человек меняет тему при открытой странице:

window.addEventListener("message", (e) => {
  if (e.data && e.data.type === "plank:set-theme") {
    document.documentElement.setAttribute("data-theme", e.data.theme === "dark" ? "dark" : "light");
  }
});

Не считайте тему светлой по умолчанию и не полагайтесь на один prefers-color-scheme: он читает операционную систему, а она может расходиться с темой, выбранной в Plank. Используйте его как первое приближение и дайте сообщению победить.

Как вернуть стандартную

• Личная страница: вызовите plank_home_set ещё раз, для того же space, с файлом, содержащим стандартную страницу. Удаления нет и истории версий нет — set заменяет. Другие пространства это в любом случае не затрагивает.
• Страница пространства: удалите /spaces/<slug>/.plank/home.html. Личные страницы тех, у кого они есть, не затрагиваются.

И запасной выход, для которого агент не нужен вовсе: если страница не загрузилась, Plank рисует стандартную и показывает над ней тихую строку «Ваша главная не загрузилась · Показать стандартную». Ничего не удаляется. Человек, запершийся на собственной главной, в одном касании от рабочего экрана.

О что споткнётесь

• Пустой файл отклоняется. Пустая главная — это пустой экран, а не чистый.
• Больше 512 КБ отклоняется. Лечится не сжатием, а тем, что данные надо запрашивать, а не вшивать: для этого и есть четыре источника.
• Истории версий нет. set заменяет — сохраните написанный файл в рабочем пространстве, если человек может захотеть вернуться.
• Личная важнее общей — только в своём пространстве. Перечитайте первый раздел до записи файла, а не после.
• У страницы свой origin. localStorage работает, но он у каждого человека и на каждом устройстве свой, и ничего из него не доходит ни до Plank, ни до другого зрителя.