[WebSquare5/SP4] ep02. API - $p.data

WebSquare5에서 제공하는 API중 $p 태그는 주로 DataCollection을 전체적으로 제어하는 용도로, 스크립트 구문에서 주로 쓰인다.

 

DataCollection이 뭐냐고? VO in Spring MVC Model 정도로 생각하면 좋을것 같다.

 

다만 DataCollection의 데이터 타입은 Map, List, LinkedList 세가지 타입만 존재한다. 

---

▷ $p.data ◁

$p.data 유틸은 복수의 데이터 객체에서 한번에 데이터 꺼내오기, 데이터 설정하기, 혹은 동적 데이터 객제 생성하기 등의 기능을 제공한다.

---

☞ $p.data.create()

create( dataCollectionString , dataCollectionObject )

 

dataList 및 dataMap을 동적으로 생성. 아래 예제와 같이 두 가지 방법(XML 및 JSON)으로 생성 가능.

 

Parameter

name	type	required	description
dataCollectionString	String	Y	dataList, dataMap의 XML 문자열.
dataCollectionObject	Object	Y	dataList, dataMap의 JSON 객체

 

Sample1 -  dataList 생성 (XML 문자열)

var dcStr = '<w2:dataList id="dataList1" baseNode="vector" repeatNode="item" valueNode=""> '+ 
                '<w2:columnInfo>'+ 
                    '<w2:column id="OrderID" dataType="text"></w2:column>'+
                    '<w2:column id="CustomerID" dataType="text"></w2:column>'+
                    '<w2:column id="EmployeeID" dataType="text"></w2:column>'+
                    '<w2:column id="OrderDate" dataType="text"></w2:column>'+
                '</w2:columnInfo>'+
            '</w2:dataList>';
$p.data.create(dcStr);

 

Sample2 -  dataMap 생성 (XML 문자열)

var dcStr = '<w2:dataMap baseNode="map" id="dataMap1">' +
               '<w2:keyInfo>' +
                 '<w2:key id="key1" name="name1" dataType="text"></w2:key>' +
                 '<w2:key id="key2" name="name2" dataType="text"></w2:key>' +
               '</w2:keyInfo>' +
             '</w2:dataMap>';
$p.data.create(dcStr); 

 

Sample3 - dataMap 생성 (JSON 객체)

var option = {
     "id":"dataMap1",
     "type":"dataMap",
     "option":{
         "baseNode":"map"
     },
     "keyInfo":[
         {
             "id":"column1",
             "name":"column1",
             "dataType":"text"
         },{
             "id":"column2",
             "name":"column2",
             "dataType":"text"
         }
     ]
 };
$p.data.create( option );

---

☞ $p.data.get()

get( type , dcOptions , returnOptions )

 

조건에 의해 다건의 dataList와 dataMap의 객체를 꺼내온다.
return type으로 XML, ARRAY, JSON이 있다.

 

Parameter

name	type	required	description
type	String	Y	반환 타입명. JSON, XML, ARRAY 가 있다.
dcOptions	Array	Y	각 DataCollection(DataMap/DataList) ID 또는 검색 조건을 가진 JSON 객체을 담고 있는 Array.
returnOptions	JSON	N	return 객체에 대한 옵션이 담긴 JSON 객체.

 

Return

type	description
JSON || XML || Array	type에 따른 dataCollection의 데이터 객체.

전제조건 - dataCollection의 모양이 아래와 같을 경우

<w2:dataCollection>
    <w2:dataMap id="dataMap1" style="" valueAttribute="">
        <w2:keyInfo>
            <w2:key id="name" name="이름" dataType="text"/>
            <w2:key id="addr" name="주소" dataType="text"/>
        </w2:keyInfo>
    </w2:dataMap>
</w2:dataCollection>

 

Sample1 - 별도의 조건이 없이 DataCollection의 ID만 줄 경우

$p.data.get("JSON",["dataLMap1"]);  //단건
$p.data.get("JSON",["dataLMap1","dataList1"]);  //다건

