데이터 소스

App Maker 위젯과 클라이언트 API는 데이터 소스를 통해 데이터에 액세스합니다. 데이터 소스는 다음을 정의합니다.

  • 애플리케이션이 모델의 데이터를 쿼리하는 방식
  • UI가 이 정보에 액세스하는 방식

데이터 소스에는 데이터 소스의 선택된 항목을 가리키는 item 속성이 있습니다. UI에서 위젯은 item 속성을 사용하여 데이터 소스에서 현재 선택된 레코드에 대한 정보를 표시하거나 수정합니다. 클라이언트 스크립트도 이 속성을 통해 레코드에 액세스하고 레코드를 수정할 수 있습니다.

이 문서에서는 다음 내용에 대해 알아봅니다.

  1. 데이터 소스 유형
  2. 데이터 소스 수명 주기
  3. 쿼리 데이터 소스를 만드는 방법(쿼리 작성 방법 및 기타 데이터 소스 설정의 구성 방법 포함)
  4. 클라이언트 스크립트로 쿼리 데이터 소스를 구체화하는 방법
  5. 관계 데이터 소스에 대한 작업을 통해 연결된 레코드에 액세스하는 방법
  6. 생성 모드 데이터 소스를 사용하여 사용자 입력으로부터 초안 레코드를 만드는 방법

데이터 소스 유형

App Maker에는 다음과 같은 세 가지 유형의 데이터 소스가 있습니다.

  1. 쿼리 데이터 소스
  2. 관계 데이터 소스
  3. 생성 모드 데이터 소스

쿼리 데이터 소스에는 다음 사항이 저장됩니다.

  • 단일 모델의 쿼리에 대한 정보
  • 마지막 쿼리 실행을 통해 얻은 레코드

쿼리 데이터 소스는 기본적으로 모델과 동일한 이름으로 각 모델에 대해 생성됩니다. 쿼리 데이터 소스를 맞춤설정하고 모델에 대해 더 많은 쿼리 데이터 소스를 만들 수 있습니다. 결과를 필터링하거나 정렬 순서 또는 페이지 크기를 다양화하는 등 단일 모델에 대해 여러 가지 옵션을 선택하려면 더 많은 쿼리 데이터 소스가 필요할 수 있습니다. 두 개의 datasource.item 값을 비교하는 등 여러 레코드를 동시에 선택하려는 경우에는 여러 데이터 소스를 사용할 수도 있습니다. 쿼리를 변경하여 다시 실행하려면 UI 위젯과 클라이언트 측 스크립트를 사용하세요. 마지막 쿼리의 결과를 위젯 속성에 결합하고 클라이언트 측 스크립트에서 이 결과에 액세스할 수 있습니다.

UI를 개발할 때는 일반적으로 쿼리 데이터 소스를 페이지 또는 복합 위젯의 최상위 패널과 연결합니다. 그러면 패널의 모든 하위 위젯에 해당 데이터 소스가 자동으로 상속되며 위젯 속성을 데이터 소스 레코드의 필드와 연결할 수 있습니다.

관계 데이터 소스는 서로 연결된 레코드에 대한 데이터를 표시하는 데 사용할 수 있습니다. 관계 데이터 소스는 특정 관계 종단에 대해 쿼리 데이터 소스나 다른 관계 데이터 소스를 기초로 만듭니다. 관계 데이터 소스는 상위 데이터 소스의 현재 선택된 레코드와 연결된 관계 종단 쪽 레코드를 표시합니다.

관계 데이터 소스는 일반적으로 마스터 - 세부정보 뷰를 구현할 때 사용합니다. 예를 들어 고객 주문과 관련 품목을 표시하는 UI를 만들 수 있습니다. 이 경우 주문품목이라는 두 개의 모델을 사용하고 두 모델 사이에 일대다 관계를 만듭니다. UI 편집기에서 관계 데이터 소스를 사용하는 방법에 대한 자세한 내용은 UI에 데이터 결합을 참조하세요.

생성 모드 데이터 소스는 상위 쿼리 또는 관계 데이터 소스에 항목을 만듭니다.

데이터 소스 수명 주기

데이터 소스는 다음 네 가지 중 하나의 상태로 존재합니다.

  1. 언로드됨
  2. 언로드됨 + 로드 중
  3. 로드됨
  4. 로드됨 + 로드 중

언로드된 데이터 소스에는 데이터가 없습니다. 데이터 소스의 항목은 빈 배열이고 현재 선택된 항목은 null입니다. 로드 중인 데이터 소스는 데이터를 가져오는 과정에 있습니다. 로드된 데이터 소스에는 데이터가 있지만 이 데이터가 비어 있을 수도 있습니다.

