본문바로가기

Component

AutoComplete

Basic
  • AutoComplete 컴포넌트는 입력 값에 따른 자동 완성 기능을 제공합니다. class="Autocomplete"
  • 자동 완성의 데이터를 가져오기 위한 두 가지 방식을 제공합니다.

data-url 방식

  • 특정 url에 input의 값을 쿼리로 보내어 자동 완성 데이터를 가져오는 방식입니다.
  • 실제 자동 완성 추출 데이터는 서버에서 직접 구현이 되어야 합니다. 아래의 url 은 예제를 위한 임의의 샘플입니다.
  • data-url 속성 값을 정의하거나, .setOptions 의 url 옵션 값을 설정합니다.
"m"을 입력해보세요

<div class="Autocomplete" data-url="/words" data-paramname="keyword" id="divTest01"></div>

data-source 방식

  • 정해진 JSON 데이터 안에서 input 값을 통해 자동 완성 데이터를 완성하는 방식입니다.
  • data-source 속성 값을 정의하거나, .setOptions 의 source 옵션 값을 설정합니다.
"i" 을 입력해보세요

<div class="Autocomplete" data-source='[{"text":"Idaho"},{"text":"Illinois"},{"text":"Indiana"},{"text":"Iowa"}]' id="divTest02"></div>

Attributes

data-bind

data-bind를 통해 데이터바인딩이 가능합니다.
.select(arg)함수 예시와 같이 select룰에 index값, text값 또는 Object사용이 가능합니다.
참고 : select(arg) 함수

<div id="divTestBind" class="Autocomplete" data-bind="source: data, select: selected_val" ></div>
$('#divTestBind').setData({ 
	data : [{ id : "code1", text : "ABC", value : "code1"},
		{ id : "code2", text : "BBC", value : "code2"},
		{ id : "code3", text : "BBA", value : "code3"},
		{ id : "code4", text : "CBC", value : "code4"},
		{ id : "code5", text : "DBC", value : "code5"},
		{ id : "code6", text : "BFC", value : "code6"},
		{ id : "code7", text : "BDA", value : "code7"},
		{ id : "code8", text : "CBA", value : "code8"}],
	selected_val : "CBC" });
}

data-datatype

  • Type: {string}
    • "json" (default) | "jsonp"
    • 서버에서 반환되는 데이터 형식을 지정할 때 사용합니다.

data-dynamic-dropdown

목록으로 보여지는 데이터 목록을 동적으로 생성하고자 할 때 사용합니다.
상위 엘리먼트 영역에 의해 데이터 목록이 가려지는 경우에 사용합니다.

  • "true"
    • 목록이 열리는 시점에 document.body 영역에 데이터 목록 객체가 생성되고, close 되는 시점에 삭제됩니다.
  • selector
    • 목록이 열리는 시점에 데이터 목록 객체를 생성하여 추가할 영역 엘리먼트의 selector을 지정합니다.
    • ex) data-dynamic-dropdown="#divId"
<div class="Autocomplete"  data-dynamic-dropdown="true"  data-filter="prefix | ignoreWhitespace" data-source='[{"text":"Idaho"},{"text":"Illinois"},{"text":"Indiana"},{"text":"Iowa"}]' id="divTest12" ></div>

data-enter-selectfirst

input에서 엔터키 입력 시 첫번째 항목을 선택하도록 설정할 때 사용합니다.

  • Type: {boolean}
    • false (default)
      • input에서 엔터키 입력 시 첫번째 항목이 선택됩니다.
"i"을 입력 후 엔터키를 누르세요

<div class="Autocomplete"  data-enter-selectfirst="true" data-minlength="1" data-source='[{"text":"Idaho"},{"text":"Illinois"},{"text":"Indiana"},{"text":"Iowa"}]' id="divTest13"></div>

data-filter

자동 완성 필터링 옵션을 지정하고자 할 때 사용합니다. (data-url 방식에서는 적용되지 않습니다)
pipe(|) 키를 사용하여 여러 옵션을 지정할 수 있습니다.

  • Type: {string}
    • "prefix"
      • 접두사 일치
    • "suffix"
      • 접미사 일치
    • "caseSensitive"
      • 대소문자 구분
    • "ignoreWhitespace"
      • 공백 무시
