# ALPS Tutorial

## Getting started

Install ASD utility.

https://github.com/koriym/app-state-diagram#run-with-docker

Then create a skeleton file `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>

An editor that supports schemas is useful. The completion works and validation is done. Let's create a skeleton

First, use WebStorm to [create a skeleton file](https://hackmd.io/@koriym/webstorm-for-alps#%E3%82%B9%E3%82%B1%E3%83%AB%E3%83%88%E3%83%B3%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90).

## Ontology

In ALPS, meaning is defined as ID.

Let's add `dateCreated` (creation date).

<?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>

### ASD for the first time

Now let's try to display the ALPS file with ASD.

Let's run ASD with the following command to create an ASD document.

asd --watch . /profile.xml 

You will not see a diagram because you just registered a word, but you will see that a word has been registered as a dictionary.

Also, after this, when you save the file, the ASD document will be redrawn and you will not need to use the ASD tool.


### Describe a word or phrase

You can use `title` or `doc` to add a description.

<descriptor id="dateCreated" title="date created"/>

<descriptor id="dateCreated">
    <doc format="markdown">The date the article was created in ISO8601 format</doc>.
</descriptor>

The ALPS document is a dictionary of terms used in the application. The ALPS application uses `dateCreated` for the creation date, not `created_date` or `created`.

An ALPS document is a collection of semantic descriptors.

The ALPS document is a collection of them. ### Linking to word definitions

A better way than verbal descriptions is to link to standard word definitions with `def`. This prevents reinventing the wheel.

<descriptor id="dateCreated" def="https://schema.org/dateCreated" />

Some famous vocab sites include.

* [schema.org](https://schema.org/docs/schemas.html)
* [IANA](https://www.iana.org/assignments/link-relations/link-relations.xml)

### Vocabularies

One of the important roles of ALPS is to become a vocabulary dictionary for applications. Users will use the same ID and the same meaning.

## Taxonomy

Semantic descriptors may contain semantic descriptors.

For example, `BlogPosting` (blog post) contains `articleBody` (body) and `dateCreated`. Information contains information, and the information it contains is also included in other information. Such an arrangement of information is a taxonomy. A hierarchy is represented by a <descriptor> inside a <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="body"/>
    <descriptor id="dateCreated" title="Date Created"/>

    <! -- Taxonomy -->.
    <descriptor id="BlogPosting" title="Blog Posting">
        <descriptor href="#id"/>
        <descriptor href="#dateCreated"/>
        <descriptor href="#articleBody"/>
    </descriptor>
    <descriptor id="Blog" title="Blog post list">
        <descriptor href="#BlogPosting"/>
    </descriptor>
</alps>

* The above represents a blog post (`BlogPosting`) that contains the body of the article (`articleBody`), and a blog post list (`Blog`) that contains the article.

* In the ALPS file, the `<! -- Taxonomy -->` block in ALPS file uses other semantic descriptors inline linked with `href`.

* You can also link other files locally or on the web.

<descriptor href="definition.xml#dateCreated"/>.

<descriptor href="http://example.com/dateCreated.xml#dateCreated"/>

Let's save the file and check the ASD document.

## Choreography

Web pages can contain not only information, but also links to other pages and forms of actions, and this kind of interaction of information is called choreography.

There are three types as follows.

### Type

#### safe

`safe` is the A tag in HTML, or GET in HTTP. It is a safe transition and does not change the resource state on the server side.

#### idempotent

The `idempotent` transition changes the resource state, but is power-equivalent, meaning that it can be repeated many times with the same result.

#### unsafe

`unsafe` also changes the resource state, but is not power-limited. Care should be taken when repeating it.

safe corresponds to `GET`, idempotentidempotent corresponds to `PUT` or `DELETE`, unsafe corresponds to `POST`, and so on for each HTTP method.

### Link

Include them in other `descriptors` as follows.

<descriptor id="BlogPosting" " title="Blog Posting">
    <descriptor href="#id"/>
    <descriptor href="#dateCreated"/>
    <descriptor href="#articleBody"/>
    <descriptor id="goBlog" type="safe" rt="#Blog" title="View Blog Post List"/>
</descriptor>

### Arguments.

Include any descriptor needed for the transition.

<descriptor id="goBlogPosting" type="safe" rt="#BlogPosting" title="View blog post">
    <descriptor href="#id"/>
</descriptor>

## Attributes

The following attributes can be used regardless of type.

### tag

Add a tag attribute.

<descriptor id="ticketList" tag="ontology collection" />

You can filter the attributes to draw the ASD. Let's try it.

[screenshot].

### link

Link to meta information.

<descriptor id="dateCreated">
  <link href="https://github.com/koriym/app-state-diagram/issues" rel="issue" title="Issue list"/>
</descriptor>.

## Link

You can also use `href` to link to other ALPS documents.

<descriptor href="definition.xml#dateCreated"/>
<descriptor href="http://example.com/dateCreated.xml#dateCreated"/>

## ALPS meta-information

--
Translated with www.DeepL.com/Translator (free version)