tyoshikawa1106のブログ

- Force.com Developer Blog -

SFDC:Aura Documentationによる仕様の管理について

SalesforceのLightningにはAura Documentationというドキュメントページが用意されています。このページでLighting開発で利用できる標準コンポーネントの情報を確認できるのですが、その他にも自分達で開発したコンポーネントの情報も確認することができます。

f:id:tyoshikawa1106:20151123104640p:plain

このAura Documentationですが、自分達で開発したコンポーネントについては任意の情報を記載することが可能となっています。今回はどのような情報を記載できるか確認してみたいと思います。

Description

Descriptionにはそのコンポーネントについての説明を記載できます。機能の概要についてと使用時に注意することなどについてまとめておくといいと思います。
f:id:tyoshikawa1106:20151123122300p:plain


Descriptionに説明を記載するには、auradocファイルを用意する必要があります。このファイルは開発者コンソールの右側にあるワークパネルのDOCUMENTAIONをクリックすることで作成できます。


次のように『aura:description』タグ内に記述した内容がDescriptionに表示されます。
f:id:tyoshikawa1106:20151123123024p:plain

Attributes

AttributesにはLightning Componentで利用するaura:attributeタグの情報が表示されます。これでaura:attributeタグで宣言した各変数が何に利用されるかについて説明することができます。
f:id:tyoshikawa1106:20151123123431p:plain


これはaura:attributeタグのdescription属性に記述した内容が表示されます。
f:id:tyoshikawa1106:20151123123723p:plain

Handled Events

これもAttributesのようにコンポーネント内で使用しているHandled Eventsの情報が表示されます。
f:id:tyoshikawa1106:20151123124445p:plain


次のようにaura:handlerタグのdescription属性に記述した内容が表示されます。
f:id:tyoshikawa1106:20151123124803p:plain

Examples

これがAura Documentationで一番便利な機能だと思います。Examplesタグを選択することで表示できます。先程のDescriptionでは概要についての簡単な説明を記述しました、こちらではより詳細な情報を記述することが可能です。
f:id:tyoshikawa1106:20151123125900p:plain


Examplesに説明を表示するにはauradocファイルのaura:exampleタグを用意する必要があります。
f:id:tyoshikawa1106:20151123130152p:plain


rel属性には対象のコンポーネント名を指定して、label属性にタイトル的な内容を記述します。aura:exampleタグ内に詳細情報を記述していけるのですが、このとき一部HTMLタグの利用が可能となっています。
f:id:tyoshikawa1106:20151123131901p:plain


上記のように記述した結果がこちらです。
f:id:tyoshikawa1106:20151123131933p:plain

Examplesタグの便利機能と注意点

Examplesタグではコンポーネントのプレビューが表示されます。ただのプレビューではなく実際に動かすことが可能となっています。
f:id:tyoshikawa1106:20151123132358p:plain


タブを切り替えてグラフを表示したり・・・
f:id:tyoshikawa1106:20151123132420p:plain


編集用のポップアップを表示したりといったことが可能です。
f:id:tyoshikawa1106:20151123132454p:plain


このような感じでどんなコンポーネントか確認できるようになっています。このプレビュー機能すごく便利なのですが、ひとつ注意点がありました。


次のように編集画面でレコードの更新を試してみます。
f:id:tyoshikawa1106:20151123132901p:plain


Examplesタグ内の表示も更新されたことを確認できます。
f:id:tyoshikawa1106:20151123133004p:plain


このときの更新はExamplesタグ内だけかと思ったのですが、実は実際にレコード更新処理が実行されています。
f:id:tyoshikawa1106:20151123133138p:plain


Examplesタグで表示できるコンポーネントはプレビューではなく、埋め込み表示ができるという認識が正しいみたいです。


Aura Documentationページを表示するにはSalesforceユーザでログインしている必要があるので知らない間に動かされるということは無いのですが、お試し間隔で試してしまいそうなのでこの仕組みには注意が必要だと思います。


ということでAura DocumentationページのExamplesタグを利用する場合は、判定用のフラグを用意するなどして更新や削除ができないようにした方が良さそうです。

さいごに

ひとつ注意点もありましたが、このAura Documentationを利用することでいままで苦労した仕様書の作成も効率よく行えるのではないかと思います。クラウド上で管理できるので常に最新の仕様書として扱うことができます。


また書式も統一され他の開発者がつくったコンポーネントでも同じように管理できるんじゃないかと思います。


以上、Aura Documentationによる仕様の管理についてでした。Lightning Componentを開発するときはAura Documentationのことも意識しておくと良さそうでした。