jQuery 플러그인은 검색창을 직접 구성하여 상세 설정을 하고 싶은 분들께 추천하는 방법입니다. 좀더 간단하게 적용하는 방법을 원하신다면 구현 예제 페이지에서 “팝업 레이어” 방식을 알아보세요.
기본적인 검색창만 표시하려면 아래와 같이 사용하시면 됩니다.
$("#postcodify").postcodify();
postcodify() 메소드를 호출할 때 다양한 옵션을 주어 Postcodify의 작동 방식을 커스터마이징할 수 있습니다.
원하시는 기능을 추가하려면 아래와 같은 형태로 설정을 해주시면 됩니다.
(jQuery의 일반적인 사용법과 동일합니다.)
$("#postcodify").postcodify({
설정키1: 설정값1,
설정키2: 설정값2
});
필수 항목은 없습니다. 꼭 필요한 항목만 넣으시면 나머지는 모두 기본값으로 채워집니다.
마지막 항목 뒤에 쉼표(,)가 들어가지 않도록 주의하시기 바랍니다. PHP에서 배열을 선언할 때는 마지막에 쉼표가 들어가도 되지만, 자바스크립트에서 그렇게 하면 인터넷 익스플로러 일부 버전에서 오류가 발생할 수 있습니다.
접속할 검색서버(메인서버)의 경로를 지정합니다. 검색서버를 직접 구축한 경우에만 설정하시면 됩니다. 버전에 따라 검색서버와 호환되지 않는 경우가 있으니 버전별 호환성 안내 페이지를 참고하시기 바랍니다.
접속할 검색서버(백업서버)의 경로를 지정합니다. 무료 API 사용시에는 자동으로 백업서버가 설정됩니다.
검색서버를 2대 이상 직접 구축하신 경우에는 1대를 api, 다른 1대를 apiBackup으로 설정하시고,
그 외의 경우에는 설정하지 마시기 바랍니다.
검색서버(메인서버)에서 이 시간 안에 응답하지 않을 경우 오류로 취급합니다. 단위는 1/1000초입니다. 백업서버가 있는 경우에는 이 시간이 경과한 후 자동으로 백업서버에 접속을 시도하게 됩니다.
검색서버(백업서버)에서 이 시간 안에 응답하지 않을 경우 오류로 취급합니다. 단위는 1/1000초입니다.
true 또는 falsefalse이 항목을 true로 설정하면 메인서버를 무시하고 백업서버에 먼저 접속합니다.
특별한 경우 외에는 사용할 필요가 없습니다.
postcodify() 메소드 호출에 사용한 선택자별다른 설정을 하지 않을 경우, Postcodify는 최초 호출에 사용된 선택자(위의 예제에서는 <div id="postcodify">) 내부에
검색 폼과 검색 결과를 모두 표시합니다.
그러나 이 항목을 사용하면 검색 폼을 별도의 위치에 표시하도록 할 수 있습니다.
postcodify() 메소드 호출에 사용한 선택자controls와 비슷한 기능입니다. 이 항목을 사용하면 검색 결과를 별도의 위치에 표시하도록 할 수 있습니다.
"ko" 또는 "en")"ko"검색 단추, 오류 메시지 등에 표시할 언어를 선택합니다.
검색 후에 표시되는 메시지들은 검색어의 언어를 따르므로 이 설정의 영향을 받지 않습니다. (예: “세종대로 110” 검색시 한글로 표시, “110 Sejong-daero” 검색시 영문으로 표시)
true 또는 falsefalse건물번호 또는 번지수까지 검색하여 결과가 1개 나온 경우 자동으로 선택되도록 하는 기능입니다. (건물명으로 검색한 경우에는 적용되지 않습니다.)
"검색" 또는 "Search"검색 단추에 표시할 내용입니다. 이미지를 사용하고 싶은 경우 <img> 태그를 넣을 수 있습니다.
공식 사이트에서는 이 항목을 사용하여 검색 단추에 돋보기 아이콘을 표시하고 있습니다.
HTML이 포함되어 있는 경우 그대로 표시되므로, <script> 등 위험한 태그가 들어가지 않도록 주의 바랍니다.
"daum", "naver", "google" 또는 URL) 또는 falsefalse각각의 검색 결과를 지도에 표시하는 링크를 넣을 수 있습니다. 위에 나열된 포털사이트를 사용할 경우 링크 주소를 자동으로 생성합니다.
위에 나열되지 않은 지도 서비스 또는 모바일 어플리케이션으로 연결하시려면 해당 URL을 직접 설정하셔야 합니다.
이 때 $JUSO는 도로명주소, $JIBEON은 지번주소로 치환됩니다.
false로 설정하면 지도 링크를 넣지 않습니다.
"지도"지도 링크에 표시할 내용입니다. 이미지를 사용하고 싶은 경우 <img> 태그를 넣을 수 있습니다.
공식 사이트에서는 이 항목을 사용하여 지도 링크를 아이콘으로 처리하고 있습니다.
HTML이 포함되어 있는 경우 그대로 표시되므로, <script> 등 위험한 태그가 들어가지 않도록 주의 바랍니다.
선택한 주소의 5자리 새우편번호(국가기초구역번호)를 입력할 <input> 또는 <textarea> 태그를 지정할 수 있습니다.
지정하지 않으면 새우편번호를 입력하지 않습니다.
선택한 주소의 5자리 새우편번호(국가기초구역번호)를 입력할 <input> 또는 <textarea> 태그를 지정할 수 있습니다.
지정하지 않으면 새우편번호를 입력하지 않습니다.
선택한 주소의 6자리 기존 우편번호를 입력할 <input> 또는 <textarea> 태그를 지정할 수 있습니다.
지정하지 않으면 우편번호를 입력하지 않습니다.
우편번호는 하이픈을 포함한 000-000 형태로 입력됩니다.
선택한 한글 도로명주소를 입력할 <input> 또는 <textarea> 태그를 지정할 수 있습니다.
지정하지 않으면 한글 도로명주소를 입력하지 않습니다.
선택한 한글 지번주소를 입력할 <input> 또는 <textarea> 태그를 지정할 수 있습니다.
지정하지 않으면 한글 지번주소를 입력하지 않습니다.
선택한 영문 도로명주소를 입력할 <input> 또는 <textarea> 태그를 지정할 수 있습니다.
지정하지 않으면 영문 도로명주소를 입력하지 않습니다.
선택한 영문 지번주소를 입력할 <input> 또는 <textarea> 태그를 지정할 수 있습니다.
지정하지 않으면 영문 지번주소를 입력하지 않습니다.
상세주소를 입력할 <input> 또는 <textarea> 태그를 지정할 수 있습니다.
새주소는 1) 도로명주소, 2) 동수·층수·호수 등 상세정보, 3) 법정동과 공동주택명 등 참고항목으로 이루어져 있습니다.
아래의 focusDetails 항목과 함께 사용하여 검색 완료 후 해당 태그로 커서를 옮겨주어
사용자가 동수·층수·호수 등의 정보를 쉽게 입력할 수 있도록 합니다.
참고항목을 입력할 <input> 또는 <textarea> 태그를 지정할 수 있습니다.
지정하지 않으면 참고항목을 입력하지 않습니다.
새주소는 1) 도로명주소, 2) 동수·층수·호수 등 상세정보, 3) 법정동과 공동주택명 등 참고항목으로 이루어져 있습니다.
아래의 useFullJibeon 항목을 사용하면 법정동 뿐 아니라 지번주소까지 참고항목에 추가할 수 있으나,
지번 추가시 공식적인 표기방법에 어긋나므로 주의하시기 바랍니다.
선택한 주소의 건물관리번호를 입력할 <input> 또는 <textarea> 태그를 지정할 수 있습니다.
지정하지 않으면 입력하지 않습니다.
사서함 주소는 건물관리번호가 없습니다.
선택한 주소의 건물명을 입력할 <input> 또는 <textarea> 태그를 지정할 수 있습니다.
지정하지 않으면 입력하지 않습니다.
선택한 주소의 아파트 동수 범위를 입력할 <input> 또는 <textarea> 태그를 지정할 수 있습니다.
지정하지 않으면 입력하지 않습니다.
선택한 주소의 행정동명, 건물명 목록, 관련지번 목록 등을 입력할 <input> 또는 <textarea> 태그를 지정할 수 있습니다.
지정하지 않으면 입력하지 않습니다.
insertBuildingId와 같은 기능입니다. 구 버전 플러그인과의 호환성을 위해 제공되며,
가능하면 insertBuildingId로 전환하시기를 권합니다.
keywords (검색어)검색서버 접속 직전에 호출할 콜백 함수입니다.
false를 반환할 경우 검색이 취소됩니다.
keywords (검색어), results (검색 결과 목록)검색서버에서 결과를 받아온 직후에 호출할 콜백 함수입니다.
false를 반환할 경우 검색이 취소됩니다.
selectedEntry (선택한 항목의 jQuery 선택자)검색 결과 중 하나를 사용자가 선택할 경우, 주소와 우편번호 등을 폼에 입력하기 전에 호출할 콜백 함수입니다.
false를 반환할 경우 선택이 취소됩니다.
selectedEntry (선택한 항목의 jQuery 선택자)검색 결과 중 하나를 사용자가 선택할 경우, 주소와 우편번호 등을 폼에 입력한 후 호출할 콜백 함수입니다.
false를 반환할 경우 선택이 취소되지만, 이 함수를 호출할 때면 이미 대부분의 작업이 완료된 상태이므로
상세주소 입력란으로 커서를 이동하는 것 외에는 사실상 아무것도 취소되지 않습니다.
선택한 주소를 별도의 폼에 다시 입력하거나 팝업창을 닫는 등의 작업은 이 항목을 사용하여 구현하시기 바랍니다.
postcodify() 메소드를 호출하여 검색 폼 생성을 완료한 후에 호출할 콜백 함수입니다.
Postcodify가 생성하는 태그들에 변경을 주고 싶거나, 별도의 스타일을 적용하고 싶은 경우 이 항목을 사용하시기 바랍니다.
검색 성공시 호출할 콜백 함수입니다.
검색서버 접속에 실패하여 백업서버 접속을 시도하기 직전에 호출할 콜백 함수입니다.
검색서버 접속에 실패하였으나 다시 접속할 백업서버가 없거나, 백업서버 접속까지 실패한 경우 호출할 콜백 함수입니다.
성공·실패 여부와 관계없이 검색이 종료된 후에 호출할 콜백 함수입니다.
true 또는 falsetrue검색 폼을 생성한 후 키워드 입력란으로 커서를 옮길지 선택할 수 있습니다.
팝업창과 같이 주소 검색 기능만 있는 페이지라면 true로 설정하시고,
다른 필드를 먼저 입력해야 하는 페이지라면 false로 설정하십시오.
true 또는 falsetrue주소 선택시 동수·층수·호수 등 상세정보 입력란으로 커서를 옮길지 선택할 수 있습니다.
insertDetails 항목을 설정하지 않은 경우에는 이 설정도 무시됩니다.
true 또는 falsetrue이 항목을 true로 설정하면 관련지번 목록을 일단 숨기고 화살표를 클릭하면 표시하도록 합니다.
false로 설정하면 관련지번 목록을 숨기지 않습니다.
true 또는 falsefalse이 항목을 true로 설정하면 검색 결과의 갯수, 검색 소요시간 등을 표시하지 않습니다.
true 또는 falsefalse이 항목을 true로 설정하면 참고항목 입력란에 법정동과 공동주택명뿐 아니라 지번까지 입력됩니다.
택배기사님들께는 도움이 될 수도 있으나, 공식적인 표기방법에 어긋나므로 주의하시기 바랍니다.
로 설정하면 관련지번 목록을 숨기지 않습니다.
true 또는 falsefalse이 항목을 true로 설정하면 검색 결과가 없거나, 너무 많거나, 그 밖의 오류가 발생할 경우
오류를 검색 결과창에 직접 표시하지 않고 alert() 함수를 사용하여 모달창으로 띄웁니다.
true 또는 falsetrue이 항목을 false로 설정하면 CORS를 지원하는 브라우저에서도 CORS 대신 JSONP 방식으로 API 요청을 전송합니다.
CORS 지원이 잘 되지 않는 모바일 어플리케이션이나 CORS 요청이 방화벽으로 막혀있는 경우에는
이 설정을 변경하여 주시기 바랍니다.
단, JSONP는 CORS에 비해 오류 처리가 원활하지 않을 수 있으니 주의하십시오.
이 항목을 사용하면 무료 API 서버에 연결할 때 현재 웹페이지의 도메인을 자동 감지하지 않고 사용자가 지정한 도메인 정보를 전송할 수 있습니다. 모바일 어플리케이션처럼 도메인 정보가 없는 경우 유용하게 사용할 수 있으나, 해당 어플리케이션과 무관한 타인의 도메인을 도용할 경우 무료 API 이용약관에 어긋나니 주의하시기 바랍니다.
일반 웹페이지에서 사용하면서 도메인을 변조하면 리퍼러 헤더와 비교하여 쉽게 알 수 있으며, 이 경우 무료 API 이용이 자동으로 차단됩니다.
true 또는 falsefalse이 항목을 true로 설정하면 정확한 도로명+건물번호, 동·리+번지,
또는 사서함 번호를 입력한 경우에만 검색이 가능하게 됩니다.
기존의 방식대로 읍·면·동만 입력하여 검색하면 쓸만한 검색 결과를 얻기 힘들 뿐더러
검색 서버에도 많은 부담을 주고 쿼리수 가중치에 따라 일일 검색 횟수도 제한되므로,
신규 개발하는 웹사이트에서는 가능하면 이 항목을 true로 설정하여 서버 부담을 줄이고
사용자들이 도로명주소 검색에 보다 적합한 검색 방식을 익힐 수 있도록 해주시기 바랍니다.
true 또는 falsefalse이 항목을 true로 설정하면 검색 결과에 6자리 우편번호 대신 5자리 새우편번호(기초구역번호)를 표시합니다.
2015년 8월 이후 버전에서는 이 옵션을 사용하지 않아도 자동으로 새우편번호가 표시될 예정입니다.
이 설정을 사용하지 않더라도 div.code6와 div.code5에 적절한 스타일을 지정하면 기초구역번호를 표시하도록 할 수 있지만,
기존의 스타일시트를 그대로 사용하기를 원하실 경우 이 설정을 활용하면 편리합니다.
(실제 우편번호가 입력될 <input>을 지정하는 것과는 무관하니 착오 없으시기 바랍니다.)
true 또는 falsefalse현재 버전에서는 이 항목을 true로 설정하더라도 아무런 영향이 없습니다.
2015년 8월 이후 버전에서는 검색 결과에 새우편번호(기초구역번호)를 표시하는 것이 기본값으로 변경될 예정이므로, 계속해서 기존 우편번호를 표시하고 싶으신 경우에는 미리 이 옵션을 사용해 주시기 바랍니다.
이 설정을 사용하지 않더라도 div.code6와 div.code5에 적절한 스타일을 지정하면 기존 우편번호를 표시하도록 할 수 있지만,
기존의 스타일시트를 그대로 사용하기를 원하실 경우 이 설정을 활용하면 편리합니다.
(실제 우편번호가 입력될 <input>을 지정하는 것과는 무관하니 착오 없으시기 바랍니다.)
true 또는 falsefalse이 항목을 true로 설정하면 현재 페이지의 보안 여부와 무관하게 항상 SSL을 사용하여 검색서버에 접속합니다.
검색서버 주소를 별도로 지정한 경우에는 주소가 //로 시작하는 경우에만 적용됩니다.