拡張スタートガイドのカスタマイズ

第5版作成 2026/09/25 04:17最終更新 2026/09/25 10:52（日本時間）

対応バージョンPleasanter 1.5.2.0 以降確認バージョン1.5.2.01.5.8.1

スタートガイドは、ログイン後に表示されるマニュアルや教材へのリンクのパネルです。1.5.2.0 から拡張スタートガイドとして拡張機能化され、JSON ファイルで内容を変えられるようになりました。このページでは設定方法と、運用上の注意点をまとめます。

設定は App_Data/Parameters/ExtendedStartGuides/ の JSON で行い、Append / Prepend / Remove / Replace / ReplaceAll の 5 つのアクションで既定のガイドを操作する
公式マニュアルの例にある wwwroot/images/ はアップグレード時に上書きされる対象。アイコンは同梱の SVG を使い回すか、サイトの添付ファイルを ../binaries/{GUID}/show で参照するとアップグレードの影響を受けない
設定変更の反映にはアプリケーションの再起動かパラメータのリロードが必要

既定のスタートガイド

拡張スタートガイドを設定していないときに表示される項目です。Id はアクションで既定のガイドを指定するときに使います。

Id	テキスト	アイコン（ライト / ダーク）
`SgManual`	ユーザーマニュアル	`sg-manual.svg` / `sg-manual-d.svg`
`SgGoHandsOn01`	アプリ作成ガイド	`sg-handson.svg` / `sg-handson-d.svg`
`SgMaterials`	お役立ちコンテンツ	`sg-materials.svg` / `sg-materials-d.svg`
`SgExtensions`	エンタープライズ版	`sg-extensions.svg` / `sg-extensions-d.svg`
`SgSupport`	ソリューションサポート	`sg-support.svg` / `sg-support-d.svg`

トップ画面に表示される既定のスタートガイド（5 項目と「次回はスタートガイドを表示しない」）

設定ファイル

配置場所

設定は次のディレクトリに JSON ファイルとして置きます。App_Data/Parameters/ 配下はインストーラによるアップグレードでも保持されます。サブディレクトリも再帰的に読み込まれるので、整理に使えます。

text

App_Data/Parameters/ExtendedStartGuides/

拡張子は .json

サンプルファイルの Sample.json.txt はそのままでは読み込まれません。.json にリネームして使います。

Extensions テーブルには対応していない

ExtensionInitializer が処理する ExtensionType は Fields / Html / NavigationMenu / Script / ServerScript / Sql / Style / Plugin の 8 種類で、StartGuide は含まれていません。拡張スタートガイドは JSON ファイルだけで管理します（Extensions テーブルで拡張機能を DB 管理の対象外です）。

JSON の構造

json

{
    "Disabled": false,
    "DeptIdList": [],
    "GroupIdList": [],
    "UserIdList": [],
    "TargetId": "",
    "Action": "Append",
    "StartGuides": [
        {
            "Id": "SgCustom01",
            "Text": "社内マニュアル",
            "Url": "https://example.com/manual",
            "ImgNameLight": "",
            "ImgNameDark": "",
            "Target": "_blank",
            "Disabled": false
        }
    ]
}

拡張設定のプロパティは次のとおりです。

プロパティ	型	説明
`Disabled`	bool	`true` で無効化
`DeptIdList`	int[]	対象の組織 ID リスト（空で全組織）
`GroupIdList`	int[]	対象のグループ ID リスト（空で全グループ）
`UserIdList`	int[]	対象のユーザー ID リスト（空で全ユーザー）
`TargetId`	string	操作対象のガイドの `Id`（`Append` / `Prepend` / `Remove` / `Replace` で使用）
`Action`	string	アクションの種類
`StartGuides`	array	スタートガイド項目のリスト

スタートガイド項目のプロパティは次のとおりです。

プロパティ	型	説明
`Id`	string	ガイド項目の一意な識別子
`Text`	string	表示テキスト
`Url`	string	リンク先 URL
`ImgNameLight`	string	ライトテーマ用のアイコン画像ファイル名
`ImgNameDark`	string	ダークテーマ用のアイコン画像ファイル名
`Target`	string	リンクの target 属性（`_blank` で別タブ）
`Disabled`	bool	`true` で無効化