데이터 소스가 로드 중 상태 가운데 하나가 되기 위해서는 로드가 트리거되어야 합니다. 로드는 다음과 같은 방식으로 트리거될 수 있습니다.

  1. 기본적으로 데이터 소스를 사용하는 위젯이 페이지에 연결되면 로드가 트리거됩니다. 대개 사용자가 위젯의 상위 페이지를 열면 위젯이 연결됩니다.
  2. 기본적으로 데이터 소스의 데이터 속성에 대한 결합이 있는 위젯이 연결되면 로드가 트리거됩니다. 예를 들어 고객 모델의 필드에 결합된 주문 페이지에 라벨 위젯이 있다면 주문 페이지가 표시될 때 고객 데이터 소스가 로드됩니다.
  3. 데이터 소스에 대해 load, loadPage, prevPage 또는 nextPage 메소드를 호출하는 클라이언트 스크립트에 의해 로드가 트리거됩니다.

쿼리 데이터 소스의 경우 데이터 자동 로드를 사용 중지하여 위에 나열된 처음 두 가지 방식의 로드가 트리거되지 않도록 할 수 있습니다. 데이터 소스를 언로드하려면 데이터 소스에 대해 unload 메소드를 호출합니다.

쿼리 데이터 소스에는 데이터 소스가 로드됨 상태로 전환될 때 트리거되는 onLoad 이벤트가 있습니다. onLoad 이벤트는 데이터 소스에 데이터가 로드된 후에 작업을 수행하는 스크립트를 실행하려는 경우에 유용합니다. 예를 들어 onLoad 코드 편집기에 다음 스크립트를 입력하여 데이터를 사용할 수 있게 될 때 위젯이 표시되도록 할 수 있습니다.

var widget = app.pages.MyPage.descendants.MyWidget;
widget.visible = true;

쿼리 데이터 소스

모델을 만들면 쿼리 데이터 소스가 자동으로 만들어집니다. 쿼리 데이터 소스를 맞춤설정하고 모델에 대해 더 많은 쿼리 데이터 소스를 만들 수 있습니다.

쿼리 데이터 소스를 수정하거나 만들려면 다음 안내를 따르세요.

  1. 탐색창에서 모델을 클릭하고 데이터 소스 탭으로 이동합니다.
  2. 데이터 소스를 수정하려면 데이터 소스를 클릭합니다. 데이터 소스를 만들려면 데이터 소스 추가를 클릭합니다.
  3. 데이터 소스를 구성합니다. 변경사항은 자동으로 저장됩니다.

데이터 소스의 구성 옵션은 다음과 같습니다.

쿼리 서버 스크립트

데이터 소스는 기본적으로 모델의 모든 레코드를 로드합니다. 필터 등의 커스텀 서버 측 로직을 지정할 때 쿼리 스크립트 속성을 사용하여 기본 쿼리 동작을 재정의할 수 있습니다. 계산된 모델의 경우 쿼리 스크립트를 사용하여 데이터 소스의 쿼리 동작을 완전히 정의하고 데이터 소스에 레코드를 만들 수 있습니다.

쿼리 스크립트 기능 및 요구사항

  • 쿼리 스크립트 편집기에서 서버 스크립트 함수를 호출할 수 있습니다. 이 기능은 쿼리 스크립트가 길 때 유용합니다.
  • 커스텀 매개변수를 사용하여 클라이언트에서 쿼리 스크립트로 매개변수를 전달할 수 있습니다.
  • 쿼리 스크립트는 데이터 소스 모델에 속한 레코드의 배열을 반환해야 합니다.

필터 예시

예를 들어 기본 직원 데이터 소스 쿼리는 직원 모델의 모든 레코드를 반환합니다. 연령이 짝수이면서 쿼리에 지정된 최소 연령보다 많은 직원만 반환되도록 하려는 경우 데이터 소스에 이 쿼리를 적용하려면 쿼리 스크립트 코드 편집기에 다음 코드를 입력하세요.

var employeeResult = [];
// Modify passed query to also filter by minimum age.
query.filters.Age._greaterThan = 20;
var employeesAboveMinimumAge = query.run();
for (var i = 0; i < employeesAboveMinimumAge.length; i++) {
  if (employeesAboveMinimumAge[i].age % 2 == 0) {
    employeeResult.push(employeesAboveMinimumAge[i]);
  }
}
return employeeResult;

계산된 레코드 생성 예시

