Translate

[jqGrid] 단일 필드 검색 설명







실습 jqGrid 버전: CDN 제공하는 v4.6 버전으로 테스트



단일 필드 검색

 - 단일필드 검색은 한번에 한필드에서 (서버로)데이터를 검색하는 방법이며, 이 방법을 사용할 때 사용자가 필드와 조건을 선택하여 검색을 적용할 수 있는 모달 형식을 구성한다.

 - 이 방법은 url을 사용하여 검색데이터를 보내고 사용자정의 및 툴바 검색방법과 다르며, 차이점은 검색된 데이터가 name:value 쌍이 아니다.

 - 이 방법을 사용하려면 Common, Form Edit, Filter Plugin 등의 모듈이 로드되어야 한다.






호출 방법

old API
<script>
... 
jQuery("#grid_id").searchGrid( options );
...
</script>
1004lucifer
new API
<script>
... 
jQuery("#grid_id").jqGrid('searchGrid', options );
...
</script>


 - 일반적으로 메소드를 실행하면 모달 대화상자가 시작되며, 모달 대화상자를 닫기전까지 그리드에 엑세스 할 수 없다.
 - 이 메소드는 검색이 사용가능한경우 navigator(링크) 의 기본 검색메소드이며, navigator의 검색 파라메터는 아래의 방법과 동일하게 설정할 수 있다.

<script>
...
jQuery("#grid_id").jqGrid({
...
   pager : '#gridpager',
...
}).navGrid('#gridpager',{view:true, del:false}, 
{}, //  default settings for edit
{}, //  default settings for add
{},  // delete instead that del:false we need this
{search_options}, // search options
{} /* view parameters*/
);
...
</script>
 - 기본적으로 대화상자는 그리드의 왼쪽 상단에 나타난다.
 - 검색 대화상자의 새옵션 overlay(기본값10)이 추가되며, 이 값을 0으로 하면 overlay가 비활성화 되며 그리드와 상호작용이 가능하다.





옵션

 - 이 메소드는 언어파일의 아래 옵션을 사용하며, search 메소드의 옵션배열을 전달할 수 있다.