ImgNameLight と ImgNameDark のどちらか一方だけを指定した場合、未指定の側には指定した側の値が使われます。両方とも空ならアイコンなし（テキストのみ）で表示されます。

アクション

Action で、既定のスタートガイドに対する操作を指定します。

Action	動作	`TargetId`	`StartGuides`
`Append`	`TargetId` のガイドの直後に挿入	必要	必要
`Prepend`	`TargetId` のガイドの直前に挿入	必要	必要
`Remove`	`TargetId` のガイドを削除	必要	不要
`Replace`	`TargetId` のガイドを `StartGuides` の内容で置き換え	必要	必要
`ReplaceAll`	既定のガイドをすべて破棄し、`StartGuides` の内容だけにする	不要	必要

json

{
    "TargetId": "SgManual",
    "Action": "Append",
    "StartGuides": [
        {
            "Id": "SgInternalManual",
            "Text": "社内運用マニュアル",
            "Url": "https://wiki.example.com/pleasanter",
            "Target": "_blank"
        }
    ]
}

この例では「ユーザーマニュアル」の直後に「社内運用マニュアル」が追加されます。Prepend は Action を変えるだけで、直前への挿入になります。

json

{
    "TargetId": "SgExtensions",
    "Action": "Remove"
}

この例ではエンタープライズ版のガイドが削除されます。

json

{
    "TargetId": "SgSupport",
    "Action": "Replace",
    "StartGuides": [
        {
            "Id": "SgHelpDesk",
            "Text": "社内ヘルプデスク",
            "Url": "https://helpdesk.example.com",
            "Target": "_blank"
        }
    ]
}

json

{
    "Action": "ReplaceAll",
    "StartGuides": [
        {
            "Id": "SgOrgManual",
            "Text": "社内マニュアル",
            "Url": "https://wiki.example.com/manual",
            "Target": "_blank"
        },
        {
            "Id": "SgOrgFaq",
            "Text": "よくある質問",
            "Url": "https://wiki.example.com/faq",
            "Target": "_blank"
        }
    ]
}

ReplaceAll は既定のガイドをすべて消す

ReplaceAll を使うと、マニュアルやハンズオンガイドなど既定のガイドはすべて表示されなくなります。必要な項目は StartGuides に含めてください。

レイアウトと項目数

スタートガイドは display: flex（横並び）で描画され、項目数に固定の上限はありません。各項目は幅 216px です。

項目数	表示
1〜3	パネル中央に寄せて表示される
4〜5	既定のレイアウトに近い表示になる
6 以上	横に並び続けるため、画面幅によっては収まらない場合がある

画面幅に対して項目が多い場合は、テキストを短くするか項目数を絞ります。アイコンなし（テキストのみ）の項目はテキストが縦方向の中央に揃えて表示されます。

アイコン画像の指定

画像 URL の組み立て

ImgNameLight / ImgNameDark の値は、内部で Locations.Get(context, "Images", imgName) によって URL に変換されます。たとえば "ImgNameLight": "my-icon.svg" なら、img タグの src は /images/my-icon.svg になります。

このため ../ を含む相対パスを指定すると、/images/ の外にある画像も参照できます。"ImgNameLight": "../binaries/{guid}/show" と指定すると /images/../binaries/{guid}/show が生成され、ブラウザが .. を解決して /binaries/{guid}/show にアクセスします。

wwwroot/images に置く方法の問題

公式マニュアルでは、カスタムアイコンを wwwroot/images/ に置く方法が紹介されています。しかしこのフォルダには標準のアイコンや画像リソースが含まれ、インストーラによるアップグレード時に上書きされる可能性があります。バージョンアップのたびにアイコンを置き直す必要が出てきます。

アップグレードの影響を受けない方法は次の 3 つです。