//return Data 예시 - 단건 ) { "dataMap1": {"name":"WebSquare","addr":"서울시"} }

 

Sample2 - DataCollection의 조건이 있는경우 ( 조건으로는 key , id가 있다 )

$p.data.get("JSON",[{ key : "dl", id : "dataLMap1" }]);

//return 예시) {"dl" :  {"name":"WebSquare" , "addr":"서울시"} }

 

Sample3 - 혼용해서 쓴 경우

$p.data.get("JSON",["dataMap1",{ key : "dl", id : "dataLMap1" }]);

 

Sample4 - 꺼내 올 DataCollection의 객체가 1개이고 singleMode(최상위 객체 또는 XML Node를 제거)를 적용하고자 할 때 returnOptions를 이용한다.

$p.data.get("JSON",["dataLMap1"],{"singleMode":true});

//return Data 예시 ) {"name":"WebSquare" , "addr":"서울시"}

---

☞ $p.data.getAllDataCollection()

getAllDataCollection( type )

 

한 화면 내에 있는 모든 DataCollection 정보를 반환. IFrame이나 Popup과 같은 다른 영역에 있는 DataCollection은 제외한다.

 

Parameter

name	type	required	description
type	string	N	반환할 DataCollection 정보 타입을 지정. (ID 혹은 객체 자체)

 

Return

type	description
Array	DataCollection의 ID를 담은 배열. type이 "object"인 경우 DataCollection 객체 자체를 담은 배열.

 

Sample

var ret = $p.data.getAllDataCollection(); // ret == ["dataList1", "dataList2"];
var ret = $p.data.getAllDataCollection("object"); // ret == [dataList1, dataList2];

---

☞ $p.data.getBroadcast()

getBroadcast( )

 

DataCollection의 broadcast 상태를 가져오는 API

 

Return

type	description
boolean	broadcast 상태 flag값

---

☞ $p.data.getInfo()

getInfo( idArray )

 

DataCollection의 상세 정보(xml에서 입력한 attribute 값)를 조회하는 함수

 

Parameter

name	type	required	description
idArray	Array	N	각 DataCollection(DataMap/DataList) ID를 담고 있는 Array. 값을 지정하지 않을 경우 모든 dataCollection이 대상이 된다.

 

Return

type	description
JSON	각 dataCollection의 하위 attribute값을 json형태로 표현한 json객체

 

Sample

$p.data.getInfo(); // 모든 dataCollection의 상세정보 조회
$p.data.getInfo(["dataList1","dataMap1"]); // dataList1, dataMap1에 대한 상세정보 조회

---

☞ $p.data.getInfo()

getOption( propertyName )

 

dataCollection객체의 속성값을 꺼내온다.

 

Parameter

name	type	required	description
propertyName	String	Y	DataCollection의 속성.

 

Return

type	description
String	dataCollection 속성의 value를 반환한다.

 

Sample

//dataCollection의 모양이 아래와 같을 경우
<w2:dataCollection>
    <w2:dataMap id="dataMap1" style="" valueAttribute="value">
        <w2:keyInfo>
            <w2:key id="name" name="이름" dataType="text"/>
            <w2:key id="addr" name="주소" dataType="text"/>
        </w2:keyInfo>
    </w2:dataMap>
</w2:dataCollection>

$p.data.dataList1.getOption( "valueAttribute" );
//return 예시- "value"

---

☞ $p.data.remove()

remove( dataCollectionID )

 

dataList, dataMap, linkedDataList를 삭제하는 함수. dataList가 remove API를 통해 삭제되면 해당 dataList를 bind하고 있는 linkedDataList도 함께 삭제된다.

 

Parameter

name	type	required	description
dataCollectionID	String	Y	dataCollection의 ID.

 

Sample

$p.data.remove("dataMap1");

---

☞ $p.data.set()

set( dataType , dataObject , idArray )

 

