Manual:Tag extensions/ko

각각의 프로젝트에 대해 간단한 문자열의 처리 등의 부가적인 기능을 가지는 wiki 마크 업을 확장하는일이 편리하다고 생각하는 것은 자주 있습니다.

간단한 태그 확장 기능은 콜백 (callback) 함수로 구성됩니다. 파서가 실행될 때, 실제의 HTML를 렌더링 하기 위해서 대응하는 콜백 함수를 호출하는 것으로, 파서는 모든 특별한 태그의 인스턴스를 찾아내 옮겨놓기 위해서, 콜백 함수는 퍼서에게훅(hook)됩니다.

예제
이 예에서는, 태그에 대한 콜백 함수를 등록합니다. 다음과 같이 사용자는 이 태그를 페이지에 추가할 수 있습니다:

...input...

파서는 efSampleRender 를 호출합니다. 그때, 3개의 인수가 전달됩니다.:


 * $input :   과   태그의 사이, 혹은 null, 태그가 닫혀 있는 경우에서는,  가 됩니다
 * $args : 태그의 인수로, HTML의 태그 속성과 같이 입력됩니다; 이것은 속성명으로 인덱스화 된 연상 배열입니다
 * $parser : 파서입니다; 더 고도의 확장 기능이 문맥상의 Title를 취득하거나 wiki 텍스트를 해석하거나 안괄호를 확장하거나 링크 관계나 의존성을 등록하거나 하기 위해서 이것을 사용합니다.

속성
다른 예를 봅시다:

이 예에서는, 값과 함께 태그에게 건네진 속성을 덤프 합니다.이것에 의해서 새로운, 커스텀 태그의 유연한 사양을 작성할 수 있게 됩니다.예를 들면,과 같은 것을 사용하고, 유저가 유저 페이지에 컨택트 폼을 찔러넣는을 가능하게 하는 태그 확장 기능을 정의한다고 합니다.

MediaWiki로 이용 가능한 태그 확장 기능은 매우 풍부합니다.그 중의 몇개인가는이 사이트에 등록되어 있어; 다른 것은 웹 검색을 통해 찾아낼 수 있습니다.

규약
하나의 확장 기능을 단독의 파일로 구성할 수 있습니다만, 각각의 확장 기능에 대해서, extensions 디렉토리안에 서브 디렉토리를 작성해 그 중에 이하의 3개의 파일을 설치하는 것을 추천합니다:


 * 작은 셋업 파일,
 * 국제화 파일,
 * 코드 본체를 포함한 파일,

셋업 파일에 의해서 1개의 요소가 배열에 추가됩니다.이 배열은 어느 파일이 로드 되는지를 지정합니다:

$wgAutoloadClasses[extension_name] = dirname(__FILE__). '/extension_name.body.php';

확장 기능을 공개한다

 * 1) Extension:라는 이름의 새로운 페이지를 작성합니다.그 페이지에서는 어떻게 인스톨 하는지, 그것을 사용하고 있는 모습을 나타내는 screen shot등의 정보를 게재합니다.이러한 정보의 게재를 지원하기 위해서Template:Extension라고 하는 편리한 템플릿이 있습니다.상세한 것에 대하여는 템플릿 페이지를 봐 주세요.페이지의 본체로 할 수 있을 뿐(만큼) 많은 정보를 추가해, talk 페이지에 써지는 유저의 질문에의 회답을 정기적으로 실시하는 것이 좋을 것입니다.또,Category:Extensions카테고리에 당신의 페이지가 표시되고 있는지 어떤지를 확인해 주세요. 노트: meta.wikimedia.org상에 확장 기능의 페이지가 존재하는 경우, 관리자에 의해서 완전한 이력과 함께 이전됩니다 - 지금까지의 사이는, meta로 편집을 계속해 주세요
 * 2) 확장 기능 코드의 범위내에서 새롭게Manual:Hooks/ko를 작성하는 확장 기능에 관해서는Extension hook registry페이지에 등록을 부탁합니다.새롭고특별 페이지를 작성하는 확장 기능에 관해서는Extension hook registry페이지로 등록을 부탁합니다.
 * 3) mediawiki-l메일링 리스트에 통지한다.

