guide 개발 Guide
javascript로 작성된 예제 코드 부분을 제외하고,
Api 문서는 정확한 자료형이 표시되는 typescript 스타일로 설명되어 있다.
업무용 앱의 신뢰성을 위해 최대한 자료형에 맞게 Api를 사용해야 한다.
기본적으로 OOP(객체지향 프로그래밍)에 기반 설계되고 구현되었다.
Api 문서에는 base 클래스, 계승된 메소드 및 속성 등이 명시되어 있다.
Namespace
RealGrid-Touch 라이브리의 네임스페이스는 RealTouch 이다.
const list = RealTouch.createListControl(document, 'realtouch');
list.setConfig(config);
list.data = data;
MVC
RealGrid-Touch 컨트롤은 전형적인 UI 개발의 기본 구조가 되는 MVC 패턴을 사용하고 있다.
모델(data)과 뷰는 완전히 분리되어 있고, RtListControl이 두 레이어를 연결하는 컨트롤러가 된다.
모델의 변경은 뷰에 즉각 반영되고, 컨트롤 UI를 통해 모델을 변경할 수 있다.
모델 layer에서는 뷰를 직접적으로 참조하지 않는다.
최대한 모델 Api를 이용해서 개발해야 하고, view는 코드 대신 최대한 템플릿을 통해 설정으로 해결해야 한다.
Event
주요 객체인 RtListControl과 RtListData에는 개발에 필요한 이벤트들이 구현되어 있는데, 이벤트별 특성에 따라 필요한 속성들이 포함된 단일 매개변수가 전달되는 이벤트 콜백을 설정한다. 대부분 리스트 컨트롤이나 데이터 객체와 이벤트가 발생한 데이터행 번호가 포함되어 있다.
// 데이터행을 tap했을 때 발생
list.onRowClick = (args) => {
args.control.toggleChecked(args.row); // checked 상태 변경
};
콜백 내에서 값을 리턴해야 하는 경우에도 매개변수에 전달된 특정 속성에 값을 설정하게 된다.
list.onRowSwipe = args => {
// 제스처 진행 방향이 오른쪽으로 진행되었다면
if(args.dir === "right"){
// rowSwipeAction으로 설정한 기본동작을 무시한다.
args.cancel = true;
}
};
API 문서에 각 이벤트별로 매개변수의 속성들이 설명되어 있다.
(주의) args 매개변수를 콜백 밖에 저장 후 사용할 수 없다. 라이브러리 내에서 재사용할 수 있으므로 속성들이 언제든 변경될 수 있다.
주의 사항
- Api 문서에 공개되지 않은 숨겨진 클래스나 함수 및 속성 등을 사용해서는 안된다. 특히,'$'나 '_'로 시작하는 함수나 속성 및 객체는 내부 구현 상황에 따라 언제든 변경될 수 있으므로 절대 접근(호출, 수정)해서는 안된다.
- Api에 명시된 자료형대로 매개변수나 속성 값을 지정해야 한다.
- Api에 명시된 enum 값들 대신 엉뚱한 값을 사용해서는 안된다.
- 모든 css 스타일을 사용할 수 없다. HTML의 구성 배치 및 크기 등은 RealGrid-Touch가 레이아웃 등을 통해 관리하므로, 그 속성들을 직접 수정하면 컨트롤의 레이아웃 구성이 깨지게 된다.
명시적으로 HTML 엘리먼트의 위치나 크기, 표시 여부를 지정하는 css 속성을 설정해서는 안된다. HTML 엘리먼트의 내용의 크기나 모양을 변경하는 스타일 속성들만을 사용해야 한다. 크기 및 배치는 전적으로 컨트롤이 제공하는 템플릿 기반 레이아웃으로 구현해야 한다.
컨트롤 레이아웃 구성 중 외부에서 설정한 위치, 크기 스타일 속성들이 대부분 overwrite되므로 설정이 의미가 없게 된다. 크기나 위치 지정이 가능한 경우 레이아웃이나 renderer, editor 모델에 존재하는 크기나 위치를 지정하는 별도의 속성을 사용해야 한다.
사용 가능한 스타일 속성은 아래 정도이다.
- color
- background-*
- border-*
- font**-*
- letter-spacing
- line-height
- padding-*
- text-align
- text-decoration-*
위 스타일들 중에도 설정할 수 없는 경우가 있을 수 있다.
json객체로 설정하는 style 객체는 단일 값처럼 취급해야 한다. 즉, 설정된 객체의 속성 일부를 변경해도 컨트롤에 반영되지 않는다. 기존 스타일을 최대한 유지하고 style을 변경하기 위해서는 기존 값을 복사해서 설정한 후 style 속성을 다시 설정해야 한다.
const style = Object.assign({}, model.style);
style.color = 'blue';
model.style = style;
콜백(callback) 매개변수
- 이벤트 콜백 혹은, 함수 매개변수나 속성으로 설정되는 콜백에서, 명시적으로 허용되는 경우를 제외하고 콜백 매개변수로 전달되는 객체의 값은 콜백 외부에서 변경해도 유지되지 않는다. 즉, 여러 이벤트에서 공유될 수 있으므로 매개변수를 따로 저장해서 사용해서는 안된다.
이미지 사용
- 이미지를 사용할 때는 이미지 렌더러를 활용해야 하며 배경 이미지의 경우에도 마찬가지로 렌더러의 스타일 통해 배경 이미지를 적용하는 것을 권장한다.
API 문서 주의 사항
- 이 문서를 포함 RealGrid-Touch의 모든 문서에서 RtListControl 객체는 '리스트 컨트롤' 혹은, 그냥 '컨트롤'로 호칭한다. 데이터 행들이 표시되는 주 영역을 구분해서 '리스트'로 호칭한다.
- '데이터행을 tap...'과 '데이터행을 클릭...'은 사용자가 기기 화면을 touch down/up 한 것을 의미한다. 즉, tap과 click을 동일한 의미로 사용한다.
- 예제 코드에 (특히, 설정 코드에 많이) 포함된 '...'은 연산자가 아니라 코드에 표시된 것 이 외에 많은 부분이 있다는 것을 나타낸다.
list.setConig({
options: {
...
},
...
});