<div class="Autocomplete" data-filter="prefix | ignoreWhitespace" data-source='[{"text":"Idaho"},{"text":"Illinois"},{"text":"Indiana"},{"text":"Iowa"}]' id="divTest11"></div>

data-fitwidth

  • Type: {boolean}
    • true (default)
      • input과 데이터 목록의 폭(width)을 일치시킵니다.
      • input의 길이보다 내용이 길 경우 ellipsis(말줄임표, ...)로 처리되어 보여집니다.
    • false
      • 데이터 목록의 폭(width)이 리스트 길이에 따라 달라집니다.
      • input 넓이보다 작아지지 않습니다.
"a"을 입력해보세요

data-fitwidth=true
data-fitwidth=false
<h5> data-fitwidth=true </h5>
<div class="Autocomplete" id="fitTrue" data-fitwidth="true" data-url="/words" data-paramname="keyword" ></div>
<h5> data-fitwidth=false </h5>
<div class="Autocomplete" id="fitFalse" data-fitwidth="false" data-url="/words" data-paramname="keyword" ></div>

data-fixed-width

  • Type: {number}
    • fitwidth 옵션이 false 일경우 데이터 목록의 넓이를 픽셀 단위로 설정합니다.
<div class="Autocomplete" data-fixed-width="300" data-fitwidth="false" data-paramname="keyword" data-source='[{"text":"Alopex UI Framework 최소한의 자바스크립트 코드를 통한 HTML5 기반의 Rich UI 제작 프레임워크"},{"text":"Illinois"},{"text":"Indiana"},{"text":"Iowa"}]' id="divTest15"></div>

data-max-count

  • Type: {number}
    • maxheight옵션이 정의되지 않았을때 필터링된 내용의 높이를 갯수로 설정합니다.
"m"을 입력해보세요

<div class="Autocomplete" data-max-count="5" data-url="/words" data-paramname="keyword" id="divTest14"></div>

data-maxheight

  • Type: {number}
    • 데이터 목록의 최대 높이 값(px)을 지정할 때 사용합니다.
"m"을 입력해보세요

<div class="Autocomplete" data-maxheight="100" data-url="/words" data-paramname="keyword" id="divTest09"></div>

data-maxresult

  • Type: {number}
    • 100 (default)
    • 자동 완성 결과의 최대 갯수를 설정하고자 할 때 사용합니다.
"i"을 입력해보세요

maxresult : 2
    <div class="Autocomplete" data-source='[{"text":"Idaho"},{"text":"Illinois"},{"text":"Indiana"},{"text":"Iowa"}]' data-maxresult="2" id="divTest08"></div>

data-method

  • Type: {string}
    • "GET" (default) | "POST"
    • ajax 통신 메소드를 지정하고자 할 때 사용합니다.

data-minlength

  • Type: {number}

    • 0 (default)
    • 텍스트의 길이가 minlength보다 같거나 클 때 자동완성 기능이 동작합니다.

    • 정해진 데이터 안에서 input 값을 통해 자동 완성 데이터를 완성하는 방식

"ida"을 입력해보세요

<div class="Autocomplete"  data-minlength="3" data-source='[{"text":"Idaho"},{"text":"Illinois"},{"text":"Indiana"},{"text":"Iowa"}]' id="divTest06"></div>

data-noresultstr

  • Type: {string}
    • 자동 완성 결과 없을 때 보여줄 텍스트를 지정하고자 할 때 사용합니다.
"k"을 입력해보세요

<div class="Autocomplete" data-noresultstr="매칭 결과 없음" data-source='[{"text":"Idaho"},{"text":"Illinois"},{"text":"Indiana"},{"text":"Iowa"}]' id="divTest07"></div>

data-open-button

  • Type: {boolean}
    • false (default)
    • input element에 열림 버튼을 생성 여부를 설정합니다.
