プリザンターで静的ファイルをサイトで管理する方法

はじめに

プリザンターを運用していると、カスタムのアイコン画像やスタイルシートなどの静的ファイルを wwwroot/ ディレクトリに配置することがあります。しかし、これらのファイルはバージョンアップ時に上書き・削除されてしまう可能性があります。

この記事では、プリザンターのサイトの添付ファイル機能を使って、静的ファイルをデータベースで管理する方法を紹介します。データベースに保存されたファイルはアプリケーションファイルの更新による影響を受けないため、バージョンアップのたびにファイルを再配置する必要がなくなります。

課題: バージョンアップ時の静的リソース再配置

カスタムの画像ファイルなどを wwwroot/ ディレクトリ以下に配置して使用している場合、プリザンターのバージョンアップ時に問題が発生します。

バージョンアップでは既存のアプリケーションファイルを新しいバージョンのファイルで置き換えます。このとき、wwwroot/ 以下に独自に配置したファイルが上書き・削除されてしまう可能性があります。

つまり、バージョンアップのたびに次の手順が必要になります。

1. カスタムファイルをバックアップする
2. バージョンアップを実施する
3. カスタムファイルを再配置する

手間がかかるだけでなく、再配置を忘れるとファイルが参照できなくなるリスクもあります。

解決策: 管理サイトによる静的ファイル管理

プリザンターの添付ファイル項目を使うと、ファイルをデータベースの Binaries テーブルに保存できます。保存されたファイルは /binaries/{GUID}/show の URL でアクセスできるため、画像やその他のファイルの参照先として使用できます。

この仕組みを利用して、静的ファイルを管理するための専用サイトを作成します。

設計のポイント

設定項目	値	理由
サイトの種別	記録テーブル	添付ファイル項目を使用するため
アクセス権	全員: 読込のみ	ログイン済みの全ユーザーがファイルにアクセスできるようにする
アクセス権	管理者: 管理権限	ファイルの登録・更新は管理者のみ実施する
読取専用の場合は画面に表示しない	有効	読込権限のみの一般ユーザーのサイトメニューに表示しない

管理者からはサイトメニューに表示されるため、ファイルの管理をすぐに行えます。一般ユーザーには見えないため、業務に関係のないサイトが邪魔になることもありません。

セットアップ手順

1. 管理フォルダの作成

ルートフォルダ（もしくは管理系の親フォルダ）に新しいフォルダを作成します。タイトルは「静的ファイル管理」など、用途が分かる名称にしておきます。

2. アクセス権の設定

作成したフォルダの管理画面で、アクセス権を設定します。

• 不要なアクセス権を削除する
• 「全員」（もしくは全ユーザーが所属する組織）に「読取」権限を付与する
• 管理者（もしくは管理者グループ）に管理権限を付与する

「全員」に読取権限を付与するのは、添付ファイルの URL にアクセスする際に読取権限が必要なためです。

3. 「読取専用の場合は画面に表示しない」を有効にする

フォルダの管理画面の「サイトの設定」タブから「読取専用の場合は画面に表示しない」を有効にします。

この設定により、読込権限のみの一般ユーザーにはサイトメニューに表示されなくなります。管理者は引き続き表示されるため、ファイルの管理はいつでも行えます。

4. 記録テーブルの作成

管理フォルダの中に記録テーブルを作成します。管理するファイルの用途に合わせて、テーブル名を付けます（例:「サイトアイコン」「スタートガイドアイコン」など）。

エディタ画面で添付ファイル項目を有効にし、管理したいファイルの数に応じて項目を追加します。

1 件のレコードの複数の添付ファイル項目にファイルをまとめて管理することも、ファイルごとにレコードを分けることもできます。管理しやすい方法を選んでください。

5. ファイルのアップロード

レコードを作成し、添付ファイル項目にファイルをアップロードします。画像ファイル（PNG、JPEG、SVG など）はもちろん、その他のファイルもアップロードできます。

アップロード後、各ファイルには GUID（一意の識別子）が割り当てられます。

