기능 보여짐(Capability Presentations)

기능 보여짐(Capability Presentation)은 SmartThings 앱의 유저 인터페이스(UI)에서 기능(Capability)의 속성(Attributes)과 명령(Commands)이 보여지는 디자인을 고릅니다.

기능 보여짐(Capability Presentation)은 기존 기능(Capability)의 ID와 버전을 써서 만듭니다. 보여짐(Presentation)에서는 기능(Capability)이 SmartThings 앱에 어떻게 보여지는지, 액션의 상태가 어떻게 보여지는지, 자동화에서 조건(Conditions)과 액션(actions)이 어떻게 보여지는지를 고를 수 있습니다.

기능 보여짐(Capability Presentation)은 SmartThings 앱의 세 가지 보기의 유저 인터페이스(UI)를 바꿀 수 있습니다.

* 대시보드 보기
* 디테일 보기(detailView)
* 자동화 보기

## 대시보드 보기

대시보드 보기는 SmartThings 앱의 기본 보기방식입니다. 여기에는 유저가 즐겨찾는 기기와 기기의 상태를 볼 수 있는 리스트가 있습니다. 대시보드는 한 번에 많은 기기를 보여주기 때문에 각 기기의 기능(Capability)을 보여주는 공간은 작습니다. 아래에서 대시보드 보기에서 볼 수 있는 기본 속성(Attributes)을 살펴봅니다.

### `State`

`state` 의 속성(Attributes)을 써서 기기의 기능(Capability)의 현재 상태를 보여줄 수 있습니다. 속성(Attributes) 값이 있는 이미 짜여진 문자열일 수 있습니다. 예를 들어, `{{<attributeName>.value}}{{<attributeName>.unit}}` 은 셈법으로 속성(Attributes)의 현재의 온도를 보여주는 데에 쓸 수 있습니다

### `State`의 `Alternatives`

`Partially open`.`state` 모델의 `Alternatives` 을 쓰면 속성 값을 UI의 다른 문자열(string)로 바꿀 수 있습니다. 아래 예에서는 `partial` 값을 보여주지 않고 UI가 `Partially open`으로 보여줍니다.

### 액션(Actions)

대시보드 액션(actions) 으로 유저는 SmartThings의 대시보드 보기에서 바로 기기를 움직일 수 있습니다.

대시보드 액션(actions)에는 displayType이 있습니다. 쓸 수 있는 displayType은 다음과 같습니다.

* `pushButton`
* `toggleSwitch`
* `switch`
* `standbyPowerSwitch`
* `statelessPowerToggle`
* `playPause`
* `playStop`

### 대시보드의 예

아래의 대시보드의 예는 위에서 설명한 컨셉을 맞춤 기능(Custom Capabilities) 섹션에서 만든 차고 문 기능에 불러옵니다. *상태(states)* 에는 문의 상태가 보여지고 *액션(actions)* 에는 문을 움직이기 위한 토글 버튼이 보여집니다. 토글 버튼의 "on" 및 "off" 상태를 각 상태에서 버튼을 눌렀을 때 전송되는 *setDoor("open")*과 *setDoor("closed")* 명령에 매핑하는 방법을 조심히 살펴보세요. *alternatives*는 실제 속성 값 대신 표시되는 문자열(strings)을 지정합니다(예: 대시보드에서 "partial"이라고 보여지는 대신에 "Partially open"이라고 보여지도록 합니다).

```
"dashboard": {
  "states": [
    {
      "label": "{{door.value}}",
      "alternatives": [
        {
          "key": "closed",
          "value": "Closed",
          "type": "inactive"
        },
        {
          "key": "open",
          "value": "Open",
          "type": "active"
        },
        {
          "key": "opening",
          "value": "Opening",
          "type": "active"
        },
        {
          "key": "closing",
          "value": "Closing",
          "type": "active"
        },
        {
          "key": "partial",
          "value": "Partially open",
          "type": "active"
        }
      ]
    }
  ],
  "actions": [
    {
      "displayType": "toggleSwitch",
      "toggleSwitch": {
        "command": {
          "name": "setDoor",
          "on": "open",
          "off": "closed",
          "argumentType": "string"
        },
        "state": {
          "value": "door.value",
          "on": "open",
          "off": "closed",
          "valueType": "string"
        }
      }
    }
  ]
}
```

