Webアプリにマニュアル埋込(前編)

一生懸命マニュアルを作っても、機能を追加のたびマニュアルの作り直し・・
これじゃwebアプリの更新頻度に影響が出てまうわー

プログラミングは好き!でも、マニュアルはめんどくさい!!

Webアプリの画面でそのまま使い方が説明できればいいのに。
と思いいろいろ探していたら、

ありました!めぇ~~

shepherd.js!

当サイトのWebアプリのマニュアルや新機能リリース時のお知らせは「shepherd.js」(シェパード)というJavascriptのライブラリを使用してます。

※この記事の時点でのバージョンは「shepherd.js 9.1.1」となります。

以下の様に注釈をモーダルウィンドウで表示してくれます。

ロゴ1

この記事は私と同じように、サイト・Webアプリにマニュアルを組み込みたいと考えてる人向けに書いてます。

個人でWebアプリを作成している方はもちろん、企業にお勤めでブラウザで動いている社内システムのマニュアル作成から解放されたい方にもお勧めです。

私も本業で新規システムリリース時、Excelにスクリーンショットを貼り付けてゴリゴリとマニュアルを作ってました。
印刷時にはみ出てないかとか、誤字脱字チェックとか・・・めっちゃメンドクサかったですし、事業所等への使い方説明会も何とかならんもんかと・・・

さて、実装です!

前置きが長くなってしまいました。

まずは必要なソースをcdn経由で取得します。(もしくは下で指定している2ファイルをURLから直接引っ張って自サーバの格納し、読込先として指定して下さい。)

<script src="https://cdn.jsdelivr.net/npm/shepherd.js@9.1.1/dist/js/shepherd.min.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/shepherd.js@9.1.1/dist/css/shepherd.css"/>

次に、マニュアルを表示したいパーツにマーキングします。

<!--説明したい部分に任意かつ一意のクラス名を付与します-->
<!--今回は「tutorial_01、tutorial_02」としています。-->
<div id = 'tutorial_01'> 
   ・・・・
</div>
<div id = 'tutorial_02'> 
   ・・・・
</div>

最後にマニュアルの定義を<script>タグ内で記述します。
シェパードではマニュアルの「[次へ]で進む」塊りを(tour)と呼びます。

<script>
	//ツアークラスのインスタンスを作成します。
	const tutorial = new Shepherd.Tour({
		useModalOverlay: true,		//trueで説明部分以外をうす暗くします
		defaultStepOptions: {
			classes: 'tour_modal',	//自身で設定したcssのclassが適用できます。効く効かないはCHROMEで検証して下さい。
			scrollTo: true,			//trueにすると説明部分に自動スクロールします
			cancelIcon:{
				enabled:true		//trueにすると説明モーダルの右上に×ボタンが表示されます
			}
		},
		tourName:'tutorial'		//チュートリアルに名称を付けれます
	});
	
	//以降、「addStep」でチュートリアルを追加していきます。
	//表示される順番はaddStepで記載した順に上から表示されます。
	tutorial.addStep({
		//title(ヘッダ部)、text(説明文)ともに` `で括るとHTMLが使えます
		title: `<p class='tour_header'>ご登録ありがとうございます。</p>`,
		text: `<p class='tour_discription'> これから簡単にWEBREZの使い方を説明します。
			  <br>10分ほどの操作になります。
			  <br>後にしたい方は「後で見る」タップして下さい。</p>`,
		//ボタンの定義
		buttons: [
			{
				text: '後で見る',			//ボタンに表示させるtext
				action: tutorial.cancel		//ボタンの処理(next,back,cancel,complete)とあり、名称の通りの処理が実行されます
			},
			{
				text: 'Next',
				action: tutorial.next
			}
		]
	});
	tutorial.addStep({
		title: `<p class='tour_header'>チュートリアル</p>`,
		text: `<p class='tour_discription'>まずはレジに表示する商品を登録しましょう。</p>`,
		buttons: [
			{
				text: 'back',
				action: tutorial.back
			},
			{
				text: 'Next',
				action: tutorial.next
			}
		]
	});
	
	//このステップでは「次へ」等のボタンはなく「×」ボタンも非表示としています。
	//別画面に強制的に遷移させたい場合など、このようにすると指定されたボタン等しか操作できなくなるため
	//画面遷移を意図どおりに操作できます。
	tutorial.addStep({
		title: `<p class='tour_header'>チュートリアル</p>`,
		text: `<p class='tour_discription'>「商品登録」から商品を追加します。<br><br>「商品登録」ボタンをタップしてください。</p>`,
		attachTo: {
			element: '#tutorial_01',	//上でマーキングしたidを指定します
			on: 'bottom'				//指定した場所の下に説明を表示します(他,top,left,rightなど)
		},
		cancelIcon:{
			enabled:false	//インスタンス作成時に有効にした×ボタンを無効にします。
		}
		//buttons定義はなし
	});
  //最後にstartメソッドでツアーが開始されます。
 //下の様に自動実行でもonClickで発火させてもいいと思います。
  tutorial.start();
</script>

以上のコードでご自身のwebアプリにもマニュアルを設定する事が出来ます。

なお、表示されるモーダルは自身で設定したCSSの影響を受ける作りになってます。

たとえばCSSファイルで<body>タグにpadding-top:0などとCSSを設定していると、text部分がtitleにめり込んで表示されない・・・といった事が起きます。(私がそうでした)


記載している事以外もいろいろ出来そうですが、私の拙い英語力ではこれが限界です。
英語が出来る方はシェパード本家のサイトGitHubを見てみてください。

次回は「マニュアルを自動実行させたいけど、一度見た人は自動実行させない

を書こうと思います。

“Webアプリにマニュアル埋込(前編)” への1件のコメント

  1. […] さて、前回はシェパードナビの使い方を説明しました。 […]

コメントを残す

メールアドレスが公開されることはありません。 が付いている欄は必須項目です