<div class="Autocomplete" data-open-button="true" data-source='[{"text":"Idaho"},{"text":"Illinois"},{"text":"Indiana"},{"text":"Iowa"}]' id="divTest10"></div>

data-paramname

"ma"을 입력해보세요

<div class="Autocomplete" data-url="/words" data-minlength=2 data-paramname="keyword" data-datatype="json" id="divTest03"></div>

data-position

  • Type: {string}
    • "bottom" (default) | "top"
    • dropdown의 위치를 설정합니다.
<div class="Autocomplete" data-source='[{"text":"Idaho"},{"text":"Illinois"},{"text":"Indiana"},{"text":"Iowa"}]' data-position="top"></div>

data-reset-button

  • Type: {boolean}
    • false (default)
    • input element에 삭제 버튼을 생성합니다.
<div class="Autocomplete"  data-reset-button="true" data-source='[{"text":"Idaho"},{"text":"Illinois"},{"text":"Indiana"},{"text":"Iowa"}]' id="divTest05" ></div>

data-select-text

  • Type: {boolean}
    • false (default)
    • Text 박스 클릭 시 텍스트가 모두 선택될지를 지정합니다.
Text 박스에 "idaho"를 입력 후 Click 해보세요

<div class="Autocomplete" data-source='[{"text":"Idaho"},{"text":"Illinois"},{"text":"Indiana"},{"text":"Iowa"}]'  data-select-text="true"  id="divTest16" ></div>

data-source

  • Type: {object}
    • 자동 완성의 데이터를 직접 넣어 줄 때 사용합니다.
"ida"을 입력해보세요

<div class="Autocomplete" data-source='[{"text":"Idaho"},{"text":"Illinois"},{"text":"Indiana"},{"text":"Iowa"}]' id="divTest04"></div>

data-url

  • Type: {string}
    • input 값이 바뀔 때 마다 특정 URL에서 해당 텍스트 값을 쿼리로 날려 데이터를 가져올 때 사용합니다.
    • data-method, data-datatype, data-paramname 속성은 data-url 이 설정되었을 때만 사용 가능합니다.
Options

$a.setup, set/getOption API에 사용할 수 있는 옵션 정보입니다.

bind

datatype

dynamicdropdown

enterselectfirst

filter

fitwidth

fixedwidth

maxcount

maxheight

maxresult

method

minlength

noresultstr

openbutton

paramname

position

resetbutton

selecttext

source

url

Functions

.clear()

Autocomplete 컴포넌트 안의 input 값을 지우고 데이터 목록을 초기화 하고자 할 때 사용합니다.

<div class="Autocomplete" id="autoclear" data-source='[{"text":"Maine","capital":"Augusta"},{"text":"Maryland","capital":"Annapolis"},{"text":"Massachusetts","capital":"Boston"}]' ></div>
<button class="Button" id="clearBtn">clear</button>
$("#clearBtn").on("click", function(e){
	$("#autoclear").clear();
});

.close()

Autocomplete 컴포넌트를 동적으로 닫을 때 사용하는 함수입니다.

<div class="Autocomplete" id="autoclose" data-source='[{"text":"Maine","capital":"Augusta"},{"text":"Maryland","capital":"Annapolis"},{"text":"Massachusetts","capital":"Boston"}]' ></div>
<a id="btn_close_mouseover" class="Button">마우스를 올려보세요</a>
</div>
$('#btn_close_mouseover').on("mouseover", function(){
	$('#autoclose').close();
});

.getOptions()

Autocomplete에 설정된 옵션값을 모두 가져올 수 있습니다.

  • Return {object}
    • object
      • Autocomplete에 설정된 옵션을 key-value로 가지는 오브젝트를 리턴합니다.
//Autocomplete에 설정된 모든옵션값을 가져옵니다.
$('#Autocomplete').getOptions();

.getSelectedData()

선택된 항목의 JSON 데이터를 가져오는 API 입니다.

  • Return
    • Type: {JSON object}
      • 자동 완성 목록에서 선택된 항목의 JSON 데이터를 return하여 줍니다.