계산된 모델을 사용하면 스크립트 결과를 UI에서 사용할 수 있도록 레코드로 나타낼 수 있습니다. 예를 들어 직원 모델을 쿼리하여 각 위치의 직원 수에 대한 레코드를 생성하는 계산된 모델을 만들 수 있습니다. 실제 EmployeesByLocation 레코드가 데이터베이스에 있는 것이 아니기 때문에 쿼리 스크립트에서 newRecord()를 호출하여 레코드를 만들어야 합니다. 다음 스크립트는 각 위치의 직원 수를 계산하고 계산된 모델에 각 위치에 대한 레코드를 만듭니다.

var calculatedModelRecords = [];
var recordsByLocation = {};
var allEmployees = app.models.Employees.newQuery().run();
for (var i = 0; i < allEmployees.length; i++) {
  var employee = allEmployees[i];
  if (!recordsByLocation[employee.location]) {
    var calculatedModelRecord = app.models.EmployeesByLocation.newRecord();
    calculatedModelRecord.numberOfEmployees = 1;
    calculatedModelRecord.location = employee.location;
    calculatedModelRecords.push(calculatedModelRecord);
    recordsByLocation[employee.location] = calculatedModelRecord;
  } else {
    recordsByLocation[employee.location].numberOfEmployees++;
  }
}
return calculatedModelRecords;

커스텀 매개변수

쿼리 스크립트에서는 데이터베이스에서 제공되지 않는 매개변수도 사용할 수 있습니다. 예를 들어 웹 서비스에서 제공되는 현재의 회사 주가를 기준으로 데이터를 필터링할 수 있습니다. 커스텀 매개변수를 사용하여 클라이언트에서 서버의 쿼리 스크립트로 매개변수를 전달할 수 있습니다.

매개변수를 추가하려면 다음 안내를 따르세요.

  1. 데이터 소스 탭에서 매개변수 추가를 클릭합니다.
  2. 매개변수 유형을 선택합니다.
  3. 매개변수의 이름을 입력합니다.

데이터 소스 쿼리의 parameters 속성 아래에서 매개변수에 액세스하고 결합할 수 있습니다. 예를 들어 다음과 같은 결합을 통해 텍스트 필드 위젯의 값 속성을 쿼리 매개변수에 결합할 수 있습니다.

textField.value <-> datasource.query.parameters.MyParam

쿼리 스크립트에서는 이 매개변수를 쿼리 매개변수로 액세스할 수 있습니다. 이 방법을 앞의 예시에 적용하려면 쿼리 스크립트에 다음을 추가하면 됩니다. 이와 같이 추가하면 RestrictAge라는 부울 커스텀 매개변수가 true인 경우에만 최소 연령 필터가 추가됩니다.

// Modify query to also filter by minimum age if client enables the option.
if (query.parameters.RestrictAge) {
  query.filters.Age._greaterThan = 20;
}
var employees = query.run();

쿼리 빌더

Cloud SQL 데이터 소스에 쿼리 빌더를 사용할 수 있습니다. 쿼리 빌더는 MySQL WHERE 절을 단순화한 것으로서, 관련 모델에 대한 필터링을 지원하며 null에 대한 쿼리를 간편하게 해줍니다. 앱 사용자가 제출한 정보를 기반으로 복잡한 쿼리를 실행하려면 쿼리 빌더를 사용하세요.

예를 들어 사용자가 HR 데이터베이스에서 다양한 퇴직 연금의 자격 요건을 갖춘 직원을 검색할 수 있는 앱을 만들 수 있습니다. 쿼리 빌더는 앱에서 데이터를 찾는 데 필요한 논리 표현식을 만드는 데 유용합니다. 이 방법을 사용하면 사용자 입력을 해석해서 Cloud SQL 데이터베이스 검색에 적용하기 위한 커스텀 스크립트를 작성할 필요가 없습니다. 쿼리 빌더는 코드 완성 기능(Ctrl+Space를 누름)도 지원합니다.

사용자 입력 매개변수가 있는 쿼리를 구현하려면 다음 안내를 따르세요.

  1. 쿼리 빌더에서 쿼리 표현식을 작성하고 평소대로 사용자 입력 매개변수를 만듭니다.
  2. 사용자 입력 매개변수에 위젯 속성을 결합합니다.

쿼리 작성