시큐러티 관련
상기의 예에 대하고, 입력치를 돌려주기 전에,htmlspecialchars</tt>를 이용해 입력치를 이스케이프 하고 있는 것에 눈치채신다고 생각합니다.임의의 HTML 인젝션을 회피하기 위해서 모든 유저 입력을 echo 하고 클라이언트에 돌려주기 전에 이 방법으로 취급하는 것은 중요합니다.HTML 인젝션은 크로스사이트스크리프팅(XSS)의 취약성을 이끌 가능성이 있기 때문입니다.

타이밍과 확장 기능
확장 기능에 대해서 코드를 변경하는 경우, 확장 기능을 이용하는 모든 페이지가, 이론적으로는, 즉석에서 새로운 코드의 결과를 반영합니다.기술적으로는, 확장 기능을 포함한 페이지가 렌다 될 때마다 코드가 실행되는 것을 의미합니다.

실제로는, 페이지 캐싱 덕분에, 이것은 별로 들어맞지 않습니다.페이지 캐싱은 MediaWiki 소프트웨어, 브라우저, 혹은 중간의 대리, 파이어 월에 의해서 행해집니다.

MediaWiki의 퍼서 캐쉬를 회피하고, 새로운 버젼의 페이지가 생성되는 것을 보증하기 위해서는, 브라우저의 주소 바에 표시되고 있는 기사의 URL의 제일 뒤로"?action=purge"를 추가해 Enter 키를 눌러 페이지를 다시 읽기 합니다.이것에 의해서 페이지와 그것을 참조하는 모든 템플릿은 모든 캐쉬 데이터를 무시해 재생성됩니다.메인 페이지 자신이 수정되지 않는 경우는 퍼지 액션이 필요합니다만, 렌다 되어 울면 안 되는 방법법은 변경됩니다(확장 기능이 수정된, 혹은 수정된 템플릿을 참조했습니다).

페이지의 새로운 카피를 취득하기 위해서 이 방법이 충분하지 않은 경우, 통상은 상기의 URL의 말단에'&rand=somerandomtext'를 추가하는 것으로 중간 상태의 캐쉬를 회피할 수 있습니다.'somerandomtext'가 매회 다른 것을 확인해 주세요.

확장 기능을 이용해 캐싱을 무효로 하는 방법은?
MediaWiki 1.5이후에서는, 퍼서는 3번째의 파라미터로서 확장 기능에게 건네집니다.이 파서는 다음과 같은 캐쉬를 무효로 하기 위해서 사용됩니다:

사이트상에서의 모든 서바사이드캐싱을 무효로 하기 위해서, 다음의 코드를 LocalSettings.php에 추가해 주세요:

버젼 1.8이후
퍼서 훅 함수 parser 오브젝트에 참조로서 건네받아 wikitext를 해석하기 위해서 이것을 사용합니다.

Parser::recursiveTagParse</tt>가 버젼 1.8 전후로 도입되었습니다.이것을 사용하는 이점은 간결한 것(하나의 인수만을 취득해 하나의 문자열을 돌려줍니다)과$text</tt>로 확장 기능 태그를 해석하므로 확장 기능 태그를 네스트 할 수 있는 것입니다.

버젼 1.8 이전
버젼 1.8 이전으로는, 다음과 같은 별로 예쁘지 않은 방법을 사용하지 않으면 안됩니다:

Parser::parse에의 4번째와 5번째의 파라미터는$lineStart</tt>와$clearState</tt>입니다; 이것들은 퍼서가 거절하지 않든지 분을 지시합니다. $lineStart</tt>는, true의 경우, wiki 텍스트가 새로운 행으로 시작되는 것으로서 취급하도록(듯이) 지시합니다(블록, 만약 나무는 리스트등을 취급하는 경우에 사용합니다).$clearState</tt>, 는 true의 경우, 내부 상태의 정보를 클리어 하는; 많은 경우, 이것은 false가 됩니다.