<span class="Autocomplete" id="test_getSelectedData" data-source='[{"text":"Maine","capital":"Augusta"},{"text":"Maryland","capital":"Annapolis"},{"text":"Massachusetts","capital":"Boston"}]'></span>
<button class="Button" id="getSelectedDataBtn"> getSelectedData </button>
$("#getSelectedDataBtn").on('click', function(){
	var getSelectedData = $("#test_getSelectedData").getSelectedData();
	alert("getSelectedData : "+JSON.stringify(getSelectedData));
});

.getText()

아이템 선택 여부와 상관없이 INPUT의 텍스트를 가져오는 API입니다.

  • Return {string}
    • INPUT의 텍스트를 return하여 줍니다.
<div class="Autocomplete" id="autogtext" data-source='[{"text":"Maine","capital":"Augusta"},{"text":"Maryland","capital":"Annapolis"},{"text":"Massachusetts","capital":"Boston"}]' ></div>
<a id="btn_gtext_mouseover" class="Button">getText</a>
</div>
$('#btn_gtext_mouseover').on("click", function(){
	alert($('#autogtext').getText());
});

.refreshFilter()

입력(input)값으로 데이터 목록을 필터링해주는 함수입니다. Autocomplete 컴포넌트는 키 입력에 의해서 데이터 목록을 필터링합니다. 따라서 키 입력없이 목록을 재구성하고 싶은 경우에 refreshFilter API 를 사용합니다.

<div class="Autocomplete" id="refreshFilter" data-source='[{"text":"Maine","capital":"Augusta"},{"text":"Maryland","capital":"Annapolis"},{"text":"Massachusetts","capital":"Boston"}]' ></div>
<button class="Button" id="refreshFilterBtn">refreshFilter</button>
// autocomplete 컴포넌트의 텍스트를 동적으로 변경
$("#refreshFilter > input").val("mai");

$("#refreshFilterBtn").on("click", function(e){
	$("#refreshFilter").refreshFilter();
});

.select(arg)

Autocomplete 안의 목록(드롭다운 메뉴)을 동적 선택 합니다.

  • Parameters
    • {Number | String | Object} Required
      • {Number}
        • 선택할 목록의 인덱스 값을 통해 선택합니다.
      • {String}
        • 텍스트로 목록을 선택합니다.
      • {Object}
        • data의 id 값을 통해 선택합니다. (id 값이 있을 경우에만 유효합니다)
        • Object에 선언된 속성 값들을 비교하여 일치한 Data를 선택합니다.
<div class="Autocomplete" id="select"></div>
<button class="Button" id="selectByIndexBtn">select(0)</button>
<button class="Button" id="selectByTextBtn">select("BBC")</button>
<button class="Button" id="selectByIdBtn">select({id : "code3"})</button>
<button class="Button" id="selectByObjBtn">select({id : "code4", text : "CBC"})</button>
$("#select").setOptions({
	source : [
		{ id : "code1", text : "ABC", value : "code1"},
		{ id : "code2", text : "BBC", value : "code2"},
		{ id : "code3", text : "BBA", value : "code3"},
		{ id : "code4", text : "CBC", value : "code4"}
	]
});
$("#selectByIndexBtn").on("click", function(e){
	$("#select").clear(); // 데이터 목록 초기화
	$("#select").select(0);
});
$("#selectByTextBtn").on("click", function(e){
	$("#select").clear(); // 데이터 목록 초기화
	$("#select").select("BBC");
});
$("#selectByIdBtn").on("click", function(e){
	$("#select").clear(); // 데이터 목록 초기화
	$("#select").select({id : "code3"});
});
$("#selectByObjBtn").on("click", function(e){
	$("#select").clear(); // 데이터 목록 초기화
	$("#select").select({id : "code4", text : "CBC"});
});

.setCustomFilter(function)

자동 완성 필터링을 위한 커스텀 함수를 등록하는 함수입니다. (data-url 방식에서는 적용되지 않습니다)

  • Parameters
    • function(el, source, text) Required
      • 필터링 처리 함수를 넣어줍니다.
      • el {element}
        • Autocomplete 엘리먼트
      • source {array}
        • 필터링 대상 JSONArray
      • text {string}
        • 필터링 키워드