쿼리 빌더는 다음 규칙에 따라 쿼리를 처리합니다.

  • 쿼리 표현식은 왼쪽에서 오른쪽으로 평가됩니다.
  • 사용자가 입력하는 매개변수는 앞에 콜론(:)이 붙어 모델 필드와 구별됩니다.
  • and 연산자는 or 연산자보다 우선합니다.
  • 괄호 안의 서브 쿼리 표현식은 andor 연산자보다 우선합니다.
  • '!' 연산자는 표현식의 부울 값을 부정합니다.
  • 리프 연산자에 '?' 한정자가 있으면 표현식 오른쪽의 null 값이 true로 간주됩니다. '?' 한정자를 사용하는 표현식은 부정할 수 없습니다.

앞에 나온 HR 데이터베이스를 예로 들면 앱은 지정된 연령대에 있거나 지정된 날짜 후에 근무를 시작한 직원을 반환해야 합니다. 해당 쿼리는 다음과 같습니다.

(Age >= :AgeMin and Age < :AgeMax) or StartDate > :StartDate
  • Age—앱의 모델에 있는 필드입니다. 이 필드에는 각 직원의 연령이 포함되어 있습니다. 앱 요청에 따라 사용자는 최소 연령(:AgeMin)과 최대 연령(:AgeMax)을 입력해야 합니다. 그러면 쿼리에서 해당 범위에 속하는 직원이 반환됩니다.
  • 콜론(:)—콜론은 앱의 UI를 통해 값을 받는 매개변수를 식별합니다.
  • 괄호—서브 쿼리를 식별합니다. App Maker는 이 서브 쿼리를 평가한 후에 :StartDate를 평가합니다.
  • and—앱이 두 조건을 모두 충족하는 직원을 반환하도록 하는 연산자입니다.
  • or—앱이 두 조건 중 하나를 충족하는 직원을 반환하도록 하는 연산자입니다.
  • StartDate—직원이 근무를 시작한 날짜가 포함되어 있는 필드입니다. 사용자가 :StartDate를 입력하면 앱이 해당 날짜 후에 근무를 시작한 직원을 반환합니다.

UI에 쿼리 표현식 결합

표현식에 콜론으로 시작하는 매개변수를 추가하면 쿼리 빌더가 자동으로 이를 인식하고 쿼리 빌더 아래 영역에 쿼리 매개변수를 만듭니다. 이 매개변수는 데이터 결합 UI에도 표시되므로 이 UI를 사용하여 앱의 위젯에 매개변수를 결합할 수 있습니다.

HR 데이터베이스 예시를 사용할 경우 다음에 수행할 단계는 아래와 같습니다.

  1. 위젯()을 열고 페이지에 텍스트 상자() 두 개를 추가합니다.
  2. 텍스트 상자의 value 속성을 다음 항목에 결합합니다.
    • @datasource.query.parameters.AgeMin
    • @datasource.query.parameters.AgeMax
  3. 페이지에 날짜 상자 위젯()을 추가합니다.
  4. 날짜 상자 위젯의 value 속성을 다음 항목에 결합합니다.
    • @datasource.query.parameters.StartDate
  5. 입력 위젯에 대해 onValueChange 이벤트를 데이터 소스 다시 로드로 변경합니다.

추가 쿼리 빌더 예시

쿼리 반환
Age >= :AgeMin and Age <= :AgeMax and Active = :IsActive 최소 연령과 최대 연령 사이에 있는 모든 근무 중인 직원
(Status = :Pending or Status = :Active) and Name startsWith :NamePrefix 대기 중 또는 근무 상태이며 이름이 NamePrefix로 시작하는 모든 직원
!(Status = :Pending or Status = :Active) 대기 중 또는 근무 상태가 아닌 모든 직원
Age >=? :AgeMin

쿼리 매개변수 AgeMin이 null이면 모든 직원이 반환됩니다. 그렇지 않으면 최소 연령보다 연령이 많은 직원이 반환됩니다.

이 연산자는 UI에서 쿼리 매개변수 AgeMin을 결합할 때 유용할 수 있습니다. 예를 들어 AgeMin 쿼리 매개변수가 텍스트 필드에 결합되면 처음에는 모든 직원이 반환됩니다. 사용자가 AgeMin의 값을 입력하면 레코드가 필터링됩니다. 사용자가 텍스트 필드를 지우면 다시 모든 직원이 표시됩니다.

쿼리에 >=? 대신 >= 연산자가 사용되면 처음에 또는 사용자가 텍스트 필드를 지울 때 직원이 반환되지 않습니다.

Role notIn :Engineering or :Marketing

Engineering 또는 Marketing 역할에 할당되지 않은 모든 직원

innotIn은 사용자가 정의된 여러 매개변수를 둘 이상 선택할 수 있는 다중 선택 위젯 과 함께 사용하면 유용합니다.

