Building an Extension

시작하기

확장기능 마법사를 이용해서 웹으로 간단한 확장기능을 만들 수 있습니다.

MozillaZine Knowledge Base에는 확장기능 마법사를 이용해 만들 수 있는 것과 비슷한 Hello World 확장기능에 대해 한 줄 한 줄 설명한 다른 글도 있습니다.

소개

이 입문서는 여러분을 아주 간단한 확장기능(Firefox 브라우저에 텍스트 "Hello, World!"를 담고 있는 상태 표시줄 패널을 추가하는)을 만드는 데 필요한 과정 속으로 안내합니다.

주의 이 입문서는 Firefox 1.5 이상 버전의 확장기능 만들기에 관한 내용입니다. 이전 버전 Firefox용 확장기능 만들기를 다루는 입문서도 있습니다.

썬더버드용 확장기능을 만드는 방법에 대한 입문서는 Building a Thunderbird extension에서 보실 수 있습니다.

개발 환경 구축하기

확장기능은 파일 확장자가 xpi (“zippy”로 소리 냄)인 ZIP 파일이나 묶음(Bundles)으로 배포됩니다.

XPI 파일 안 구조의 예 :

extension.xpi:
              /install.rdf                   
              /components/*  
              /components/cmdline.js                   
              /defaults/
              /defaults/preferences/*.js     
              /plugins/*                        
              /chrome.manifest                
              /chrome/icons/default/*       
              /chrome/
              /chrome/content/

이 글에서도 위와 비슷한 파일 구조를 만들 것입니다. 그러면 이제 하드디스크 어디든지(예컨대, C:\extensions\myExtension\이나 ~/extensions/my_extension/) 확장기능을 위한 폴더를 만들고, 이 폴더 안에 chrome 폴더를 만들고, chrome 폴더 안에 content 폴더를 만드세요.

확장기능 폴더 루트 안에, chrome 폴더와 나란히, 빈 텍스트 파일 두 개를 새로 만드세요. 하나는 chrome.manifest 그리고 다른 하나는 install.rdf입니다. 그리고, chrome/content 폴더 안에 sample.xul이라는 빈 텍스트 파일을 하나 만드세요.

만들어진 폴더 구조 :

<ext path>\
          install.rdf
          chrome.manifest
          chrome\
              content\
                  sample.xul

Install Manifest 만들기

확장기능 폴더 계층(hierarchy) 상단에 여러분이 만든 install.rdf 파일을 열어 안에 다음을 써넣으세요.

<?xml version="1.0"?>

<RDF xmlns="https://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:em="https://www.mozilla.org/2004/em-rdf#">

  <Description about="urn:mozilla:install-manifest">
    <em:id>[email protected]</em:id>
    <em:version>1.0</em:version>
    <em:type>2</em:type>
   
    <!-- Target Application this extension can install into, 
         with minimum and maximum supported versions. --> 
    <em:targetApplication>
      <Description>
        <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
        <em:minVersion>1.5+</em:minVersion>
        <em:maxVersion>2.0.0.*</em:maxVersion>
      </Description>
    </em:targetApplication>
   
    <!-- Front End MetaData -->
    <em:name>Sample!</em:name>
    <em:description>A test extension</em:description>
    <em:creator>Your Name Here</em:creator>
    <em:homepageURL>https://www.foo.com/</em:homepageURL>
  </Description>      
</RDF>

[email protected] - 확장기능 ID. 이는 email 주소 형식(여러분의 email이 아니어야 함을 주의하세요)으로 확장기능을 식별하는 여러분이 짠 어떤 값입니다. 유일하게 만드세요. GUID를 쓸 수도 있습니다.
<em:type>2</em:type>로 지정 -- 2는 확장기능을 설치함을 선언합니다. 테마를 설치하는 경우에는 4입니다(다른 형 코드는 Install Manifests#type를 보세요).
{ec8030f7-c20a-464f-9b0e-13a3a9e97384} - Firefox 응용프로그램 ID.
1.5 - 이 확장기능이 작동하는 Firefox의 최소(minimum)판. 이를 여러분이 시험하고 버그를 고치려는 최소판으로 설정하세요.
2.0.0.* - 이 확장기능이 작동하는 Firefox의 최대(maximum)판. 현재 이용가능한 최신판보다 더 최신판으로 설정하지 마세요! 위 경우에, "2.0.0.*"은 확장기능이 Firefox 2.0.0.0에서 2.0.0.x 판까지 작동함을 나타냅니다.

최신 Firefox 1.5.0.x에서 작동하도록 디자인된 확장기능은 최대판을 "1.5.0.*"로 설정해야 합니다. 완전한 필수와 선택 프로퍼티 목록은 Install Manifests를 보세요.

파일을 저장하세요.

XUL로 브라우저 확장하기

Firefox의 사용자 인터페이스는 XUL과 JavaScript로 작성됩니다. XUL은 button, menu, toolbar, tree 등과 같은 사용자 인터페이스 위젯을 제공하는 XML 문법입니다. 사용자 동작은 JavaScript로 작동됩니다.

브라우저를 확장하기 위해, 우리는 위젯을 추가하거나 수정하여 브라우저의 UI 부분을 수정합니다. 브라우저 창에 새 XUL DOM 요소를 삽입하여 위젯을 추가하고 스크립트 쓰고 이벤트 처리기(handler)를 붙여 위젯을 수정합니다.

브라우저는 browser.xul($FIREFOX_INSTALL_DIR/chrome/browser.jar가 content/browser/browser.xul를 포함합니다)로 구현됩니다. browser.xul에서 아래처럼 보이는 상태 표시줄을 찾을 수 있습니다.

<statusbar id="status-bar">
 ... <statusbarpanel>s ...
</statusbar>

<statusbar id="status-bar">는 XUL Overlay를 위한 "병합점(merge point)"입니다.

XUL Overlay

XUL Overlays는 실행 시간(run time)에 XUL 문서에 다른 UI 위젯을 붙이는 한 가지 방법입니다. XUL Overlay는 "주(master)" 문서 안에서 특정 병합점에 삽입되는 XUL 조각(fragment)을 지정하는 .xul 파일입니다. 이 조각은 삽입, 제거, 수정되는 위젯을 지정하기도 합니다.

XUL Overlay 문서 예

<?xml version="1.0"?>
<overlay id="sample" 
         xmlns="https://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
 <statusbar id="status-bar">
  <statusbarpanel id="my-panel" label="Hello, World"/>
 </statusbar>
</overlay>

status-bar로 불리는 <statusbar>는 우리가 붙쳤으면 하는 브라우저 창 안 "병합점"을 지정합니다.

<statusbarpanel> 자식은 병합점 안에서 삽입하고 싶은 새 위젯입니다.

위에 있는 이 sample 코드를 취해 여러분이 만든 chrome/content 폴더 안에 sample.xul 파일로 저장하세요.

위젯 병합과 Overlay를 쓴 사용자 인터페이스 수정에 관한 더 많은 정보는, 아래를 보세요.

Chrome URI

XUL 파일은 "Chrome Packages"(chrome:// URI를 거쳐 로드되는 사용자 인터페이스 컴포넌트 묶음)의 부분입니다. file:// URI(시스템 위에서 Firefox 위치가 플랫폼과 시스템마다 바뀌기도 하기 때문에)를 써서 디스크에서 브라우저로 로드하기보다는, Mozilla 개발자들은 설치된 응용프로그램이 알고 있는 XUL content에 이르는 URI를 만드는 해결책을 냈습니다.

브라우저 창은 chrome://browser/content/browser.xul입니다. Firefox의 location bar에 이 URL을 쳐 보세요!

Chrome URI는 여러 컴포넌트로 구성되어 있습니다.

첫째로, URI scheme (chrome)은 Firefox 네트워킹 라이브러리에 이것이 Chrome URI임을 알립니다. URI content가 (chrome)으로 처리되어야 함을 나타냅니다. Firefox가 URI를 웹 페이지로 다루도록 하는 (chrome)과 (http)를 비교하세요.
둘째로, 패키지 이름(위 예에서는, browser)은 사용자 인터페이스 컴포넌트 묶음을 식별합니다. 이는 확장기능 사이의 충돌을 피하기 위해 가능하면 응용프로그램에 유일하면 좋습니다.
셋째로, 요청되는 데이터 형. 세 가지 형이 있습니다. content (응용프로그램 UI의 구조(structure)와 behavior를 구성하는 XUL, JavaScript, XBL 바인딩 등.), locale (UI의 지역화를 위한 문자열을 담고 있는 DTD, .properties 파일 등), skin(UI의 테마를 구성하는 CSS와 이미지)
끝으로, 로드하는 파일의 경로.

그러므로, chrome://foo/skin/bar.png는 foo 테마의 skin section에서 bar.png 파일을 로드합니다.

Chrome URI를 써서 content를 로드할 때, Firefox는 이 URI를 디스크(나 JAR 패키지)의 실제 원본 파일로 번역하기 위해 Chrome 레지스트리를 씁니다.

Chrome Manifest 만들기

Chrome Manifest와 지원하는 프로퍼티에 관한 더 많은 정보는, Chrome Manifest 참고 문서를 보세요.

확장기능 원본 폴더 계층의 루트에 chrome 디렉토리와 나란히 만든 chrome.manifest 파일을 여세요.

이 코드를 추가하세요.

content     sample    chrome/content/

(끝에 "/"를 잊지 마세요! 빠트리면, 확장기능이 로드되지 않습니다.)

주의: Firefox/Thunderbird 1.5가 mixed/camel case를 지원하지 않기 때문에 패키지 이름("sample")에 모두 소문자를 씀을 확인하세요. 2.0과 이전버전에서 대소문자를 섞어쓰는 기능을 지원하지 않습니다. bug 132183

이는 다음을 지정합니다.

chrome 패키지 안에 material 형
chrome 패키지 이름
chrome 패키지 파일의 위치

그래서, 이 줄은 chrome 패키지 sample의 경우, chrome.manifest 위치와 상대 경로인 chrome/content 위치에서 우리가 패키지의 content 파일을 찾을 수 있음을 말합니다.

content, locale, skin 파일은 여러분의 chrome 하위디렉토리 안 content, locale, skin 폴더 안에 놓여야 함을 주의하세요.

파일을 저장하세요. 여러분의 확장기능이 깔린 Firefox를 띄우면, (이 입문서에서 뒤에), 이 줄이 chrome 패키지를 등록합니다.

Overlay 등록

브라우저를 표시할 때마다 Firefox가 여러분의 overlay를 브라우저 창에 병합할 필요가 있습니다. 그래서 chrome.manifest 파일에 이 줄을 추가하세요:

overlay chrome://browser/content/browser.xul chrome://sample/content/sample.xul

이 줄은 Firefox에게 browser.xul을 로드할 때 browser.xul 안에 sample.xul을 병합하도록 합니다.

시험

먼저, 우리는 Firefox에 확장기능 정보 알림이 필요합니다. 예전 좋지 않은 Firefox 1.0 때는 이는 확장기능을 XPI로 패키징하고 그것을 사용자 인터페이스를 거쳐 설치함을 뜻합니다. 그것은 실로 고통이었습니다. 이제는, 훨씬 더 간단합니다.

Profile 폴더를 여세요.
extensions 폴더를 여세요(없으면 만드세요).
새 텍스트 파일을 만들어, 그 안에 extension 폴더(예컨대, C:\extensions\myExtension\이나 ~/extensions/myExtension)를 써넣으세요. 확장기능 id를 이름(예컨대, [email protected])으로 갖는 파일로 저장하세요.

이제 확장기능을 시험할 준비가 됐습니다!

Firefox를 시작하세요. Firefox가 확장기능 디렉토리 텍스트 링크를 감지하고 확장기능을 설치합니다. 브라우저 창이 보이면 여러분은 상태 표시줄 패널의 오른쪽에 텍스트 "Hello, World!"를 봅니다.

이제 돌아가서 .xul 파일에 변화를 주고, Firefox를 닫고 재시작하면 그 변화가 보입니다. These don't actually match the described extension and confuse people. -Nickolay CENTER> Image:Helloworld_tools_menu.PNG Image:Helloworld_extensions_wnd.PNG </CENTER

Package

이제 여러분의 확장기능이 동작하므로, 배치(deployment)와 설치를 위해 그것을 패키지할 수 있습니다.

여러분의 확장기능 폴더 내용들을 Zip 파일로 압축하고 (확장기능 폴더 자체가 아닙니다.) zip 파일 확장자를 .xpi 로 바꾸세요. Windows XP에서는, 여러분의 확장기능 폴더 안 모든 파일과 하위폴더를 고르고 오른쪽 버튼을 누른 뒤 "보내기 -> Compressed (Zipped) Folder"를 골라 이를 쉽게 할 수 있습니다. .zip 파일은 여러분을 위해 만듭니다. 바로 이름을 바꾸면 끝납니다!

Mac OS X에서는, 확장기능 폴더의 내용들 위에서 오른쪽 버튼을 누른 뒤 zip 파일로 만들기 위해 "Create Archive of..."를 고를 수 있습니다. 그러나, Mac OS X가 파일 metadata를 추적(track)할 목적으로 숨김 파일을 폴더에 추가하기 때문에, 터미널을 쓰고 숨김 파일(의 이름은 마침표로 시작합니다)을 지워야 합니다. 그리고 나서 zip 파일을 만들기 위해 명령줄에서 zip 명령을 쓰세요.

Linux에서도, 역시 명령줄 Zip 도구를 씁니다.

혹시 여러분이 'Extension Builder' 확장기능을 설치했으면 여러분을 위해 .xpi 파일을 compile할 수 있습니다(도구 -> Extension Developer -> Extension Builder). 단지 여러분의 확장기능(install.rdf 등)이 있는 디렉토리를 탐색하고 Build Extension button을 누르세요. 이 확장기능에 개발을 더 쉽게 하는 많은 도구가 있습니다.

이제 여러분의 서버에 .xpi 파일을 올려주고(upload), application/x-xpinstall로 다뤄지는지 확인하세요. 여러분은 그 파일에 링크할 수 있고 사람들이 내려받고(download) Firefox에 설치하게 할 수 있습니다. .xpi 파일을 시험할 목적으로 우리는 단지 Tools -> Extensions이나 Add-Ons -> Extensions in FireFox 2을 거쳐 확장기능 창 안에 그것을 끌어다 놓을 수 있습니다.

addons.mozilla.org 이용하기

Mozilla Update는 공짜로 확장기능을 host할 수 있는 배포 사이트입니다. 여러분의 확장기능은 비록 매우 유명해지더라도 내려받기를 보장하는 Mozilla의 mirror 네트워크에 host됩니다. Mozilla 사이트는 또한 사용자에게 더 쉬운 설치를 제공하고 여러분이 새 버전을 올려주면 기존 버전 사용자들이 자동으로 이용할 수 있게 합니다. 게다가 Mozilla Update는 사용자들이 여러분의 확장기능에 평(comment)을 하고 feedback을 제공하게 합니다. 여러분이 확장기능을 배포하는 데 Mozilla Update 사용을 강력히 권고합니다!

https://addons.mozilla.org/developers/ 에 방문하여 계정을 만든 뒤 확장기능 배포를 시작하세요!

주의: 여러분의 확장기능은 좋은 설명과 확장기능 실행 스크린샷(screenshot)이 있으면 더 빨리 퍼지고 더 많이 내려받습니다.

Windows 레지스트리에 확장기능 등록하기

Windows에서, 확장기능 정보는 레지스트리에 추가될 수 있고 확장기능은 응용프로그램이 시작하는 다음 번에는 자동으로 pick up됩니다. 이는 응용프로그램 설치프로그램이 쉽게 integration hook을 확장기능에 추가하게 합니다. 더 많은 정보는 Windows 레지스트리를 써서 확장기능 추가하기를 보세요.

XUL Overlay 더 많은 정보

병합점에 UI 위젯 추가 외에 또, Overlay 안에 XUL 조각을 다음에 쓸 수 있습니다.

병합점에 있는 속성 수정, 예컨대 <statusbar id="status-bar" hidden="true"/> (status bar 숨김)
주 문서에서 병합점 제거, 예컨대 <statusbar id="status-bar" removeelement="true"/>
삽입되는 위젯의 자리 제어:

<statusbarpanel position="1" .../>

<statusbarpanel insertbefore="other-id" .../>

<statusbarpanel insertafter="other-id" .../>

새로운 사용자 인터페이스 컴포넌트 만들기

여러분은 UI 위젯을 조작하는 DOM 메소드를 써서 .js 파일에서 사용자 동작을 구현하여 기능(functionality)을 제공하는 분할한 .xul 파일로 여러분의 창과 대화상자를 만들 수 있습니다. 이미지 붙임, 색 설정 등을 하기 위해 .css 파일에서 스타일 규칙을 쓸 수 있습니다.

XUL 개발자를 위한 더 많은 자원(resource)은 XUL 문서를 보세요.

Defaults File

Defaults file은 여러분의 확장기능 폴더 계층의 루트 아래 defaults/에 놓일 사용자 profile을 뿌리는(seed) 데 씁니다. defaults/preferences/에 저장될 Default preferences .js file - .js 파일을 여기에 놓으면 시작할 때 Firefox preferences system에 의해 자동으로 로드되어 Preferences API를 써서 파일에 접근할 수 있습니다.

XPCOM 컴포넌트

Firefox는 확장기능에 XPCOM 컴포넌트를 지원합니다. 여러분은 JavaScript나 C++(Gecko SDK를 써서)로 쉽게 자신만의 컴포넌트를 만들 수 있습니다.

components/ 디렉토리에 모든 .js나 .dll 파일을 두세요 - 여러분의 확장기능이 설치된 뒤 Firefox가 도는 첫 번에 자동으로 등록됩니다.

더 많은 정보는 JavaScript로 XPCOM 컴포넌트 빌드하는 법과 책 XPCOM 컴포넌트 만들기를 보세요.

응용프로그램 명령줄

사용자 정의(custom) XPCOM 컴포넌트의 가능한 쓰임 가운데 하나는 Firefox 나 Thunderbird 에 명령줄 처리기 추가입니다. 여러분은 확장기능을 응용프로그램으로 실행하는 데 이 기술을 쓸 수 있습니다.

 firefox.exe -myapp

I should move the useful parts of this to the Command Line page. -Nickolay This is done by adding a component containing the function... function NSGetModule(comMgr, fileSpec) { return myAppHandlerModule; } 이 함수는 firefox가 시작할 때마다 firefox가 실행합니다. Firefox registers the myAppHandlerModule's by calling its 'registerSelf()'. Then it obtains the myAppHandlerModule's handler factory via 'getClassObject()'. The handler factory is then used to create the handle using its 'createInstance(). Finally, the handle's 'handle(cmdline)' processes the command line cmdline's handleFlagWithParam() and handleFlag(). 상세한 내용은 Chrome: Command Line과 forum discussion을 보세요.

지역화

하나 이상의 언어를 지원하려면, entities와 string bundles을 써서 content에서 문자열을 분리해야 합니다. 돌아와서 나중에 하기보다는 확장기능을 개발하면서 하면 훨씬 더 쉽습니다!

지역화 정보는 그 확장기능을 위한 locale 디렉토리에 저장됩니다. 예를 들어, sample 확장기능에 locale을 추가하려면, chrome 디렉토리("content" 디렉토리가 위치한)에 "locale"로 이름 붙인 디렉토리를 만들고 chrome.manifest 파일에 다음 줄을 추가하세요:

locale sample sampleLocale chrome/locale/

XUL로 localizable 속성값을 만들려면, .ent(나 .dtd) 파일에 그 값을 써넣으세요, 속성값은 locale 디렉토리에 놓이고 이와 같이 보입니다.

<!ENTITY  button.label     "Click Me!">
<!ENTITY  button.accesskey "C">

그리고 나서 XUL 문서 상단(하지만 "<?xml version"1.0"?>" 아래)에 이렇게 포함(include)하세요.

<!DOCTYPE window SYSTEM "chrome://packagename/locale/filename.ent">

window는 XUL 문서 루트 요소의 localName값이고 SYSTEM 프로퍼티 값은 엔티티(entity) 파일의 chrome URI입니다. sample 확장기능에서, 루트 요소는 overlay입니다.

그 엔티티를 쓰려면, XUL을 이렇게 보이도록 수정하세요.

<button label="&button.label;" accesskey="&button.accesskey;"/>

Chrome Registry가 선택한 locale과 대응하는 지역화 묶음에서 로드된 엔티티 파일인지 확인합니다.

스크립트에서 쓴 문자열은, 이 형식으로 각 줄에 문자열이 있는 .properties 파일, 텍스트 파일을 만드세요.

key=value

그리고 나서 스크립트에 그 값을 로드하기 위해 nsIStringBundleService/nsIStringBundle이나 <stringbundle> tag을 쓰세요.

브라우저 이해하기

브라우저 창이나 여러분이 확장하길 원하는 어떤 다른 XUL 창을 검사하려면 DOM Inspector (Standard Firefox 설치 부분이 아님, browser의 Tools(도구) 메뉴에 "DOM Inspector" 항목이 없으면 사용자 정의 설치 경로로 재설치하고 Developer Tools를 골라야 합니다)를 쓰세요.

노드를 선택하기 위해 XUL 창의 노드를 눈에 보이게 클릭하려면 DOM Inspector toolbar 좌상단에 있는 point-and-click 노드 finder button을 쓰세요. 이렇게 하면 DOM inspector의 DOM 계층 tree view는 여러분이 클릭하는 노드로 건너뜁니다.

overlay에서 여러분의 요소를 삽입하는 데 쓸 수 있는 id 붙은 병합점을 발견하려면 DOM Inspector의 오른쪽 패널을 쓰세요. 병합할 수 있는 id 붙은 요소를 발견할 수 없으면, overlay에 스크립트 붙임과 load 이벤트가 주 XUL 창 위에 발생할 때 요소 삽입이 필요할 지도 모릅니다.

확장기능 디버그하기

디버깅을 위한 분석 도구

DOM Inspector - 속성, DOM 구조, CSS 스타일 규칙을 검사(예컨대 왜 여러분의 스타일 규칙이 요소에서 작동하지 않는지 찾아냄 - 매우 귀중한 도구!)
Venkman - JavaScript에서 중단점(breakpoint)을 설정하고 호출 스택(call stack) 검사
JavaScript의 arguments.callee.caller - 함수의 호출 스택 접근

printf 디버깅

명령줄에서 -console을 붙여 Firefox 실행하고 dump("string") 사용(상세한 내용은 링크를 보세요)
JavaScript 콘솔에 log하기 위해 nsIConsoleService 사용

고급 디버깅

디버그 Firefox 빌드를 실행하고 Firefox 자체나 여러분의 C++ 컴포넌트에 중단점 설정. 숙련된 개발자에게, 이는 대부분 문제를 진단(diagnose)하는 가장 빠른 방법입니다. 더 많은 정보는 Build Documentation와 Mozilla 개발하기를 보세요.
더 도움이 되는 팁은 XULRunner 응용프로그램 디버그하기를 보세요.

빠른 시작

여러분은 작동하는 단순 확장기능을 만드는 데 Extension Wizard 온라인 도구를 쓸 수 있습니다.

Extension Wizard로 만들 수 있는 것과 비슷한 Hello World 확장기능은 MozillaZine Knowledge Base의 다른 입문서에서 한 줄 한 줄 설명합니다.