## 디테일 보기(detailView)

유저가 대시보드에서 기기를 탭하면 디테일 보기(detailView)가 보여집니다. 디테일 보기(detailView)에는 `label`과 `displayType`이 있어야 합니다. 쓸 수 있는 displayType은 다음과 같습니다.

* `toggleSwitch`
* `standbyPowerSwitch`
* `switch`
* `slider`
* `pushButton`
* `playPause`
* `playStop`
* `list`
* `textField`
* `numberField`
* `stepper`
* `state`

### 디테일 보기(detailView)의 예

아래 예는 lable이 있는 드롭다운 리스트의 생김새로 움직일 수 있는 차고 문 기능(Capability)을 보여줍니다. 기능(Capability)과 마찬가지로 명령(Commands)에는 속성(Attributes)보다 더 작은 alternatives들이 있습니다. 원한다면 presentation에서 대체 명령(Commands)을 더 제한할 수 있습니다. 그러면 유저가 디테일 보기(detailView)에서는 할 수 있지만 API 호출에서는 할 수 없는 일을 움직일 수 있습니다.

```
"detailView": [
  {
    "label": "Garage Door Status",
    "displayType": "list",
    "list": {
      "command": {
        "name": "setDoor",
        "alternatives": [
          {
            "key": "closed",
            "value": "Closed",
            "type": "inactive"
          },
          {
            "key": "open",
            "value": "Open",
            "type": "active"
          }
        ],
        "argumentType": "string"
      },
      "state": {
        "value": "door.value",
        "valueType": "string",
        "alternatives": [
          {
            "key": "closed",
            "value": "Closed",
            "type": "inactive"
          },
          {
            "key": "open",
            "value": "Open",
            "type": "active"
          },
          {
            "key": "opening",
            "value": "Opening...",
            "type": "active"
          },
          {
            "key": "closing",
            "value": "Closing...",
            "type": "active"
          },
          {
            "key": "partial",
            "value": "Partially open",
            "type": "active"
          }
        ]
      }
    }
  }
]
```

## 자동화 보기

기능 보여짐(Capability Presentation)의 자동화 섹션에서는 자동화에서 기능(Capability)을 쓰는 방법을 알아보겠습니다.

### 조건(Conditions)

조건은 `if` 문과 같은 작업에 대한 트리거로 쓰이는 요인입니다(여기에서 조건에 대해 자세히 알아보기). 자동화 보기의 이 섹션은 유저가 켤 수 있는 자동화 값을 고를 수 있는 방법을 결정합니다.

이 기능(Capability)에 대한 자동화가 켜지는 조건(Conditions)은 다음의 보기 타입(displayType)으로 렌더링할 수 있습니다.

* `slider`
* `list`
* `numberField`
* `textField`

### 액션(Actions)

Presentation의 액션(action) 섹션은 `condition`이 생기거나 켜지면 유저가 자동화의 효과(또는 액션(action))를 만들 수 있는 방법을 정의합니다.

자동화가 켜질 때 할 수 있는 일은 다음의 보기 타입(displayType)으로 렌더링할 수 있습니다.

* `slider`
* `list`
* `numberField`
* `textField`

### 자동화의 예

아래의 자동화 보기의 예에서는 볼륨 상태 및 재생 상태에 따라 자동화를 할 수 있도록 합니다. 이렇게 하면 볼륨 조건으로 자동화를 설정할 수 있고 자동화 보기의 액션(action)을 통해 기기가 자동화를 써서 음악을 틀거나 잠시 멈출 수 있습니다.

```
"automation": {
    "conditions": [
        {
            "label": "Volume",
            "displayType": "slider",
            "slider": {
                "range": [
                    0,
                    11
                ],
                "step": 1,
                "value": "volume.value"
            }
        }
    ],
    "actions": [
        {
            "label": "Player actions",
            "displayType": "list",
            "list": {
                "command": "setPlaybackStatus",
                "alternatives": [
                    {
                        "key": "playing",
                        "value": "Playing"
                    },
                    {
                        "key": "paused",
                        "value": "Paused"
                    }
                ]
            }
        }
    ]
}
```

