yaml reference

셀렉트에서 지원하는 yaml 기본 정보들을 한 곳에 모아, 쉽게 이해하고 참고할 수 있게 하였습니다.

📘

yaml이란?

YAML은 '사람이 쉽게 읽을 수 있는' 데이터 직렬화 양식이며 설정 파일을 작성하고 관리할 때 많이 쓰입니다. 셀렉트로 어드민을 yaml로 만들 때 장점과 특징에 대해 궁금하시다면 "코드가 아닌 스펙으로 어드민을 만든다면"이라는 글을 읽어보세요.

title

어드민 사용자가 보는 페이지의 상단 왼쪽에 보여지는 제목입니다.

title: 어드민 제목

menus

어드민 사용자 페이지의 메뉴를 설정할 수 있습니다.

menus.path

메뉴에 접근하는 경로입니다. 링크를 공유했을 때 사용자가 이해하기 쉬운 네이밍을 한다면 좋습니다.

menus.name

메뉴에 표시되는 이름입니다.

menus:
- path: user
  name: 사용자

menus.group

group이 없는 경우 모든 메뉴는 같은 그룹으로 인식됩니다. 메뉴들을 따로 묶고 싶으신 경우 group을 이용해주세요.

menus:
- path: user
  name: 사용자
  group: u
- path: user/active
  name: 활성 유저
  group: u

menus.placement

메뉴는 기본적으로 왼쪽 영역과 오른쪽 탭에 둘다 나타납니다. 왼쪽 또는 탭에만 메뉴를 보여주고 싶은 경우 placement를 이용해보세요.

placement: menu-only
placement: tab-only
placement: expand-only
menus:
- path: user
  name: 사용자
  group: u
- path: user/active
  name: 활성 유저
  group: u
  placement: tab-only

menus.redirect

메뉴 클릭 시 redirect 시킬 path 또는 링크를 지정합니다.

menus:
- path: user
  name: 사용자
  group: u
  redirect: user/all
  placement: menu-only
- path: user/all
  name: 전체 사용자
  group: u
  placement: tab-only
- path: user/active
  name: 활성 유저
  group: u
  placement: tab-only

type: divider

메뉴 사이에 시각적으로 영역을 구분짓고 싶을 때 사용할 수 있습니다.

menus:
- path: user
  name: 사용자
  group: u
  
- type: divider

- path: payment
  name: 결제
  group: p

pages

페이지들을 구성하기 위한 최상위 키

pages.path

개별 페이지를 메뉴와 연결할 수 있습니다.

pages.blocks

페이지 안을 블록으로 구성합니다.

menus:
- path: user
pages:
- path: user
  blocks:

blocks

페이지 안은 블록들로 이루어져 있습니다. 1개 또는 여러개를 추가할 수 있으며, 블록의 종류는 query, http, markdown 이 있습니다.

blocks:
- type: query
- type: http
- type: markdown

blocks.type

blocks:
- type: query
  name: 샘플 쿼리
  resource: sample.db
  sqlType: select # update, insert
- type: http
  name: 샘플 http
  axios: GET
- type: markdown
  content: type anything

type: query

SQL 쿼리의 select, update, insert를 모두 사용할 수 있습니다.

sqlType: select
sqlType: update
sqlType: insert
- type: query
  resource: sample.db
  sqlType: select
  sql: select * from user limit 10

type: http

REST API와 GraphQL API 모두 사용 가능합니다. axios 용법을 그대로 따릅니다. axios에 대한 자세한 설명은 여기서 확인해보세요.

method: GET

- type: http
  axios:
    method: GET
    url: https://testapi.com/v1/33iac2d
  rowsPath: rows

method: POST

- type: http
  axios:
    method: POST
    url: https://testapi.com/v1/33iac2d
    data:
      'user_id': user-{{id}}
      'v': "{{API_VERSION}}" 
  params:
  - key: id
  - key: API_VERSION
    valueFromEnv: true

graphQL

- type: http
  name: http 샘플
  axios:
    method: POST
    url: https://testapi.com/v1/33iac2d
    data:
      query: >
        {
          getUser(id: "test") {
            id
            name
            email
          }
        }

type: markdown

마크다운 용법에 맞춰서 내용을 작성할 수 있습니다. 페이지에 대한 설명이나 유의사항 등을 작성해보세요.

- type: markdown
  content: >
    write something

blocks.paginationOptions

주로 조회할 때 페이지네이션을 추가해서 필요한 정보만 빨리 볼 수 있게 도와줍니다.

perPage

페이지 당 보여지는 기본 row 개수를 지정합니다.

- type: query
  ...
  paginationOptions:
    enabled: true
    perPage: 10

blocks.searchOptions

조회한 내역들을 검색할 수 있게 지원합니다. 프론트 레벨에서 검색하기 때문에 서버 부하를 줄일 수 있는 장점이 있습니다.

- type: query
  ...
  searchOptions:
    enabled: true

searchOptions.trigger

테이블 검색 시, 내용을 입력하고 엔터(enter)를 눌렀을 때만 조회하게 설정할 수 있습니다. 데이터를 안정적으로 조회할 수 있는 장점이 있습니다.