상기의 예에 대하고,Parser::parse</tt>는 생의 HTML가 아니고, ParserOutput 오브젝트를 돌려주는 것에 주의해 주세요.

이것이 동작하지 않는경우(실행의 차례, 네스트, 다른 훅과의 혼합등이 자주 있는 원인), parser 오브젝트의 클론 카피를 사용해 주세요:

확장 기능과 템플릿
템플릿 파라미터는 확장 기능 태그 내부에서 사용되는 경우(예를 들면, "은 확장 기능에 직접 건네받고 템플릿이 불려 갔을 때에 지정된 올바른 값에 변환되지 않습니다.퍼서의 템플릿의 전에 확장 기능이 해석되기 때문입니다.더 상세한 정보와 이용 가능한 패치에 대해서는bug 2257을 봐 주세요.

이 문제의 차선책은 템플릿 변수를 확장하는 있어 퍼서 함수를 작성해 확장 기능 코드를 작성하는 것입니다. 템플릿 파라미터로 를 호출하기 위해서는, 다음과 같은 새로운 퍼서 함수를 작성합니다:

다음과 같은 페이지상에서 함수를 호출하는:

버젼 1.5이후
MediaWiki 1.5이후에서는, XML 스타일의 파라미터(태그 속성)가 서포트되고 있습니다.파라미터는 2번째의 파라미터로서 훅 기능에 연상 배열로서 건네받습니다.문자열의 값은 이미 디코드된 HTML 문자 엔티티를 가지므로, 그것들을 HTML에 되돌리는 경우, HTML 인젝션의 리스크를 피하기 위해서, 를 사용하는 것을 잊지 말아 주세요.

버젼 1.5 이전
MediaWiki 1.5는 파라미터와 확장 기능 태그의 사이에파라미터를 건네주지 않으면 안됩니다.즉, 옵션을 위해서 특별한 구문과 그러한 유익의 훅 입력 텍스트를 분석하지 않으면 안됩니다.가능한 구문의 하나는 다음과 같습니다:

@option1=foo @option2=bar

...content to be processed by the extension....

확장 기능 기능에 두고, 통상의 처리를 실행하기 전에@option1=foo</tt>와 같은 행을 찾습니다.다른 구문을 선택하는 일도 물론 자유롭습니다.

확장 기능의 HTML 출력의 수정을 피하는 방법은?
현재의 확장 기능 코드에서는 퍼서 훅 확장 기능이인 라인의 매테리얼을 생성해 그것들이 마지막 블록 레벨에 삽입되는 것을 전제로 하고 있습니다(Bugilla:8997참조).

이것에 착수하는 방법은 실제의 결과 대신에 마커를 출력하는 확장 기능의 퍼서 훅 함수를 작성해, 그 마커를 ParserAfterTidy훅을 위해서 누각에 오름 된 핸들러 함수의 실제의 결과로 옮겨놓는 것입니다.

다른 방법으로서는, 마커의 출력 대신에, 무장된 폼(예를 들면, Base64로 encode 된 것)에 결과를 출력하는 것으로, ParserAfterTidy 핸들러로 그것을 무장해제(디코드) 하는 것도 가능합니다.

Special:Version상에서 확장 기능을 표시하려면?
확장 기능을 MediaWiki의 Special:Version 페이지로 표시하기 위해서는, PHP 코드의 범위내에서 확장 기능 크레디트를 할당하지 않으면 안됩니다.

이것을 실시하기 위해서, 훅행 혹은 함수의 정의 전에$wgExtensionCredits변수를 최초의 실행 가능한 행의 코드로서 추가합니다

확장 기능 크레디트의 예는 다음과 같습니다:

'validextensionclass'를 다음 중 어떤 것이나 하나로 옮겨놓아 주세요:
 * 'specialpage' -- MediaWiki의 특별 페이지로의 추가하기 위해서 확보됩니다;
 * 'parserhook' -- 확장 기능이 수정되어 보완, 혹은 MediaWiki로 파서 함수에 옮겨놓는 경우에 사용됩니다;
 * 'variable' -- MediaWiki에 복수의 기능을 추가하는 확장 기능입니다;
 * 'other' -- 모든 다른 확장 기능입니다.

관련 항목

 * Manual:Extensions/ko
 * Extensions FAQ/ko
 * Category:Extensions/ko
 * Extension Matrix
 * $wgExtensionFunctions
 * Comparison of parser function and XML-style parser extension - refers to DynamicPageList2, but is of general interest
 * Project:Extension requests

-우케 케스시 누리관호오오 오누치세하타코 헤타코 오세히 타요치臭, 테하오□미아우 3 누미우사누 소타호 세니 터프-. 누하사단□쿠키호 사爻ぁ릿-주름□쿠키호슈에트 테요사嵯옐燦鏶ろ케마스헤세□르.

.쿠커鏶ぁ璿.세. .소확누 사후세니치贅ろ타요에트타후웨, 키나.케

쿠主슛맣【 오어□. 쿠主슛륫ㅋ네타호눔 웨에트 에 肖쏘케이 터프 테트치臭지세하에르누마에트 타마타사 세히세니트誕六. 쿠□테카嵯た읕ンク用세皮옴-. 에르세명무 헤타후 카 트치「스코키에이케후치臭◀４에 肖쏘케이 터프 아율거짓말.에트 세 阪ろ, 에와치케이케비·후 코르타코 누마에테타누 쿠主슛륫ㅘ아율거짓말.에트 타요타사 사모. 아라키크치臭웨키호슈에트 에肖쏘케이타사 사후타요에트 스테이 」타사 에와테누메 시 타요아카케소., 타후헤타코 세저」 아감로 케곽치소에엘. 세니에마..치카안 켄코케누마크소아체. 에肖쏘케이 터프 테트치臭지세하에르누마에트 타마소. 세 □이.타누케후.아. 에 멱와쵸 타요타사아□트 세히타요엘. 아라키크치臭웨타누 세□咫 아르코사타□호 코호코미타후 아라 누 臭뭅㈔말치크牌옴쿠 스헤에르사 爻ぁ릿㈇뗄시타요타서나소. 트誕쏵트케저오 오케세니소타 테요 스코키케누우타크키호 쿠사눔에르크켄타타 타 □시모오오 아, 시모타누 300 사변타후카嵯だ驕ソ에엘-. , ., . , . , . , . ,

182. 케크□트치나크트세세 2008우11소16 타마 02:49 치牌敲悟 에마오

183. 케크□트치나크트세세 2008우11소16 타마 14:42 쿠카타호우「쿄우라소·호. 에르크크 우라소·호에트 쿠커 귤나무 MAX 사嵯覺

184. 케크□트치나크트세세 2008우11소16 타마 17:27 세니트아케레사 .쿠아트□니.세니치1 테하웨 타요세□.케

185. 케크□트치나크트세세 2008우11소17 타마 00:00 치牌◀맛객㈔릿사총오 카嵯궐캬

186. 케크□트치나크트세세 2008우11소17 타마 11:39 .리 185 코□·. -阪ぐ旽매㈔⑶ AT누하오마. -.치臭지세하치 오섬.-·시 키케코타후 오누세케 臭⑶ 타마코사타누 타□□투-낙지 타충 에·케 템소헤 에르크세牌㉧ -阪づ걱읏테요에·호 사□사 아提㉵치, 오오타후

187. 케크□트치나크트세세 2008우11소17 타마 23:08 타□肖1500 타누 카嵯ゐニ키호치카트에와시牌譴 소.우하치臭珏民쿠키호 사□후 웃세니. 치臭瞼癬케르이□카케

188. 케크□트치나크트세세 2008우11소18 타마 01:30 아라킷코크크만,. , ., . , 치臭◐斫걷우우니토. 테요테하키호 사비·무 아잠 코」치臭珏-.카嵯뎨る, .쿠케소타타타호사