Computer startsWith :Chromebook and notContains :Pixel 구체적인 모델에 상관없이 Chromebook을 사용하는 직원 중 Chromebook Pixel 사용 직원을 제외한 모든 직원

계산된 SQL에 대한 SQL 쿼리

자세한 내용은 계산된 SQL 모델을 참조하세요.

기타 쿼리 데이터 소스 속성

페이지 크기

페이지 크기 설정은 단일 쿼리에 대해 데이터 소스가 반환하는 레코드의 수를 제어합니다. 이 설정을 사용하면 UI에 반환되는 결과 수를 제어하고 성능을 높일 수 있습니다. 서버에 10,000개의 레코드가 있는 경우 UI에서 모든 레코드를 한 번에 로드하려고 하면 속도가 느려지고 작업을 관리하기 어렵게 됩니다. 대신 페이지 크기를 설정하고 데이터 소스에 대해 nextPage 메서드를 호출하는 다음 버튼을 만들 수 있습니다.

모든 레코드를 표시하려면 페이지 크기를 0으로 설정하세요.

페이지 크기는 데이터 소스의 속성이므로 다음을 수행할 수 있습니다.

  • 이 속성에 위젯 속성 결합
  • 클라이언트 측 스크립트에서 페이지 크기 액세스 및 수정

예를 들어 슬라이더 위젯의 value 속성을 데이터 소스의 pageSize 속성에 결합하면 표시할 레코드 수를 사용자가 제어할 수 있게 됩니다.

정렬

정렬 가능한 필드를 기준으로 레코드를 오름차순 또는 내림차순으로 정렬할 수 있습니다. 둘 이상의 필드를 기준으로 정렬하려면 클라이언트 쿼리 스크립트를 사용하세요.

수동 저장 모드

App Maker에서 데이터 소스 항목의 값이 변경되면 기본적으로 변경사항이 즉시 서버에 자동 저장됩니다. 예를 들어 사용자가 텍스트 필드 위젯에서 값을 변경하면 새로운 값이 결합된 레코드 필드에 자동으로 저장됩니다.

이 자동 저장 동작을 사용 중지하려면 데이터 소스를 수동 저장 모드로 설정하면 됩니다. 모델 편집기의 데이터 소스 탭에서 수동 저장 모드 체크박스를 선택하세요.

수동 저장 모드에서는 변경사항을 UI 또는 스크립트에 명시적으로 저장해야 합니다. UI에서 입력 필드와 양식은 일반적인 웹 양식과 마찬가지로 동작하며 사용자 작업을 필요로 합니다. 사용자는 onClick 작업이 데이터 소스 변경사항 저장저장 버튼을 클릭해야 합니다.

클라이언트 측 스크립트에서는 변경 관리에 다음 메소드를 사용할 수 있습니다.

  • saveChanges—현재 변경사항을 서버에 저장합니다.
  • clearChanges—마지막으로 saveChanges를 호출한 이후에 변경된 사항을 모두 취소합니다.
  • hasChanges—데이터 소스에 저장되지 않은 변경사항이 있으면 true를 반환합니다.

관계 속성을 통해 액세스한 레코드를 포함하여 데이터 소스의 itemitems 속성을 통해 액세스한 레코드가 변경되면 변경사항이 클라이언트에 로컬로 보관되며 이를 저장하거나 롤백할 수 있습니다.

데이터 자동 로드

기본적으로 데이터 소스는 위젯이 데이터 소스의 데이터에 결합될 때마다 자동으로 데이터를 로드합니다. 데이터 자동 로드 체크박스의 선택을 취소하면 load, loadPage, nextPage, prevPage 메소드를 호출할 때만 데이터 소스에 데이터가 로드됩니다.

데이터를 로드하기 전에 사용자가 쿼리 필터의 값을 제공하도록 하려면 데이터 로드를 지연시키십시오.

OnLoad 작업

데이터 소스가 로드될 때마다 클라이언트 측 자바스크립트를 실행하려면 코드 상자에 스크립트를 입력합니다. onLoad 작업은 서버에서 클라이언트로 쿼리 결과가 반환될 때마다 트리거됩니다. 데이터 소스 수명 주기 섹션에서 로드에 대해 자세히 알아보세요.

항목 변경 시 작업

현재 항목이 변경될 때마다 클라이언트 측 자바스크립트를 실행하려면 코드 상자에 스크립트를 입력합니다.