$.jgrid = {
...
   search : {
     caption: "Search...",
     Find: "Find",
     Reset: "Reset",
     odata : ['equal', 'not equal', 'less', 'less or equal','greater','greater or equal', 'begins with','does not begin with','is in','is not in','ends with','does not end with','contains','does not contain']
   },
...

1004lucifer
OptionTypeDescriptionDefault
afterShowSearchfunction정의된경우 이 이벤트는 검색 대화상자가 표시된 후 매번 발생한다.null
beforeShowSearchfunction정의된경우 이 이벤트는 검색대화상자가 표시되기전에 매번 발생한다.null
closeAfterSearchbooleantrue 설정 시 사용자가 검색대화상자를 닫은 후 검색이 적용된다.(Find Button 클릭)false
closeAfterResetbooleantrue 설정 시 사용자가 검색대화상자를 닫은 후 검색이 초기화 된다. (Reset button 클릭)false
dragboolean모달을 드래그 가능여부 지정true
jqModalbooleantrue 설정 시 jqModel plugin(있는경우) 을 사용하여 대화상자를 생성하며, true로 설정되고 plugin이 없는경우 내부함수를 사용하여 대화상자를 생성한다.true
resizeboolean모달의 크리조정 활성화/비활성화 여부true
modalbooleantrue 설정 시 검색대화상자가 모달이 된다.false
widthinteger검색대화상자의 width값을 정의450
heightmixed검색대화상자의 height값을 정의auto
topinteger모달 대화상자의 최초 상단 위치.
기본값은 0이며 그리드의 왼쪽 가장위에 위치한다.
jqModql이 true이고 jqModal 플러그인이 있는경우 값이 0이면 윈도우의 왼쪽 가장위를 의미한다.
0
leftinteger모달 대화상자의 최초 왼쪽 위치.
기본값은 0이며 그리드의 왼쪽 가장위에 위치한다.
jqModql이 true이고 jqModal 플러그인이 있는경우 값이 0이면 윈도우의 왼쪽 가장위를 의미한다.
0
captionstring모달의 captionsee lang file
showQuerybooleantrue로 설정 시 사용자가 검색의 조건을 정의할 때 생성되는 query를 보여주며, 고급검색에서 사용가능하다.
검색버튼 근처의 이버튼을 다시 사용할 시 쿼리가 보여지거나 감춰지거나 동적으로 변한다.
false
searchOnEnterbooleanEnter 키를 눌러서 검색할지의 여부를 결정한다.false
Findstringfind 버튼의 textsee lang file
multipleSearchbooleantrue로 설정 시 고급검색이 활성화 된다.false
multipleGroupbooleantrue로 설정 시 복잡한 조건을 정의할 수 있는 고급검색이 활성화 된다.false
odataarraysopt 옵션과 부합하는 교체디는 문자열see lang file
onClosefunction정의된경우 대화상자가 닫힐 때 이벤트가 발생한다.
true 또는 false를 반환할 수 있으며, false를 반환하면 대화상자가 닫히지 않는다.
null
afterRedrawfunction정의된경우 filter가 모습이 바뀔때(redraw) 마다 수행된다.
룰이나 필드를 추가/삭제할때마다 filter는 redraw되며, 검색 파라메터가 파라메터로 전달된다.
null
onSearchfunction정의된경우 검색버튼을 클릭하면 이 이벤트가 실행된다.null
onResetfunction정의된경우 reset버튼이 활성화되면 수행된다.null
closeOnEscapeboolean true설정 시 ESC키를 누르면 검색대화상자가 닫힌다.false
onInitializeSearchfunction이 이벤트는 모달을 만들때 한번만 수행된다.null
recreateFormboolean true로 설정 시 colModel의 새 옵션으로 검색대화상자가 활성화될 때마다 form 이 다시 생성된다.false
showOnLoadboolean이 옵션은 navigator옵션에서만 사용가능하며, true 설정 시 그리드가 초기에 구성될 때 대화상자가 자동으로 나타난다.false
errorcheckboolean searchrules가 정의된경우 error체크를 한다.
입력에 오류가 있으면 필터는 서버에 전송하지 ㅇ낳고 오류메시지를 보여준다.
true
Resetstringclear (reset) Button 의 텍스트see lang file
sFieldstringsopt 설명 참조searchField
sFilterstring고급검색이 가능하며 고급검색 항목 참조filters
sOperstringsopt 설명 참조searchOper
soptarray이 옵션은 일반적인 검색규칙을 설정하며, 설정하지 않으면 모든 사용가능한 옵션이 사용된다.
옵션은 다음과 같다.
['eq','ne','lt','le','gt','ge','bw','bn','in','ni','ew','en','cn','nc','nu','nn']
해당 텍스트는 언어파일에 있으며 다음을 의미한다.
['equal','not equal', 'less', 'less or equal','greater','greater or equal', 'begins with','does not begin with','is in','is not in','ends with','does not end with','contains','does not contain','is null','is not null']
sopt배열의 요소는 순서에 상관이 없다.
sValuestringsopt 설명 참조searchString
overlayinteger이 옵션을 0으로 설정 시 그리드의 오버레이가 비활성화 되며 검색 대화상자가 활성화시에도 그리드와 상호작용이 가능하다.10
layerstring정의된경우 DOM의 유효한 id 이어야하며, 이 옵션이 설정되면 요소의 자식으로 filter가 삽입된다.null
tmplNamesarray['Template1', 'Template2',…] 와 같이 간단한 사용자 입력에 사용되는 템플릿 이름을 정의한다.
템플릿 정의 관련 그리드 데모 참고
null
tmplFiltersarray of objects 정의된 경우 tmplNames와 값이 일치해야 한다.
템플릿 정의 관련 그리드 데모 참고
null
tmplLabelstring템플릿이 정의된경우 Reset과 Find 버튼 사이에 Select Element가 보여진다.
해당 select에 보여질 텍스트
Template:
zIndexinteger대화상자의 z-index 값.
다른 요소 아래에 대화상자가 보여지길 원하는경우 기본값인 950보다는 높아야 하며, 대부분의 경우 jQuery UI 대화상자의 기본값인 1000 보다 높아야 한다.
950




 위에서 언급한것처럼 서버로 검색 데이터 전달은 사용자정의, 툴바 검색과 다르다.
찾기 버튼을 클릭하면 그리드는 (_search=true와 함께) name=value 쌍의 3개 파라메터가 추가된다.

 - sField (searchField):  colModel의 index 값
 - sValue (searchString): 입력된 값
 - sOper (searchOper): 검색유형 (sopt array참고)

 예를들어 필드색인이 invid이고 조건이 같고 검색값이 123이면 서버에 전송되는 문자열은 다음과 같다.
http://localhost/demo35/server.php?...&searchField=invid&searchString=123&searchOper=eq






colModel 옵션

 - jqGrid v3.5 부터 모든 검색 메소드에 사용할 수 있는 공통 검색옵션을 사용하며, 아래는 colModel에서 설정해야 하는 옵션인다.
(일부 옵션은 특정 메소드에 적용할 수 없다.)
1004lucifer
OptionTypeDescriptionDefault
searchboolean필드를 검색할지 여부true
stypestring필드의 검색유형을 결정
text: text타입의 input element 생성
select: select element 생성
text
searchoptionsobject검색필드에 대한 이벤트나 그외 속성이 정의된 내용이 담긴 Object (아래참조)
searchrulesobject사용자 입력 유효성검사에 대한 추가조건이 포함된 Object

searchoptions 옵션은 사용자정의 검색 메소드에서는 적용되지 않으며, 이경우에는 별도의 옵션을 사용한다.



searchoptions 객체의 속성은 아래와 같다.


PropertyTypeDescription
dataUrlstring이 옵션은 stype:'select' 로써 select Element 인 경우에만 사용이 가능하며, select Element 를 로드할 url을 나타낸다.
이 옵션을 설정하면 Element는 ajax request로 받아온 값으로 채워지며 데이터는 원하는 옵션이 있어야 하며 한번만 호출이 된다.
응답내용의 예는 아래와 같다.
<select><option value=“1”>One</option> <option value=“2”>Two</option></select>.
buildSelectfunction이 옵션은 dataUrl 파라메터가 설정된 경우에만 사용할 수 있으며, 서버의 응답으로 select Element 를 만들 수 없는경우 이 함수를 이용해 select를 생성한다.
이 함수는 dataUrl 옵션과 같이 select, options 값이 포함된 문자열을 반환해야 하며, 서버의 응답값이 함수 파라메터로 넘겨진다.
dataInitfunction이 함수가 설정된경우 Element가 생성될 때 한번 호출이 된다.
이 함수에는 element object 가 전달된다.
dataInit: function(elem) {
  do something
}
이 함수에서 datepicker를 붙이려면 아래와 같이 할 수 있다.
dataInit : function (elem) {
  $(elem).datepicker();
}
dataEventsarraydata Element에 이벤트 리스트를 적용한다.
$(“#id”).bind(type, [data], fn) 과 같이 data Element에 이벤트를 바인딩하며 아래와 같이 기술한다.
dataEvents: [
 { type: 'click', data: { i: 7 }, fn: function(e) { console.log(e.data.i); }},
 { type: 'keypress', fn: function(e) { console.log('keypress'); } }
]
attrobject생성된 Element에 설정가능한 속성 Object
title을 설정하려면 아래와 같다.
attr : { title: “Some title” }
searchhiddenboolean기본적으로 그리드에서 숨겨진 Element는 검색할 수 없다.
필드가 숨겨진경우 검색을 가능하게 하려면 true로 설정해라.
soptarray이 옵션은 사용자정의검색을 제외한 모든 검색에서 사용가능하며, element에 적용되는 작업을 결정한다.
설정하지 않은경우 사용가능한 모든옵션이 사용되며, 툴바검색에서는 첫번째 요소가 사용된다.
모든 옵션은 다음과 같다.
['eq','ne','lt','le','gt','ge','bw','bn','in','ni','ew','en','cn','nc']
해당 텍스트는 언어파일에 있으며 의미는 다음과 같다.
['equal','not equal', 'less', 'less or equal','greater','greater or equal', 'begins with','does not begin with','is in','is not in','ends with','does not end with','contains','does not contain']
배열 요소의 순서는 상관없다.
defaultValuestring검색 입력요소의 기본값으로 사용할 문자열
valuemixed이 옵션은 stype:'select' 인 경우에만 사용가능하며 검색대화상자의 select option 을 정의한다.
stype:'select'가 설정되고 dataUrl 옵션이 설정되지 않은경우 값은 string 또는 object 이다.
값이 string인경우 value:label 쌍으로 설정되어야 하며 label의 값은 콜론(:)으로 분리되며 세미콜론(;)으로 끝나야 한다.
editoptions:{value:“1:One;2:Two”} <= 이렇게 세미콜론(;) 없이 끝나면 안된다.
값이 object인경우 value:name 쌍으로 정의되어야 한다.
ex) editoptions:{value:{1:'One',2:'Two'}}
clearSearchboolean기본값: true
false로 설정 시 검색데이터를 지우는 X아이콘을 비활성화 한다.



 참고
 - searchoptions의 dataUrl옵션이 select 타입 검색에서 사용되지 않으면, select에 대한 정의는 searchoptions의 속성값에서 처음으로 가져오며, 정의되지 않은경우 editoptions의 속성값을 사용한다.
 ex) editoptions:{value:“1:one;2:two”,…}






