最初にASDをインストールしてください。
https://github.com/koriym/app-state-diagram#run-with-docker
次にスケルトンファイルprofile.xml
を作成します。
<?xml version="1.0" encoding="UTF-8"?>
<alps
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://alps-io.github.io/schemas/alps.xsd">
</alps>
スキーマをサポートするエディターが便利です。補完が効き、バリデーションも行われます。フリーのWebStormがあります。
まずは、WebStormでスケルトンファイルを作成してみましょう。
ALPSでは意味をIDとして定義します。
dateCreated
(作成日付)を追記してみましょう。
<?xml version="1.0" encoding="UTF-8"?>
<alps
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://alps-io.github.io/schemas/alps.xsd">
+ <descriptor id="dateCreated"/>
</alps>
では早速ALPSファイルをASDで表示してみましょう。
以下のコマンドでASDを実行してASDドキュメントを作成しましょう。
asd --watch ./profile.xml
http://localhost:3000を開いて確認してください。1つ単語が登録されたのが確認できます。
以後はファイルを保存するとASDドキュメントが再描画され、ASDツールの操作の必要はありません。
title
やdoc
で説明を加えることができます。
<descriptor id="dateCreated" title="作成日付"/>
<descriptor id="dateCreated">
<doc format="markdown">ISO8601フォーマットで記事の作成日付を表します</doc>
</descriptor>
ALPSドキュメントはアプリケーションで使う用語の辞書になります。このALPSアプリケーションでは作成日付を表す時はcreated_date
でも、created
でもなくdateCreated
と表します。
この意味に紐づけられたIDをセマンティックディスクリプタ(意味的記述子)といいます。ALPSドキュメントはその集合です。
言葉による説明よりもっと良い方法はdef
でスタンダードな語句定義へリンクすることです。車輪の再発明を防ぎます。
<descriptor id="dateCreated" def="https://schema.org/dateCreated" />
有名なボキャブラリサイトには以下のものがあります。
ALPSの重要な役割の1つはアプリケーションのボキャブラリ辞書になることです。利用者が同じID、同じ意味を使います。
セマンティクディスクリプタはセマンティックディスクリプタを含むことがあります。
例えば、BlogPosting
(ブログ記事)はarticleBody
(本文)とdateCreated
を含みます。 情報は情報を含み、その含んだ情報も他の情報に含まれます。このような情報のアレンジがタクソノミーです。<descriptor>の中に<descriptor>を記述することで階層を表します。
<alps
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://alps-io.github.io/schemas/alps.xsd">
<!-- Ontology -->
<descriptor id="id" title="id"/>
<descriptor id="articleBody" title="本文"/>
<descriptor id="dateCreated" title="作成日付"/>
<!-- Taxonomy -->
<descriptor id="BlogPosting" title="ブログ記事" >
<descriptor href="#id"/>
<descriptor href="#dateCreated"/>
<descriptor href="#articleBody"/>
</descriptor>
<descriptor id="Blog" title="ブログ記事リスト">
<descriptor href="#BlogPosting"/>
</descriptor>
</alps>
上記は、記事の本文(articleBody
)を含んだブログ記事(BlogPosting
)、その記事を含んだブログ記事リスト(Blog
)を表しています。
ALPSファイルの<!-- Taxonomy -->
ブロックでは他のセマンティックディスクリプタをhref
でインラインリンクして利用しています。
他にローカルやWeb上の他のファイルをリンクすることもできます。
<descriptor href="definition.xml#dateCreated"/>
<descriptor href="http://example.com/dateCreated.xml#dateCreated"/>
ファイルを保存してASDドキュメントを確認してみましょう。
Webページは情報だけでなく他のページへのリンクやアクションのフォームを含むことができますが、このような情報の相互作用をコレオグラフィーと呼びます。
以下の3つのタイプがあります。
safe
はHTMLで言うとAタグ、HTTPではGETです。安全な遷移で、サーバー側のリソース状態は変化しません。
idempotent
(アイデムポテント)はリソース状態は変更されますが冪等性があり、何度繰り返しても同じ結果になります。
unsafe
も同じようにリソース状態は変更されますが冪等性がありません。繰り返し実行には注意が必要です。
safeはGET
、idempotentidempotentはPUT
またはDELETE
、unsafeはPOST
とそれぞれのHTTPのメソッドに対応します。
下記のように他のdescriptor
に含めます。
<descriptor id="BlogPosting" " title="ブログ記事">
<descriptor href="#id"/>
<descriptor href="#dateCreated"/>
<descriptor href="#articleBody"/>
<descriptor id="goBlog" type="safe" rt="#Blog" title="ブログ記事リストを見る"/>
</descriptor>
遷移に必要なdescriptorは含めます。
<descriptor id="goBlogPosting" type="safe" rt="#BlogPosting" title="ブログ記事を見る">
<descriptor href="#id"/>
</descriptor>
以下のアトリビュートはタイプに関わらず利用することができます。
属性を加えます。
<descriptor id="ticketList" tag="ontology collection" />
属性をフィルターしてASDを描画することができます。やってみましょう。
[スクリーンショット]
メタ情報とリンクします。
<descriptor id="dateCreated">
<link href="https://github.com/koriym/app-state-diagram/issues" rel="issue" title="Issue list"/>
</descriptor>
href
を使って、他のALPSドキュメントへリンクすることもできます。
<descriptor href="definition.xml#dateCreated"/>
<descriptor href="http://example.com/dateCreated.xml#dateCreated"/>
アルプスのファイルにメタ情報を付け加えるにはこのようにします。
<?xml version="1.0" encoding="UTF-8"?>
<alps>
<title>ALPS Blog</title>
<doc>An ALPS profile example for ASD</doc>
<link rel="issue" href="https://github.com/koriym/app-state-diagram/issues"/>
</alps>