현재 항목은 다음과 같은 이유로 변경될 수 있습니다.

  • 데이터 소스가 데이터를 다시 로드한 결과 현재 항목이 반환된 데이터에 없는 경우
  • 클라이언트 측 스크립트가 데이터 소스에 대해 next 또는 prev 메소드를 호출하는 경우
  • 클라이언트 측 스크립트 또는 결합을 통해 데이터 소스의 item 속성에 값이 할당되는 경우
  • 클라이언트 측 스크립트가 데이터 소스에 대해 selectIndex 또는 selectKey 메소드를 호출하는 경우
  • 일부 위젯이 데이터 소스의 현재 항목을 자동으로 변경하는 경우. 예를 들어 목록 위젯은 사용자가 행을 클릭할 때마다 데이터 소스의 현재 항목을 변경합니다.

프리페치

프리페치는 클라이언트 스크립트나 UI에서 연결된 레코드를 사용할 때 관계 종단에서 해당 레코드를 효율적으로 로드하기 위해 사용됩니다. 다른 관계 종단의 연결된 레코드는 자동으로 로드되지 않으므로 클라이언트 스크립트에서 관계 데이터 소스의 레코드를 사용하는 경우에는 서버에서 연결된 레코드를 명시적으로 로드해야 합니다. 연결된 레코드를 로드하는 한 가지 방법은 App Maker가 쿼리 결과를 로드할 때 연결된 레코드도 로드하도록 프리페치를 사용 설정하는 것입니다.

프리페치는 데이터 소스에 많은 레코드가 있고 모든 레코드에 대해 연결된 레코드를 로드해야 할 때 UI 성능을 향상시킬 수 있습니다. 예를 들어 관리자팀 구성원이라는 두 관계 종단을 통해 모델 자체와 관리자 관계를 맺고 있는 직원 모델이 있을 수 있습니다. 이 경우 UI에는 쿼리 데이터 소스에 따라 직원 레코드의 목록이 표시되며 각 직원의 관리자도 표시됩니다.

프리페치를 사용하지 않을 경우 App Maker는 데이터 소스의 각 직원 레코드에 대해 연결된 관리자 레코드를 요청합니다. 이 프로세스는 서버에 대해 많은 요청을 실행해야 하므로 속도가 느릴 수 있습니다. 프리페치를 사용 설정하면 App Maker가 쿼리 결과와 함께 연결된 레코드를 로드하므로 초기 로드 후 UI의 작업 속도가 빨라집니다.

클라이언트 스크립트로 연결 수정에서 연결된 레코드를 클라이언트에 로드하는 다른 방법에 대해 알아보세요.

클라이언트에서 데이터 소스 쿼리 구체화

쿼리 데이터 소스에는 클라이언트 스크립트를 사용하여 쿼리를 수정하는 데 사용할 수 있는 속성 및 메소드가 포함되어 있습니다. 쿼리 객체는 데이터 소스가 로드될 때 서버로 전송되는 쿼리를 나타냅니다. 여기에는 쿼리 조건과 반환할 결과 페이지를 지정하는 속성이 포함됩니다.

쿼리 데이터 소스에 대해 로드를 트리거하면 다음 작업이 수행됩니다.

  1. 쿼리 데이터 소스가 현재 쿼리를 서버로 보냅니다.
  2. 쿼리 데이터 소스가 쿼리 결과로 데이터를 업데이트합니다.
  3. 클라이언트의 레코드도 쿼리 결과로 업데이트됩니다.

쿼리 데이터 소스를 로드하면 쿼리 결과의 레코드가 변경되지 않았더라도 클라이언트에서 레코드 값이 변경될 수 있습니다. 서버 측 스크립트나 다른 클라이언트가 레코드를 변경한 경우 이러한 현상이 발생합니다.

필터

쿼리 객체의 filters 속성에는 모델의 필드에 대한 쿼리 조건이 포함됩니다. 필터는 다음과 같은 구문으로 지정합니다.

datasource.query.filters.field-id.filter-operator = value

각 항목의 의미는 다음과 같습니다.

  • field-id는 필터링에 사용할 수 있는 모델 내 필드입니다.
  • filter-operatorequals 또는 contains 같은 필터 작업입니다. 지원되는 필터 연산자는 필드 유형과 데이터베이스에 따라 다릅니다. 클라이언트 API 쿼리 문서에서 필터 연산자에 대해 자세히 알아보세요.
  • value는 쿼리에서 필드 및 연산자에 사용되는 매개변수입니다. 값 유형은 innotIn 연산자를 제외하고는 항상 필드 유형과 일치해야 합니다. innotIn 연산자의 경우 매개변수 값은 필드 유형의 배열이어야 합니다.

목록 필드의 경우에는 목록에 있는 항목 중 하나 이상이 쿼리 필터를 충족해야 합니다. filters 아래의 속성에 값을 여러 개 할당하면 레코드가 모든 필터와 일치해야 로드됩니다.

