guide Templates

리스트 컨트롤은 데이터행들을 표시하는 본체와 리스트 헤더, 푸터 등 여러 영역으로 구성되는데, 각각의 데이터행과 헤더, 푸터 등은 레이아웃 구성을 통해 개발자가 원하는 대로 표시할 내용들을 배치할 수 있고, 레이아웃은 템플릿으로 구성한다.
템플릿은 데이터행이나 영역을 표시하기 위한 모든 정보를 포함하며, 표시 정보들은 param을 활용해서 실행 시간 동적으로 변경되게 할 수 있다.
템플릿은 registerTemplate이나 registerTemplates로 컨트롤에 미리 등록한 후, 등록된 이름의 컨트롤이나 각 영역의 관련 속성에 설정된다. 컨트롤에서 미리 준비한 기본 템플릿(Stock Templates)들이 존재하는 데, '@'로 시작하는 이름을 갖는다.

[주의] 템플릿 설정에 사용된 원본 json 객체는 컨트롤 내부에서 변경할 수 있고, 재사용될 수도 있으므로 외부에서 변경해서는 안된다.

레이아웃

템플릿의 주요 내용은 레이아웃을 지정하는 것이다.

const template = {
    template: {
    }
};

내부 template 속성이 지정되지 않고, 'layout' 속성이 존재하면 전체를 template으로 읽어 들인다.

const template = {
    layout: {
    }
};

레이아웃은 레이아웃필드와 자식 레이아웃으로 구성한다.

const template = {
    template: {
        type: 'layout',
        layout: 'hlinear',
        children: [{
            type: 'field',
            field: 'name',
        }, {
            type: 'field',
            fields: ['f1', 'f2', 'f3'],
        }, {
            type: 'value',
            value: 'Hello'
        }]
    }
};

좀 더 단순하게 지정할 수도 있다.

const template = {
    template: {
        layout: 'vlinear',   // type: 'layout', layout: 'vlinear' 와 동일
        children: [{
            field: 'name',  // type: 'field', field: 'name'과 동일
        }, {
            fields: ['f1', 'f2', 'f3']  // type: 'field', fields: ['f1', 'f2', 'f3']와 동일
        }, {
            value: 'Hello'
        }]
    }
};

동시에 설정되면 'fields', 'field', 'value' 순서대로 우선한다.

Params

템플릿 작성 시점에 알 수 없는 동적 값을 param으로 지정할 수 있다.
param은 값을 지정하는 위치에 '${param}'이나 '%{param}' 처럼 '${}' 혹은 '%{}'으로 둘러싸인 문자열로 지정하고, 실행 시간 템플릿이 적용되는 영역에서 값을 계산해서 대체하게 된다. 이름이 '@'으로 시작하는 param을 "stock param"이라고 하며, 라이브러리 내부에 알아서 계산해주는 값이다. 이름이 '@'으로 시작하지 않는 param은 "custom param"으로서 콜백 속성 등을 통해 값을 직접 지정해야 한다.
예를 들어 아래의 '@check_count'는 footer 레이아웃에서 현재 check된 행 수를 표시하는 stock param이고, 'checkVisible'은 footer의 layoutParams 속성으로 지정해야 하는 custom param이다.

{
    value: "${@check_count}",
    visible: '${check_visible},
}

Param에는 이름외에 기본값과 표시 형식을 동시에 지정할 수 있다.
${이름;기본값;형식} 혹은 ${이름|기본값|형식} 으로 지정하고, 기본값은 게산된 값이 undefined일때 사용된다.

{
    value: "${inc_rate;0;,0.0}",
    visible: '${check_visible;false},
}

템플릿 전체 개요

const template = {
    vars: {             // (1) 템플릿 내에서 반복 사용하는 값들.
        nameStyle: {
            ...
        }
    },
    rowProps: {         // (2) 데이터행 속성들.
        ...
    },
    rowStyle: {         // (3) 데이터행 스타일셋.
        padding: '4px 10px',        // 기본 스타일셋
        backgroundColor: '#0088ff10',
        ...,
        default: {} | 'class',      // 기본 스타일셋 or class name
        alternate: {} | 'class',    // 홀수 행
        created: {} | 'class',      // 신규 행
        updated: {} | 'class',      // 수정 행
        deleted: {} } 'class',      // 삭제 행
        selected: {} | 'class',     // 선택 행
        checked: {} | 'class',      // 체크 행
        searched: {} | 'class',     // 검색 행
    },
    template: {                 // (4) 레이아웃
        layout: 'vlinear',
        children: [{            // (5) 필드 및 자식 layout들
            type: 'field',
            field: 'addr', | '${addr-field;addr}'
        }, {
            field: 'name',      // (6) 필드
        },
        'addr',             //   필드명
        {
            fields: []          // (7) 필드 목록
        }, {
            type: 'field',
            value: 'Salary is ${salaryField;salary}',
        }, {
            value: 'Good',      // (8) 값
        }, {
            field: 'salary',
            renderer: {         // (9) 렌더러
                imageWidth: 10,
                ...,
                style: {
                    color: 'red'
                }
            },
        }, {
            space: 10           // (10) 여백
        }, {
            layout 'hlinear',      // (11) 자식 레이아웃
            children: [{
                field: 'addr',
                width: 4,       // (12) 너비, 높이
                height: '*'
                style: {
                    fontSize: '${value_fontSize;16px}',
                    ...
                } | 'className'
            }, {
                field: 'department',
                renderer: 'image',
                style: '--nameStyle'     // (13) (1)에서 설정한 vars 에 설정한 값
            }]
        }]
    },
    skeleton: {},       // (14) skeleton view
    detailed: {}.       // (15) 상세 view
    extra: {},          // (16) 추가 정보 view
    collapsed: {},      // (17) 접힌 행
    params: {}          // (18) 동적 변수들
};