方法	内容	向いている場面
テキストのみ	`ImgNameLight` / `ImgNameDark` を省略（または空文字）	最もシンプルで確実に運用したい
同梱の SVG を使い回す	既定のガイド用の SVG を指定	追加のファイル配置なしでアイコンを付けたい
サイトの添付ファイル	`../binaries/{GUID}/show` を指定	独自のアイコンを DB で管理したい

テキストのみで運用する

json

{
    "Action": "ReplaceAll",
    "StartGuides": [
        {
            "Id": "SgOrgManual",
            "Text": "社内マニュアル",
            "Url": "https://wiki.example.com/manual",
            "Target": "_blank"
        },
        {
            "Id": "SgOrgHandsOn",
            "Text": "操作トレーニング",
            "Url": "https://wiki.example.com/training",
            "Target": "_blank"
        }
    ]
}

同梱の SVG アイコンを使い回す

既定のスタートガイド用の SVG は標準ファイルなので、アップグレード後も存在します。

ファイル名（ライト / ダーク）	イメージ
`sg-manual.svg` / `sg-manual-d.svg`	マニュアル
`sg-handson.svg` / `sg-handson-d.svg`	ハンズオン
`sg-materials.svg` / `sg-materials-d.svg`	コンテンツ
`sg-extensions.svg` / `sg-extensions-d.svg`	拡張機能
`sg-support.svg` / `sg-support-d.svg`	サポート

json

{
    "Action": "ReplaceAll",
    "StartGuides": [
        {
            "Id": "SgOrgManual",
            "Text": "社内マニュアル",
            "Url": "https://wiki.example.com/manual",
            "ImgNameLight": "sg-manual.svg",
            "ImgNameDark": "sg-manual-d.svg",
            "Target": "_blank"
        },
        {
            "Id": "SgOrgFaq",
            "Text": "よくある質問",
            "Url": "https://wiki.example.com/faq",
            "ImgNameLight": "sg-support.svg",
            "ImgNameDark": "sg-support-d.svg",
            "Target": "_blank"
        }
    ]
}

サイトの添付ファイルでアイコンを管理する

アイコン画像を管理用サイトに添付ファイルとしてアップロードし、DB で管理します。管理用サイトの作り方は静的ファイルをサイトで管理を参照してください。

管理用サイトにアイコン画像をアップロードする
各ファイルの GUID を確認する
ImgNameLight / ImgNameDark に ../binaries/{GUID}/show の形式で指定する。先頭の ../ で /images/ を回避し、/binaries/{GUID}/show が参照される

json

{
    "Action": "ReplaceAll",
    "StartGuides": [
        {
            "Id": "SgOrg_Manual",
            "Text": "社内マニュアル",
            "Url": "https://wiki.example.com/manual",
            "ImgNameLight": "../binaries/a1b2c3d4e5f6/show",
            "ImgNameDark": "../binaries/f6e5d4c3b2a1/show",
            "Target": "_blank"
        }
    ]
}

GUID の部分は、実際にアップロードしたファイルの GUID に置き換えます。添付ファイルは DB の Binaries テーブルに保存されるため、アップグレードで上書きされることはありません。SVG もそのまま使えます。

添付ファイルには読取権限が必要

添付ファイルの参照には読取権限が必要です。管理用サイトのアクセス権で、全ユーザーに読取権限が付与されていることを確認してください。

リンク先をプリザンター内で管理する

外部の Wiki や Web サイトの代わりに、リンク先のコンテンツもプリザンター内のサイトで管理できます。

text

スタートガイドリソース（フォルダ）
├── はじめにお読みください（Wiki）
├── 操作マニュアル（Wiki）
├── よくある質問（Wiki）
└── お問い合わせ先（Wiki）

管理用フォルダのアクセス権は次のように設定します。全ユーザーが閲覧でき、管理者だけが編集できる形です。

対象	読取	作成	更新	削除	送信
全ユーザー	対応	-	-	-	-
管理者グループ	対応	対応	対応	対応	対応