Cloud SQL 모델 데이터 소스의 쿼리 객체에는 관계 필터 속성도 포함됩니다. 이러한 속성을 사용하면 연결된 레코드, 필드 또는 키를 기준으로 레코드를 필터링할 수 있습니다. 필터링은 일대일 및 다대일 관계에만 지원됩니다.

클라이언트 쿼리 예시

  • 단일 필터—다음 코드는 이름이 'John Smith'인 레코드를 반환하는 쿼리 필터를 위젯 데이터 소스에 추가합니다.

    var datasource = widget.datasource;
    datasource.query.filters.Name._equals = 'John Smith';

  • 다중 필터—다음 코드는 이름이 'John'으로 시작하고 연령이 18세를 초과하는 레코드를 찾는 쿼리 필터를 추가합니다.

    var datasource = widget.datasource;
    datasource.query.filters.Name._startsWith = 'John';
    datasource.query.filters.Age._greaterThan = 18;

  • 목록 필드 일치—다음 쿼리는 record.Emails = ['smith.j@example.com', 'john@example.com'] 레코드를 로드합니다. Emails 목록 필드의 항목 중 하나가 john@로 시작하기 때문입니다.

    datasource.query.filters.Emails._startsWith = 'john@';

  • in 연산자— 다음 코드는 쿼리 필터에 in 연산자를 사용하여 favoriteColor 필드의 값이 blue 또는 green인 레코드를 로드합니다.

    var datasource = widget.datasource;
    var colors = ['blue', 'green'];
    datasource.query.filters.FavoriteColor._in = colors;

  • 관계 필드 필터직원 모델이 해당 모델 자체와 일대다 관계로 관리자와 관리자의 팀 구성원을 나타내는 경우 다음을 수행할 수 있습니다.

    • manager1에 할당된 팀 구성원의 레코드를 로드합니다.

      var datasource = widget.datasource;
      datasource.query.filters.Manager._equals = 'manager1';

    • 관리자의 레코드 키를 기준으로 필터링합니다.

      datasource.query.filters.Manager._key._in = ['manager1RecordKey', 'manager2RecordKey'];

    • 관리자 이름을 기준으로 필터링합니다.

      datasource.query.filters.Manager.Manager.Name._equals = 'John Doe';

    관계 필터 속성 값을 null로 설정하면 다른 필드 필터와 마찬가지로 필터가 적용되지 않습니다.

정렬

클라이언트 스크립트에서 데이터 소스에 구성된 정렬을 재정의할 수 있습니다. 데이터 소스 모델에 있는 하나 이상의 정렬 가능한 필드를 기준으로 데이터를 정렬합니다. Cloud SQL 모델 데이터 소스의 경우 관계 종단이 일대일 또는 다대일 관계에 있으면 관련 레코드의 필드를 기준으로 정렬할 수도 있습니다. 예를 들어 다대일 도시- 관계가 있다면 주를 기준으로 도시를 정렬할 수 있습니다.

쿼리 정렬 속성에 대해 자세히 알아보세요.

페이지 색인

페이지 색인 속성은 로드할 페이지 번호를 지정합니다. 기본적으로는 쿼리 결과의 1페이지가 로드됩니다. 이 속성을 임의의 양수로 변경할 수 있습니다. 다음에 쿼리 데이터 소스가 로드될 때는 해당 페이지 번호에 대한 레코드가 로드됩니다.

페이지 크기

페이지 크기 속성은 쿼리 결과에 대해 서버에서 반환할 레코드의 수를 지정합니다.

관계 데이터 소스

관계 데이터 소스를 사용하면 관계 종단의 데이터 소스에서 레코드의 연결된 레코드를 쉽게 가져와 표시할 수 있습니다.

속성 편집기에서 위젯의 관계 데이터 소스를 설정할 수 있습니다. 데이터 소스 대화상자에는 상위 모델에 구성된 각 관계에 대한 관계 데이터 소스가 표시됩니다. UI에서 관계 데이터 소스를 선택하는 방법에 대한 자세한 내용은 UI에 데이터 결합을 참조하세요. 데이터 모델 연결 가이드의 예시도 사용해 보세요.

연결된 레코드 로드

관계 데이터 소스가 함께 구성된 위젯이 로드될 때는 현재 레코드와 연결된 레코드가 자동으로 로드됩니다. 관계 데이터 소스에 대한 로드를 트리거하면 연결된 레코드도 로드됩니다.