searchOptions:
  enabled: true
  trigger: enter

searchOptions.placeholder

테이블의 검색 필드 안에 placeholder 값을 입력할 수 있습니다. 사용자가 참고할 수 있는 정보를 기입할 수 있습니다.

searchOptions:
  enabled: true
  placeholder: '입력한 검색어로 찾습니다.'

blocks.columnOptions

주로 데이터 조회 결과를 다르게 표현하고 싶을 때 이용합니다. columnOptions와 columns 사용 시 값의 데이터 타입이 text로 지정됩니다. 데이터 타입을 바꾸고 싶은 경우 type키를 이용해주세요.

- type: query
  ...
  columnOptions:
  - field: id
  - field: name
    label: 이름
  - field: json
    format: json

columnOptionsAppend

전체 필드를 보여주면서, 일부 필드만 columnOptions로 수정하고 싶을 때 사용하세요.

columnOptionsAppend: true
columnOptions:
- field: name
  label: 이름

blocks.columns

columnOptions와 동일한 기능이고 양식이 다릅니다.

- type: query
  ...
  columns:
    id:
    name:
      label: 이름
    rank:
      label: 랭킹
      type: number
    created_at:

columns.updateOptions

한번에 여러 필드를 수정하지 않고, 낱개로 처리할 수 있습니다.

columns:
  id:
  updateOptions:
    type: query
    ...
    confirm: true

confirm: true
쿼리 또는 API 블록을 실행할 때, 한번 더 확인할 수 있게 합니다.

columns.valueAs

각 컬럼의 값들을 고정된 텍스트로 표시할 수 있습니다. 데이터를 '링크'나 '클릭' 같은 이름으로 감쌀 수 있습니다.

# columns 용법
columns:
  customer_link: # column name
    format: url
    valueAs: 링크
    
# columnOptions 용법
columnOptions:
- field: customer_link
  format: url
  valueAs: 링크

blocks.tabOptions

블록 안에 세부 탭을 여러개 추가할 수 있습니다.

blocks:
- type: query
  ...
  tabOptions:
    autoload: 1
    tabs:
    - name: 주문
      blocks:
    - name: 결제
      blocks:

blocks.params

블록 안에서 parameter를 쓸 수 있습니다. 데이터를 조회하거나 생성, 수정할 때 input 역할을 하게 됩니다.

- type: query
  ...
  params:
  - key: id
    label: 아이디(ID)

📘

params의 key 값은 영어 알파벳을 지원합니다.

key 의 값에 한글 등 알파벳이 아닌 문자를 입력하면 정상적으로 작동하지 않게 됩니다. 꼭 key: id 와 같이 영어 알파벳을 이용해주세요.

parameter에 특정 값을 미리 입력하거나, 다른 곳에서 가져와서 입력하고 싶을 때 아래와 같은 키를 사용하세요.

key(키)설명
valueFromRowviewModal 안에서 사용
valueFromSelectedRowsselectOptions가 있는 actions 안에서 사용
defaultValue기본값을 설정하고 싶을 때 이용
defaultValueFromRowviewModal 안에서 사용
valueFromEnvAPI를 호출할 때 안전한 환경변수에서 이용
valueFromUserProperty사용자 속성에서 값을 가져와서 이용

params.valueFromUserProperty

설정 > 계정의 사용자 이름(name)과 이메일(email) 시스템 데이터를 변수로 이용할 수 있습니다.

params:
- key: user_name
  valueFromUserProperty: "{{name}}"
- key: email
  valueFromUserProperty: "{{email}}"

params.required

특정 파라미터를 필수값으로 설정하는 방법

params:
- key: email
  required: true

params.format

input 안에 값을 입력할 때 format을 제한합니다.

format: number
format: date 
format: time
format: datetime-local
format: text

params.radio

라디오버튼으로 값을 선택하여 입력합니다.

params:
- key: status
  radio:
  - draft
  - published

값 value와 표시 label을 분리해서 이용할 수도 있습니다.

params:
- key: status
  radio:
  - value: draft
    label: 초안
  - value: published
    label: 배포 완료

radioButtonGroup

라디오 버튼을 시각적으로 더 큰 버튼 묶음으로 만들어줍니다.

radioButtonGroup: true
radio:
- all
- lead
- customer

params.checkbox

체크박스로 값을 선택하여 입력합니다.

params:
- key: active
  checkbox:
    true: active
    false: inactive

params.dropdown

드롭다운으로 값을 선택할 수 있습니다.

params:
- key: status
  dropdown:
  - draft
  - published

드롭다운 선택 시, 실제 반영되는 값과 UI에 보여지는 내용을 다르게 할 수도 있습니다.

params:
- key: status
  dropdown:
  - draft: 초안
  - published: 배포완료

params.datalist

값 선택 시, 보여지는 내용과 실제 저장되는 데이터를 구분해서 처리할 수 있습니다.

params:
- key: code
  datalist:
  - value: A000
    label: 분류1
  - value: A002
    label: 분류2

value : 데이터에 저장되는 값
label : 선택 시 보여지는 내용