<div class="Autocomplete" id="custom" data-source='[{"text":"Idaho"},{"text":"Illinois"},{"text":"Indiana"},{"text":"Iowa"}]'></div>
$("#custom").setCustomFilter(function(el, source, text){
	// 필터링 처리
	console.log('입력 텍스트 : '+text);

	return source;
});

.setEnabled(enabled)

Autocomplete 컴포넌트를 활성화 / 비활성화할 수 있는 함수입니다.

  • Parameters
    • enabled {Boolean} Required
      • Autocomplete 컴포넌트를 활성화 / 비활성화 합니다.

<div class="Autocomplete" id="autoSetEnable"></div>
<button class="Button" id="enabledBtn">setEnabled(true)</button>
<button class="Button" id="disabledBtn">setEnabled(false)</button><br/>
$("#autoSetEnable").setOptions({
	source : [
		{ id : "code1", text : "ABC", value : "code1"},
		{ id : "code2", text : "BBC", value : "code2"},
		{ id : "code3", text : "BBA", value : "code3"},
		{ id : "code4", text : "CBC", value : "code4"}
	]
});
$("#enabledBt").on("click", function(e){
	$("#autoSetEnable").setEnabled(true);
});
$("#disabledBtn").on("click", function(e){
	$("#autoSetEnable").setEnabled(false);
});

.setOptions(JSON option)

.setOptions 함수를 통해서 옵션을 동적으로 설정할 수 있습니다.

Options에 정의되어 있는 옵션을 설정할 수 있습니다.

  • Parameters
    • url {string}
      • 자동 완성 데이터를 가져올 URL을 지정할 때 사용합니다. (data-url 속성과 동일 기능)
      • source 옵션과 동시에 사용될 수 없습니다.
    • method {string}
      • ajax 통신의 메소드를 지정하고자 할 때 사용합니다. (data-method 속성과 동일 기능)
      • url 속성 값이 지정되어 있을 때 유효하게 작동합니다.
      • 'GET'(default) | 'POST'
    • datatype {string}
      • 서버에서 반환되는 데이터 형식을 지정할 때 사용합니다. (data-datatype 속성과 동일 기능)
      • url 속성 값이 지정되어 있을 때 유효하게 작동합니다.
      • 'json'| 'jsonp'
    • paramname {string}
      • 파라미터 이름을 설정해야 할 때 사용합니다. (data-paramname 속성과 동일 기능)
      • url 속성 값이 지정되어 있을 때 유효하게 작동합니다.
    • before {function}
      • 서버 통신 전처리 함수
      • url 속성 값이 지정되어 있을 때 유효하게 작동합니다.
"m"을 입력해보세요

<div class="Autocomplete" id="setOptions_url" ></div>
<button class="Button" id="setOptions1"> setOptions </button>
$("#setOptions1").on('click', function(){
	$("#setOptions_url").setOptions({
		url : "/words",
		method : "get",
		datatype : "json",
		paramname : "keyword",
		before : function(id, option){
			this.data.serviceId = "test"; // 파라미터 추가
		}
	});
});

  • Parameters
    • source {JSON Object} Optional
      • 자동 완성의 데이터를 직접 넣어 줄 때 사용합니다. (data-source 속성과 동일 기능)
      • url 옵션과 동시에 사용될 수 없습니다.
<div class="Autocomplete" id="setOptions_source" ></div>
<button class="Button" id="setOptions2"> setOptions </button>
$("#setOptions2").on('click', function(){
	$("#setOptions_source").setOptions({
		source : [{"text":"Maine","capital":"Augusta"},
			{"text":"Maryland","capital":"Annapolis"},
			{"text":"Massachusetts","capital":"Boston"},
			{"text":"Michigan","capital":"Lansing"},
			{"text":"Minnesota","capital":"St Paul"},
			{"text":"Mississippi","capital":"Jackson"},
			{"text":"Missouri","capital":"Jefferson City"}
		]
	});
});

  • Parameters
    • minlength {number} Optional
      • 텍스트의 길이가 minlength보다 같거나 클 때 자동완성 기능이 동작합니다. (data-minlength 속성과 동일 기능)