(1) vars

템플릿에서 반복 사용하는 값들을 미리 준비해서 다른 곳에서 값 대신 var 이름앞에 '--'을 붙여서 사용한다.

(2) rowProps

데이터행 속성들. 1.0 버전 현재 지원하는 속성이 없다.

(3) rowStyle

데이터행 스타일셋 혹은 class name. 데이터행에 기본 적용되는 스타일들 외에, 아래 목록에 나열된 스타일셋을 추가로 지정할 수 있다.

(6) field

데이터필드와 연결된 필드 레이아웃을 지정한다.

{
    type: 'field',
    field: 'name'
}

field 속성에 필드명을 직접 지정할 수도 있다.

{
    field: 'name'
}

또는, 문자열로 지정하면 필드명으로 해석한다.

{
    type: 'layout',
    children: [
        'name',
        'addr',
    ]
}

(7) fields

둘 이상의 필드값을 표시하는 렌더러를 표시하는 필드 레이아웃을 지정한다. 단일 필드와 마찬가지로 두 가지 방식으로 지정할 수 있다.

{
    type: 'field',
    fields: ['mon_1', 'mon_2', 'mon_3']
}

{
    fields: ['mon_1', 'mon_2', 'mon_3']
}

(8) value

필드와 연결되지 않은 상수값을 표시하거나,

{
    type: 'field',
    value: 'Hello'
}

{
    value: 'Helo'
}

value에 param을 지정할 수 있다.

{
    value: ${name}
}

{
    value: ${@name}
}

만일 필드명과 동일한 stock param을 지정하면 필드를 지정하는 것과 동일하게 된다.

(9) renderer

필드 및 값 레이아웃의 렌더러를 설정한다.
지원하는 렌더러 및 설정 가능한 속성들이 나열된 렌더러 모델들은 렌더러 문서를 참조한다.

(10) space

자식 필드나 레이아웃 사이에 여백을 설정한다.

(11) layout

자식 레이아웃을 설정한다.

(12) width, height

자식 필드나 레이아웃의 너비나 높이를 명시적으로 지정한다.

(13) style

자식 레이아웃의 스타일을 지정한다. 스타일 클래스나 (1) vars 에서 선언한 스타일의 이름에 '--'를 붙여서 설정할 수도 있다. style: '--nameStyle'

(14) skeleton

RtListControl.skeletonVisible이 true로 설정되면 데이터 로딩 중에 Loading Page 대신 표시되는 view의 데이터행 layout으로 사용되는 템플릿.

(15) detailed

row가 detailed 상태일 때 사용되는 layout 템플릿.

(16) extra

row가 expanded 상태일 때, template 아래 추가 layout 템플릿. detailed가 설정되면 이 설정은 무시.

(17) collapsed

행 그룹 혹은 데이터 그룹의 그룹 header가 접힌 상태일 때 사용되는 layout 템플릿.

(18) params

layout params, 영역들의 모델에 설정된 params 보다 우선한다. 동적 변수이므로 여기에 설정되는 param 값은 주로 함수가 된다. 콜백 매개변수로 전달되는 내용은 param이 계산되는 영역별로 달라진다.

    params: {
        'renewable-vis': (args) => {
            return args.values.renewable != null;
        },
        'renewable-back': (args) => {
            return args.values.renewable ? '#ff8800' : '#0088ff';
        }
    }

컨트롤 내부에 미리 생성된 템플릿들(Stock Templates)

컨트롤 생성 시 각 영역별 템플릿이 미리 준비된다. 이 stock 템플릿들은 stock param과 동일하게 '@'로 시작되는 이름으로 등록된다.

See Also

레이아웃 개요
registerTemplates