params.datalist.datalistFromQuery

params:
- key: code
  datalist: true
  datalistFromQuery:
    type: query
    ...
    sql: >
      select id as 'value', code_name as 'label' from codes

params.disabled

입력 필드를 비활성화 시킵니다. 마우스 커서도 올릴 수 없게 됩니다.

params:
- key: status
  disabled: true
  defaultValue: draft

params.readonly

일반 텍스트 필드를 '읽기 전용' 상태로 설정할 수 있습니다. 마우스 커서로 내용을 복사할 수 있습니다. dropdown 이나 radio 등 선택이나 옵션 계열의 필드는 적용되지 않습니다.

params:
- key: code_number 
  readonly: true

blocks.viewModal

- type: query
  ...
  viewModal:
    blocks:
    - type: query

viewModal.displayParentRow

viewModal:
  displayParentRow: true

viewModal.dismissible

모달이 띄워졌을 때 esc로 꺼지지 않게 하고 싶을 때 dismissble을 이용해주세요.

viewModal:
  dismissible: false

viewModal.blocks.display

기본적으로 데이터를 조회하면 테이블(표) 형태로 나타납니다. 이를 특정한 형태로 바꾸고 싶을 때 display를 사용합니다.

display: form

조회한 데이터를 form 양식으로 보여줍니다.

viewModal:
  blocks:
  - type: query
    sqlType: select
    ...
    display: form

display: col-2

조회한 데이터를 피봇 테이블로 2등분합니다.

viewModal:
  blocks:
  - type: query
    sqlType: select
    ...
    display: col-2

viewModal.useColumn

특정 컬럼을 모달 조회 링크로 지정할 수 있습니다.

viewModal:
  useColumn: id
  blocks:

viewModal.params.valueFromRow

조회한 row 데이터를 모달 안에서 사용할 수 있습니다.

sql: select id, name, email, created_at from user limit 10
viewModal:
  blocks:
  - type: query
    ...
    sql: select * from order where user_id = :user_id
    params:
    - key: user_id
      valueFromRow: id

blocks.actions

selectOptions

selectOptions는 테이블의 row를 선택할 때 쓰입니다. actions와 함께 사용할 때 유용합니다.

selectOnCheckboxOnly: true

테이블의 row를 선택할 때, 체크박스 영역을 눌러야만 선택할 수 있게 설정하게 됩니다.

blocks:
- type: query
  selectOptions: 
    enabled: true
    selectOnCheckboxOnly: true

actions

버튼을 통해 특정 액션을 실행할 때 쓰입니다.

blocks:
- type: query
  selectOptions: 
    enabled: true
  actions:
  - label: 버튼
    type: query

actions.type

type: query

actions:
- type: query
  label: 전시
  resource: acme
  sqlType: update
  sql: update product set status = 'published' where id = :id
  params:
  - key: id

type: http

actions:
- type: http
  label: 결제취소
  axios:
    method: POST
    url: https://testapi.com/v1/33iac2d/payment/cancel
    data:
      'payment_id': {{id}}
      'v': "{{API_VERSION}}" 
      'status': 'cancel'
  params:
  - key: id
  - key: API_VERSION
    valueFromEnv: true

actions.label

액션 버튼이 어떤 역할을 하는지 구분하기 위해 label을 입력하시는걸 권장합니다.

actions:
- label: 전시
  placement: right top

actions.placement

placement: right top
placement: right bottom  
placement: left top
placement: left bottom

actions.single

actions 안에서 체크박스 없이, 실행 버튼만을 만들고 싶을 때 single 키를 이용하세요.

actions:
- label: 전체 초기화
  placement: right top
  single: true

actions.params.valueFromSelectedRows

선택한 row의 값을 가져와서, 파라미터에 이용할 수 있습니다.

selectOptions:
  enabled: true
actions:
- label: 버튼  
  type: query
  ...
  params:
  - key: id
    valueFromSelectedRows: true
    valueFromSelectedRowsAs: id

actions.confirmText

actions:
- label: 삭제
  confirmText: 정말 삭제하시겠습니까? 삭제 후 복구가 어려울 수 있습니다.

actions.params.promptText

prompt를 띄워서 parameter에 값을 입력할 수 있습니다.

params:
- key: memo
  valueFromPrompt: true
  promptText: 메모를 입력해주세요.

actions.modal

액션 버튼을 눌러 모달을 띄울 수 있습니다.

actions:
- label: 티켓 추가
  placement: top right
  modal: true
  type: query
  ...

actions.forEach

액션 실행 시, 선택된 row의 값들을 하나씩 연속으로 실행합니다.

actions:
- label: 티켓 추가
  placement: top left
  modal: true
  type: query
  resource: acme
  sqlType: insert
  sql: >
    insert into tickets (created_at, written_by, title, description, status, type, type_id) 
    values ( current_timestamp, :written_by, :title, :description, :status, 'order', :type_id)
  forEach: true
  params:
  - key: written_by
  - key: title
    help: >
      필드에 대한 도움말
  - key: description
  - key: status
  - key: type_id
    valueFromSelectedRows: true
    valueFromSelectedRowsAs: id