생성 되어 있는 여러개의 dataList와 dataMap의 값을 한번에 설정한다.
linkedDataList는 미지원한다. ( linkedDataList는 bind로 참조하고 있는 dataList에 셋팅해야 한다. )

 

Parameter

name	type	required	description
dataType	String	Y	데이터의 타입으로 XML, ARRAY, JSON이 있다.
dataObject	JSON||XML||ARRAY	Y	setting 할 데이터 객체.
idArray	Array	N	각 DataCollection(DataMap/DataList) ID 또는 셋팅 조건을 가진 JSON 객체을 담고 있는 Array. 값을 지정하지 않을 경우 dataObject에 정의 된 key를 참조하여 데이터가 셋팅 된다.

 

전제조건 - dataCollection의 모양이 아래와 같을 경우

<w2:dataCollection>
    <w2:dataMap id="dataMap1" style="" valueAttribute="">
        <w2:keyInfo>
            <w2:key id="name" name="이름" dataType="text"/>
            <w2:key id="addr" name="주소" dataType="text"/>
        </w2:keyInfo>
    </w2:dataMap>
</w2:dataCollection>

 

Sample1 - JSON Type

var tmpJSON = {"name":"WebSquare","addr":"서울시"};
$p.data.set("JSON" , {"dataMap1": tmpJSON } , ["dataMap1"] );
$p.data.set("JSON" , {"dataMap1" : tmpJSON } );

 

Sample2 - XML Type

var tmpXML = WebSquare.xml.parse( '<map><map id="dataMap1"><name>WebSquare</name><addr>서울시</addr></map></map>' );   //XML 객체 생성
$p.data.set("XML" , tmpXML , ["dataMap1"] );
$p.data.set("XML" , tmpXML );

 

Sample3 - ARRAY Type

var tmpArray = ["WebSquare","제주도"];
$p.data.set("ARRAY" , {"dataMap1":tmpArr} , ["dataMap1"]);
$p.data.set("ARRAY" , {"dataMap1":tmpArr} );

---

☞ $p.data.setBroadcast()

setBroadcast( flag )

 

모든 dataCollection의 broadcast 상태를 설정한다. dataCollection 변경에 따른 화면 갱신을 최소화하기 위해 사용하는 API.
broadcast가 비활성화 (false) 상태일 경우 dataCollection이 변경되어도 연동된 컴포넌트 ui는 갱신되지 않는다.
broadcast가 비활성화 상태에서 활성화 상태로 변경될 경우 dataCollection과 화면이 동기화되는 처리가 저동으로 이루어진다.

 

Parameter

name	type	required	description
flag	boolean	Y	broadcast 설정 플래그. true시 broadcast 활성화와 동시에 dataCollection 갱신, false시 broadcast 비활성화.

 

Sample

//아래의 코드는 insertRow의 속도를 최대한 빠르게 만든 코드이다.
$p.data.setBroadcast(false);
for(var i = 0; i < 10; i++){dataList1.insertRow(i)}; // broadcast 비활성화에 의해 dataList를 변경해도 연동된 컴포넌트 ui는 갱신되지 않는다. 
for(var i = 0; i < 10; i++){dataList2.insertRow(i)};
$p.data.setBroadcast(true); // 최종적으로 dataList1, dataList2와 연동된 컴포넌트 ui가 이 시점에서 1회만 갱신된다.

---

☞ $p.data.setOption()

setOption( propertyName , propertyValue )

 

dataCollection객체의 속성을 설정한다. ( 사용자의 임의 속성 및 ID는 적용 안됨 )

 

Parameter

name	type	required	description
propertyName	String	Y	셋팅 할 속성명.
propertyValue	String	Y	속성에 셋팅 할 값.

 

Sample

//만약 propertyName이 엔진에서 지정 한 속성이 아닐 경우 적용되지 않는다.(id 와 사용자의 임의 속성은 적용 안됨)
$p.data.dataList1.setOption( "valueAttribute" , "value" );

---