이 예에서는 자동화에서 기기의 볼륨을 바꿀 수 없습니다. 이 기능을 쓰려면 `actions` 안에 있는 `setPlaybackStatus`다음에 해당 항목을 추가하십시오.

## 당신의 기능 보여짐(Capability Presentation)을 만드세요

다음은 맞춤형 차고 문의 기능(Capability)에 대한 기능 보여짐(Capability Presentation) 파일입니다.

```
{
  "dashboard": {
    "states": [
      {
        "label": "{{door.value}}",
        "alternatives": [
          {
            "key": "closed",
            "value": "Closed",
            "type": "inactive"
          },
          {
            "key": "open",
            "value": "Open",
            "type": "active"
          },
          {
            "key": "opening",
            "value": "Opening",
            "type": "active"
          },
          {
            "key": "closing",
            "value": "Closing",
            "type": "active"
          },
          {
            "key": "partial",
            "value": "Partially open",
            "type": "active"
          },
          {
            "key": "jammed",
            "value": "Jammed or unresponsive",
            "type": "active"
          }
        ]
      }
    ],
    "actions": [
      {
        "displayType": "toggleSwitch",
        "toggleSwitch": {
          "command": {
            "name": "setDoor",
            "on": "open",
            "off": "closed",
            "argumentType": "string"
          },
          "state": {
            "value": "door.value",
            "on": "open",
            "off": "closed",
            "valueType": "string"
          }
        }
      }
    ],
    "basicPlus": []
  },
  "detailView": [
    {
      "label": "Garage Door Status",
      "displayType": "list",
      "list": {
        "command": {
          "name": "setDoor",
          "alternatives": [
            {
              "key": "closed",
              "value": "Closed",
              "type": "inactive"
            },
            {
              "key": "open",
              "value": "Open",
              "type": "active"
            }
          ],
          "argumentType": "string"
        },
        "state": {
          "value": "door.value",
          "valueType": "string",
          "alternatives": [
            {
              "key": "closed",
              "value": "Closed",
              "type": "inactive"
            },
            {
              "key": "open",
              "value": "Open",
              "type": "active"
            },
            {
              "key": "opening",
              "value": "Opening...",
              "type": "active"
            },
            {
              "key": "closing",
              "value": "Closing...",
              "type": "active"
            },
            {
              "key": "partial",
              "value": "Partially open",
              "type": "active"
            },
            {
              "key": "jammed",
              "value": "Jammed or unresponsive",
              "type": "active"
            }
          ]
        }
      },
      "state": null
    }
  ],
  "automation": {
    "conditions": [
      {
        "label": "Garage Door Status",
        "displayType": "list",
        "list": {
          "alternatives": [
            {
              "key": "closed",
              "value": "Closed",
              "type": "inactive"
            },
            {
              "key": "open",
              "value": "Open",
              "type": "active"
            },
            {
              "key": "partial",
              "value": "Jammed or unresponsive",
              "type": "active"
            }
          ],
          "value": "door.value",
          "valueType": "string"
        }
      }
    ],
    "actions": [
      {
        "label": "Garage Door",
        "displayType": "list",
        "list": {
          "alternatives": [
            {
              "key": "closed",
              "value": "Closed",
              "type": "inactive"
            },
            {
              "key": "open",
              "value": "Open",
              "type": "active"
            }
          ]
        }
      }
    ]
  },
  "id": "angryofmyhomeminister6617.customGarageDoor",
  "version": 1
}
```

이제 SmartThings CLI에서 아래의 명령어를 써서 SmartThings 플랫폼에 올립니다. 이 명령어 중에 `presentation.json`은 위의 예제 파일의 이름입니다.

```
smartthings capabilities:presentation:create angryofmyhomeminister6617.customGarageDoor 1 -i presentation.json
```

다음으로 기능 번역(Capability Translations)을 써서 여러 말(언어)로 레이블과 값을 정의하고 Samsung Galaxy의 말(언어) 설정에 맞춰서 손 안대고 맞는 말(언어)로 바꿔서 보여주는 방법을 살펴보겠습니다.