colModel 규칙

<script>
jQuery("#grid_id").jqGrid({
...
   colModel: [ 
      ... 
      {name:'price', index:'price', width:60, search:true, stype:'text', searchoptions:{dataInit:datePick, attr:{title:'Select Date'}} },
      ...
   ]
...
});
datePick = function(elem)
{
   jQuery(elem).datepicker();
}
</script>


검색규칙
 - 이옵션은 검색가능한 요소에 추가속성을 추가하고 colModel에서 사용해야하며 대부분 사용자 입력값을 서버에 전송하기전에 검사하는데 사용된다.

<script>
jQuery("#grid_id").jqGrid({
...
   colModel: [ 
      ... 
      {name:'price', ..., searchrules:{required:true....}, search:true },
      ...
   ]
...
});
</script>


사용가능한 옵션목록
1004lucifer
OptionTypeDescription
requiredbooleantrue 설정 시 값이 비어있는경우 에러메시지 표시
numberbooleantrue 설정 시 값이 숫자가 아닌경우 에러메시지 표시
integerbooleantrue 설정 시 값이 integer가 아닌경우 에러메시지 표시
minValuenumber(integer)설정한경우 값이 설정값보다 작은경우 에러메시지 표시
maxValuenumber(integer)설정한경우 값이 설정값보다 크면 에러메시지 표시
emailbooleantrue 설정 시 값이 이메일 형식이 아니면 에러메시지 표시
urlbooleantrue 설정 시 값이 url 형식이 아니면 에러메시지 표시
datebooleantrue 설정 시 값은 datefmt옵션에서 가져온 값(설정되지 않으면 ISO date 사용)이며 date형식이 아니면 에러메시지 표시
timebooleantrue 설정 시 time 형식이 아니면 에러메시지 표시.
현재는 hh:mm 포멧과 옵션으로 마지막에 am/pm이 있다.
custombooleantrue 설정 시 custom_func 함수의 규칙에 따라체크한다. (아래 참고)
custom_funcfunction이 함수는 custom 옵션이 true인 경우에만 사용이 가능하며, 전달되는 파라메터는 체크할 값과 colModel의 이름이다.
이 함수는 아래와 같이 배열을 반환해야 한다.
1번째: 성공실패여부 true 또는 false
2번째: 1번째값이 false인경우 에러메시지
ex) [false,“Please enter valid value”]



 검색규칙은 검색대화상자에서만 사용가능하며 검색필터에서는 작동되지 않는다.
 참고링크 - http://stackoverflow.com/a/9011733




사용자정의 검사 예제
<script>
function mypricecheck(value, colname) {
if (value < 0 || value >20) 
   return [false,"Please enter value between 0 and 20"];
else 
   return [true,""];
}
jQuery("#grid_id").jqGrid({
...
   colModel: [ 
      ... 
      {name:'price', ..., searchrules:{custom:true, custom_func:mypricecheck....}, search:true },
      ...
   ]
...
});
</script>


참고
 - http://www.trirand.com/jqgridwiki/doku.php?id=wiki:singe_searching

댓글