管理用フォルダは通常の業務では使わないため、サイトの管理で「リンクを表示しない」を有効にします。ナビゲーションのサイト一覧には表示されなくなりますが、URL を直接指定したアクセスはできます。

Url にはプリザンター内の相対パスを指定できます。Wiki サイトの場合は /items/{SiteId} の形式です。内部リンクでは Target を省略するか空文字にすると同じタブで遷移します。

json

{
    "Action": "ReplaceAll",
    "StartGuides": [
        {
            "Id": "SgIntroduction",
            "Text": "はじめにお読みください",
            "Url": "/items/1001",
            "ImgNameLight": "../binaries/a1b2c3d4e5f6/show",
            "ImgNameDark": "../binaries/f6e5d4c3b2a1/show"
        },
        {
            "Id": "SgOperationManual",
            "Text": "操作マニュアル",
            "Url": "/items/1002",
            "ImgNameLight": "../binaries/1a2b3c4d5e6f/show",
            "ImgNameDark": "../binaries/6f5e4d3c2b1a/show"
        },
        {
            "Id": "SgFaq",
            "Text": "よくある質問",
            "Url": "/items/1003",
            "ImgNameLight": "../binaries/b1c2d3e4f5a6/show",
            "ImgNameDark": "../binaries/a6f5e4d3c2b1/show"
        },
        {
            "Id": "SgContact",
            "Text": "お問い合わせ先",
            "Url": "/items/1004",
            "ImgNameLight": "../binaries/c1d2e3f4a5b6/show",
            "ImgNameDark": "../binaries/b6a5f4e3d2c1/show"
        }
    ]
}

このように ReplaceAll で既定の 5 項目を消し、リンク先を社内の Wiki サイト、アイコンを管理用サイトの添付ファイルにすれば、公式のガイドを組織独自のものに完全に入れ替え、しかもアップグレードの影響を受けない構成になります。

表示対象の絞り込み

DeptIdList / GroupIdList / UserIdList で、表示するユーザーを組織・グループ・ユーザーで絞り込めます。

json

{
    "DeptIdList": [10, 20],
    "Action": "Append",
    "TargetId": "SgManual",
    "StartGuides": [
        {
            "Id": "SgDeptManual",
            "Text": "部門別業務マニュアル",
            "Url": "https://wiki.example.com/dept-manual",
            "Target": "_blank"
        }
    ]
}

ID の先頭に - を付けると、そのユーザーを除外する否定条件になります。次の例では UserId が 1 のユーザー（通常は管理者）を除き、それ以外のユーザーにだけ表示します。

json

{
    "UserIdList": [-1],
    "Action": "Append",
    "TargetId": "SgManual",
    "StartGuides": [
        {
            "Id": "SgNonAdminGuide",
            "Text": "一般ユーザー向けガイド",
            "Url": "https://wiki.example.com/user-guide",
            "Target": "_blank"
        }
    ]
}

複数ファイルの組み合わせ

ExtendedStartGuides/ には複数の JSON を置けます。ファイルは読み込まれた順に処理されます。1.5.8.1 のソースでは DirectoryInfo.GetFiles("*.json") の結果をそのまま使い、並べ替えはしていません（直下のファイルの後にサブディレクトリを処理。Initializer.cs）。Windows（NTFS）では通常ファイル名順に返りますが、Linux などでは順序が保証されないため、順序に依存する構成は動作環境で確認してください。

text

ExtendedStartGuides/
├── 01_RemoveUnused.json      ← まず不要な項目を削除
├── 02_AddCustomGuides.json   ← 次にカスタム項目を追加
└── 03_DeptSpecific.json      ← 最後に部門固有の項目を追加

json

{
    "TargetId": "SgExtensions",
    "Action": "Remove"
}

json

{
    "TargetId": "SgSupport",
    "Action": "Replace",
    "StartGuides": [
        {
            "Id": "SgHelpDesk",
            "Text": "社内ヘルプデスク",
            "Url": "/items/2001",
            "ImgNameLight": "sg-support.svg",
            "ImgNameDark": "sg-support-d.svg"
        }
    ]
}

json