6. GUID の確認

アップロードしたファイルの GUID は、添付ファイルのリンク URL から確認できます。添付ファイルのリンクを右クリックして URL をコピーすると、/binaries/{GUID}/download 形式の URL が取得できます。この {GUID} 部分がファイルの一意の識別子です。

ファイルの参照方法

アップロードしたファイルは、以下の URL で参照できます。

URL	用途
/binaries/{GUID}/show	画像の表示（<img> タグや CSS の background-image など）
/binaries/{GUID}/download	ファイルのダウンロード

{GUID} の部分は各ファイルの GUID に置き換えてください。

添付ファイルの URL は認証が必要です。プリザンターにログイン済みのユーザーのみファイルにアクセスできます。

活用例

サイトアイコンの管理

「プリザンターでサイトアイコンとサイト種別の表示を両立する方法【別解】」で紹介した拡張スタイルでは、サイト種別ごとのアイコンを CSS の background-image で指定しています。

静的ファイル（/images/icon-site-*.svg）の代わりに、管理サイトの添付ファイル URL を指定することで、バージョンアップ時のファイル再配置が不要になります。

SiteReference.css

.conditions .reference {
    display: none !important;
}

/* サブディレクトリで運用している場合はurlのパスの書き換えが必要 */
.nav-site:not(.to-parent):not(:has(.site-icon img)) {
    background-position: left 0.5em bottom 0.5em;
    background-repeat: no-repeat;
    background-size: 2em;

    .title {
        padding-left: 2em;
        padding-right: 2em;
    }

    &.sites {
        background-image: url("/binaries/a1b2c3d4e5f6/show");
    }

    &.results {
        background-image: url("/binaries/1a2b3c4d5e6f/show");
    }

    &.issues {
        background-image: url("/binaries/b1c2d3e4f5a6/show");
    }

    &.wikis {
        background-image: url("/binaries/c1d2e3f4a5b6/show");
    }

    &.dashboards {
        background-image: url("/binaries/d1e2f3a4b5c6/show");
    }
}

各 {GUID} は実際の環境で管理サイトにアップロードしたファイルの GUID に置き換えてください。

拡張スタートガイドのアイコン

拡張スタートガイドの ImgNameLight / ImgNameDark は、内部的に /images/ プレフィックスを付けて画像パスを生成します。そのため、../binaries/{GUID}/show の形式で指定すると /images/../binaries/{GUID}/show となり、ブラウザがパスを解決して /binaries/{GUID}/show にアクセスします。

{
    "ImgNameLight": "../binaries/a1b2c3d4e5f6/show",
    "ImgNameDark": "../binaries/f6e5d4c3b2a1/show"
}

サイト画像の利用

アイコン用途であれば、サイト画像を利用する方法もあります。各サイトの管理画面からサイト画像をアップロードでき、以下の URL で参照できます。

/items/{SiteId}/binaries/siteimageicon/
/items/{SiteId}/binaries/siteimagethumbnail/

サイト画像はアップロード時に PNG 形式にリサイズされます。SVG 形式のファイルをそのまま使いたい場合は、添付ファイルを使用してください。

バージョンアップ時の安心感

この方法の最大のメリットは、プリザンターのバージョンアップ時にファイルの再配置が不要になることです。

管理方法	バージョンアップ時の対応
静的ファイル（wwwroot/ 配下）	ファイルの再配置が必要
管理サイト（データベース保存）	対応不要

ファイルはデータベースの Binaries テーブルに格納されるため、アプリケーションファイルの更新による影響を受けません。

まとめ

• プリザンターのサイトの添付ファイル機能を使って、静的ファイルをデータベースで管理する方法を紹介しました
• アクセス権と「読取専用の場合は画面に表示しない」オプションを組み合わせることで、一般ユーザーからは見えない管理サイトを構築できます
• ファイルはデータベースに保存されるため、バージョンアップ時の再配置が不要になります
• サイトアイコンや拡張スタートガイドのアイコンなど、さまざまな用途に応用できます