"mis"을 입력해보세요

<span class="Autocomplete" id="setOptions_minlen"></span>
<button class="Button" id="setOptions3"> setOptions </button>
$("#setOptions3").on('click', function(){
	$("#setOptions_minlen").setOptions({
		source : [{"text":"Maine","capital":"Augusta"},
			{"text":"Maryland","capital":"Annapolis"},
			{"text":"Massachusetts","capital":"Boston"},
			{"text":"Michigan","capital":"Lansing"},
			{"text":"Minnesota","capital":"St Paul"},
			{"text":"Mississippi","capital":"Jackson"},
			{"text":"Missouri","capital":"Jefferson City"}],
		minlength : 3
	});
});

  • Parameters
    • noresultstr {string} Optional
      • "No Results" (default)
      • 자동 완성할 데이터가 없을 때 보여지는 텍스트를 설정할 수 있습니다.
텍스트를 입력해보세요

<span class="Autocomplete" id="setOptions_noresultstr"></span>
<button class="Button" id="setOptions4"> setOptions </button>
$("#setOptions4").on('click', function(){
	$("#setOptions_noresultstr").setOptions({
		source : [],
		noresultstr : '매칭 결과 없음'
	});
});

  • Parameters
    • maxresult {number} Optional
      • 100 (default)
      • 자동 완성 결과의 최대 갯수를 설정할 수 있습니다.
"m"을 입력해보세요

<span class="Autocomplete" id="setOptions_maxresult"></span>
<button class="Button" id="setOptions5"> setOptions </button>
$("#setOptions5").on('click', function(){
	$("#setOptions_maxresult").setOptions({
		source : [{"text":"Maine","capital":"Augusta"},
			{"text":"Maryland","capital":"Annapolis"},
			{"text":"Massachusetts","capital":"Boston"},
			{"text":"Michigan","capital":"Lansing"},
			{"text":"Minnesota","capital":"St Paul"},
			{"text":"Mississippi","capital":"Jackson"},
			{"text":"Missouri","capital":"Jefferson City"}],
		maxresult : 3
	});
});

  • Parameters
    • select {function} Optional
      • 자동 완성 목록을 선택했을 때 처리할 함수를 넣어줍니다.
      • function(event, selectedData)
        • event {Object}
          • 이벤트 객체 입니다 (select API 실행 시 null값이 리턴 됩니다)
        • selectedData {Object}
          • 선택된 데이터 객체 입니다
"m"를 입력한 후 목록 중 하나를 선택해보세요

<span class="Autocomplete" id="setOptions_select"></span>
<button class="Button" id="setOptions6"> setOptions </button>
$("#setOptions6").on('click', function(){
	$("#setOptions_select").setOptions({
		source : [{"text":"Maine","capital":"Augusta"},
			{"text":"Maryland","capital":"Annapolis"},
			{"text":"Massachusetts","capital":"Boston"},
			{"text":"Michigan","capital":"Lansing"},
			{"text":"Minnesota","capital":"St Paul"},
			{"text":"Mississippi","capital":"Jackson"},
			{"text":"Missouri","capital":"Jefferson City"}],
		select : function(e,selobj){
			alert("selected : "+JSON.stringify($("#setOptions_select").getSelectedData()));
		}
	});
});

  • Parameters
    • selectedDataDefault {object} Optional
      • getSelectedData API 호출 시, 선택된 항목이 없을 경우 리턴값을 설정할 때 사용합니다.
<span class="Autocomplete" id="setOptions_default" data-source='[{"text":"Idaho"},{"text":"Illinois"},{"text":"Indiana"},{"text":"Iowa"}]' ></span>
<button class="Button" id="selectedDataDefault"> getSelectedData </button>
$("#setOptions_default").setOptions({
	selectedDataDefault : { "text" : "" }
});
$("#selectedDataDefault").on("click", function(){
	var data = $("#setOptions_default").getSelectedData();
	alert("getSelectedData : "+JSON.stringify(data));
});