앱에서 데이터가 사용되기 전에 연결된 레코드가 로드되도록 하려는 경우가 종종 있습니다. 레코드의 연결된 레코드가 로드될 때 스크립트를 실행하거나 알림을 받으려면 위젯에 onDataLoaded 이벤트를 사용하세요. 앱에서 연결된 레코드를 사용하는 일반적인 방법은 다음과 같습니다.

  1. 관계 데이터 소스를 사용하여 관련 데이터가 로드되도록 하는 숨겨진 패널을 만듭니다.
  2. 숨겨진 패널에서 onDataLoaded 이벤트를 사용하여 관련 데이터를 사용하는 몇 가지 로직을 수행합니다.

연결된 레코드를 서버에서 다시 로드하려면 관계 데이터 소스에 대해 load를 호출합니다. 연결된 레코드가 클라이언트 측 스크립트나 결합을 통해서가 아니라 서버 스크립트를 통해 변경될 때 해당 레코드를 다시 로드할 수 있습니다.

현재 레코드에 대해 _reload 메소드를 사용하여 연결된 레코드를 다시 로드할 수도 있습니다.

생성 모드 데이터 소스

데이터베이스에 자동으로 저장되지 않는 상위 쿼리 데이터 소스 또는 관계 데이터 소스에 항목을 생성하려면 생성 모드 데이터 소스를 사용합니다. 그러면 사용자가 레코드를 저장하기 위한 작업을 트리거할 때까지 클라이언트 측의 초안 레코드에 데이터가 대신 저장됩니다. 초안 레코드는 새 레코드를 위한 템플릿을 제공할 수도 있습니다. 생성 모드 데이터 소스는 상위 데이터 소스와 동일한 모델에 속합니다.

생성 모드 데이터 소스를 사용하면 다음을 수행할 수 있습니다.

  • 생성 모드 데이터 소스의 필드에 UI 요소를 결합합니다. 이러한 필드는 초안 레코드에 값을 채우는 데 사용됩니다.
  • 데이터 소스 레코드의 기본 필드 값을 설정합니다. 이 방법을 사용하면 필수 필드에 항상 값이 있게 됩니다. 생성 모드 데이터 소스가 데이터베이스에 레코드를 저장하면 필드 값이 기본값으로 재설정됩니다. 기본값은 스크립트나 UI로 설정할 수 있습니다.

앱 UI와 클라이언트 스크립트로 생성 모드 데이터 소스에 대한 작업을 수행할 수 있습니다.

양식을 사용하여 레코드 생성

입력 유형 양식의 값은 기본적으로 생성 모드 데이터 소스의 필드에 결합됩니다. 사용자가 양식에 내용을 입력하면 App Maker는 해당 값을 초안 레코드에 저장합니다. 생성 모드 데이터 소스는 @datasource.parent-datasource.modes.create이며 UI는 이를 parent-datasource(생성)로 보고합니다. 양식의 각 필드는 초안 레코드의 필드에 해당하는 datasource.item.field에 결합됩니다.

사용자가 양식에 내용을 입력한 후 제출을 클릭하기 전까지는 해당 레코드가 클라이언트에 저장됩니다. 제출 버튼의 onClick 작업은 항목을 만들어 상위 데이터 소스에 추가하는 datasource.item.createItem()입니다. 지우기 버튼의 onClick 작업은 생성 데이터 소스의 레코드를 지우는 widget.datasource.clearChanges()입니다.

데이터 위젯: 양식데이터 작업 가이드에서 자세한 내용을 알아보세요.

스크립트를 사용하여 레코드 생성

클라이언트 스크립트는 생성 모드 데이터 소스에 레코드를 추가할 수 있습니다. 다음과 같은 경우에 이 방식으로 레코드를 추가하세요.

  • 사용자 이름 및 레코드 생성 날짜와 같은 세션 데이터를 자동으로 추가하려는 경우
  • 레코드를 만들기 전에 이름과 성을 연결하는 등 양식의 데이터가 데이터 소스의 필드와 일치하게 처리하려는 경우

예를 들어 DateAdded 필드가 있는 People 모델이 있는 경우 생성 모드 데이터 소스에서 레코드의 DateAdded 속성을 new Date();로 설정하면 이 데이터 소스를 통해 생성되는 레코드의 시작 날짜는 사용자 시간대의 현재 날짜가 됩니다.

var createDatasource = app.datasources.people.modes.create;
var draft = createDatasource.item;
draft.DateAdded = new Date();
createDatasource.createItem(function(createdRecord) {
 alert('Created record on ' + createdRecord.DateAdded)
});

CreateDataSource에 대해 자세히 알아보세요.