{
    "DeptIdList": [30],
    "TargetId": "SgHelpDesk",
    "Action": "Append",
    "StartGuides": [
        {
            "Id": "SgDevGuide",
            "Text": "開発チーム向けガイド",
            "Url": "/items/3001",
            "ImgNameLight": "sg-extensions.svg",
            "ImgNameDark": "sg-extensions-d.svg"
        }
    ]
}

03 では、02 で追加した SgHelpDesk を TargetId に指定しています。

処理順序に注意

Remove で削除した項目の Id を、後続のファイルで TargetId に指定しても、すでに削除済みのため操作は無効になります。ファイル名の先頭に番号を付けて処理順序を明確にしておくことを勧めます。

運用上の注意

設定変更の反映

設定ファイルはアプリケーションの起動時に読み込まれます。変更後は次のどちらかで反映します。

アプリケーションの再起動
パラメータのリロード（特権ユーザーで /admins/reloadparameters にアクセス。パラメータを参照）

JSON の構文エラー

設定ファイルに構文エラーがあると、アプリケーションの起動時に例外が発生します。変更後は JSON の構文を確認してから再起動してください。

Id の命名規則

Id は一意である必要があり、Remove や Replace の対象の特定にも使われます。組織のプレフィックスを付けるなどの命名規則を決めておくと管理しやすくなります。

text

例: SgOrg_Manual, SgOrg_Faq, SgDept30_DevGuide

ダークテーマ

ダークテーマのユーザーがいる場合は、ImgNameDark でダークテーマ用のアイコンを指定することを勧めます。未指定の場合はライトテーマ用のアイコンが使われますが、ダークテーマの背景では見えにくくなることがあります。

スタートガイドを表示しない

組織全体でスタートガイドを表示しない場合は、Service.json の ShowStartGuide を false にします。

json

{
    "ShowStartGuide": false
}

個人単位では、スタートガイドのパネル内の「次回からスタートガイドを表示しない」で非表示にできます。この設定はユーザーの UserSettings に保存されます。

拡張スタートガイドのカスタマイズ

既定のスタートガイド

設定ファイル

配置場所

JSON の構造

アクション

レイアウトと項目数

アイコン画像の指定

画像 URL の組み立て

wwwroot/images に置く方法の問題

テキストのみで運用する

同梱の SVG アイコンを使い回す

サイトの添付ファイルでアイコンを管理する

リンク先をプリザンター内で管理する

表示対象の絞り込み

複数ファイルの組み合わせ

運用上の注意

設定変更の反映

JSON の構文エラー

Id の命名規則

ダークテーマ

スタートガイドを表示しない

関連ページ

変更履歴

拡張スタートガイドのカスタマイズ ​

既定のスタートガイド ​

設定ファイル ​

配置場所 ​

JSON の構造 ​

アクション ​

レイアウトと項目数 ​

アイコン画像の指定 ​

画像 URL の組み立て ​

wwwroot/images に置く方法の問題 ​

テキストのみで運用する ​

同梱の SVG アイコンを使い回す ​

サイトの添付ファイルでアイコンを管理する ​

リンク先をプリザンター内で管理する ​

表示対象の絞り込み ​

複数ファイルの組み合わせ ​

運用上の注意 ​

設定変更の反映 ​

JSON の構文エラー ​

Id の命名規則 ​

ダークテーマ ​

スタートガイドを表示しない ​

関連ページ ​

変更履歴

拡張スタートガイドのカスタマイズ

既定のスタートガイド

設定ファイル

配置場所

JSON の構造

アクション

レイアウトと項目数

アイコン画像の指定

画像 URL の組み立て

wwwroot/images に置く方法の問題

テキストのみで運用する

同梱の SVG アイコンを使い回す

サイトの添付ファイルでアイコンを管理する

リンク先をプリザンター内で管理する

表示対象の絞り込み

複数ファイルの組み合わせ

運用上の注意

設定変更の反映

JSON の構文エラー

Id の命名規則

ダークテーマ

スタートガイドを表示しない

関連ページ