Bootstrapped extensions

노트: 부가기능 SDK 를 사용한 모든 확장기능은 부트스트랩입니다! 모든 부트스트랩 코드는 생성되었으므로 따로 고민할 필요 없습니다. 부가기능 SDK를 사용하지 않으셨나요? 계속 읽어주세요...

전통적인 확장기능은 오버레이를 포함하고 있습니다. 오버레이는 확장기능 패키지에서 XUL 파일을 꺼내 자동으로 UI 위에 덧씌웁니다. 이 방식을 쓰면 UI에 무언가 더하는 확장기능을 만들기 쉬워지지만 업데이트, 설치, 사용불가를 할 때마다 파이어폭스를 다시 시작해야 합니다.

Gecko 2.0(Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)은 부트스트랩 확장기능을 소개합니다. 이것은 오버레이 대신 직접 파이어폭스로 삽입되게 프로그램밍된 확장기능입니다. 확장기능 안에 포함된 어떤 스크립트 파일이 브라우저가 이 확장기능을 설치, 제거, 실행, 종료할 수 있게 해 줍니다.

파이어폭스가 하는 일은 스크립트 파일에 따라 호출하는 것 뿐입니다. UI의 추가, 제거, 설치, 종료 등은 모두 확장기능이 알아서 합니다.

이 문서는 어떻게 부트스트랩 확장기능이 작동하는지 알려줍니다. 오버레이 확장기능을 부트스트랩으로 바꾸려면 converting from an overlay extension to restartless 이 문서를 확인하세요.

시작과 종료 프로세스

부트스트랩 확장기능의 가장 중요한 점은 필요에 따라 파이어폭스가 마음대로 켜고 끌 수 있어야 한다는 점입니다. 확장기능의 startup() 함수가 호출되면 UI와 다른 기능들이 수동으로 실행되어야 합니다. 마찬가지로 shutdown() 함수가 호출되면 파이어폭스에 추가한 것과 그것의 오브젝트의 모든 리퍼런스를 제거해야 합니다.

startup() 함수가 호출될 때의 예:

파이어폭스와의 호환과 활성화가 되어 있을 경우 확장기능이 설치 되었을 때
부가 기능 관리자 창으로 확장기능이 활성화 되었을 때
확장기능이 활성화 되어있고 호환 가능할 경우 파이어폭스가 실행되었을 때

shutdown() 함수가 호출될 때의 예:

확장기능이 활성화된 상태로 제거되었을 때
확장기능이 비활성화 되었을 때
확장기능이 활성화 되어있을 경우 사용자가 파이어폭스를 껐을 때

파이어폭스 UI를 변경할 때

부트스트랩 부가기능의 chrome.manifest

다으의 경우에서 부트스트랩 부가기능의 chrome.manifest 을 사용할 수 있습니다:

부가기능을 chrome:// URL로 켤 때 (매니페스트에서 content, locale, 그리고 skin 인스트럭션을 사용하세요);
이미 있는 chrome:// URI 를 교체할 때 (override 인스트럭션을 사용하세요).

부트스트랩 부가기능에서 모든 chrome.manifest 인스트럭션이 지원되는 것은 아닙니다. 예를 들어 XUL Overlays 는 부트스트랩 부가기능에서 사용할 수 없습니다. 더 자세한 내용은 chrome.manifest 문서를 참고하세요.

파이어폭스 10 이후 버전에서 부가기능의 xpi 파일의 최상단(install.rdf 등과 같은 위치)에 위치해 있는 chrome.manifest 파일은 자동으로 열립니다. 파이어폭스 8과 9에서 당신은 직접 nsIComponentManager.addBootstrappedManifestLocation() 과 nsIComponentManager.removeBootstrappedManifestLocation()를 통해 매니페스트 파일을 열고 닫아야 합니다. 이 기능은 파이어폭스 8 이전 버전에서는 지원되지 않습니다.

UI를 수동으로 추가하기

만약 파이어폭스의 UI를 바꾸는 부트스트랩 확장기능을 개발하기로 했다면 여기 몇가지 제안사항이 있습니다.

우선 document.getElementById()를 호출해서 바꾸고자 하는 UI 엘리먼츠를 ID로 찾아야 합니다. 그 다음 UI를 추가하기 위한 조작을 합니다. 예를 들어 파이어폭스의 메뉴바에 접근하기 위해서 이렇게 합니다. document.getElementById("main-menubar").

종료할 대마다 추가한 모든 UI를 제거해야 합니다.

부트스트랩 확장기능 만들기

확장기능이 부트스트랩이라는 것을 표시하기 위해 install manifest 에 다음 줄을 추가하세요:

<em:bootstrap>true</em:bootstrap>

그 다음 필요한 기능들이 담긴 bootstrap.js 파일을 추가합니다; 이것은 확장기능 패키지에서 install.rdf 파일과 같이 있어야 합니다.

Backward compatibility이전버전과의 호환

오래된 버전의 파이어폭스는 bootstrap 속성이나 bootstrap.js 파일을 인식하지 못하기 때문에 부트스트랩 확장기능과 전통적인 확장기능이 모두 담긴 XPI 파일을 만드는 것은 어려운 일이 아닙니다. 확장기능을 부트스트랩으로 만든 다음 오버레이를 추가하세요. 새 버전의 파이어폭스는 bootstrap.js 스크립트를 사용하면서 컴포넌트와 오버레이를 무시할 것이고 오래된 버전은 오버레이를 사용할 것입니다.

부트스트랩 진입점

bootstrap.js 스크립트는 브라우저가 확장기능을 관리할 때 호출하는 특정 함수들을 포함하고 있어야 합니다. 스크립트는 특정 샌드박스에서 실행되며 샌드박스는 확장기능이 종료되기 전까지 캐시로 남아있습니다.

startup

확장기능을 시작할 때 호출됩니다. 파이어폭스가 켜질 때, 비활성화된 확장기능이 활성화될 때 또는 업데이트를 설치하기 위해 종료되었을 때 같은 상황에서 호출됩니다. 이처럼 파이어폭스의 생명주기동안 여러번 호출될 수 있습니다.

이 함수가 호출되었을 때 부가기능은 UI를 추가하고 동작에 필요한 작업을 시작해야 합니다.

void startup(
  data,
  reason
);

변수

data: A bootstrap data structure.
reason: reason constants 중의 하나로 왜 확장기능이 시작되었는지를 표시합니다. APP_STARTUP, ADDON_ENABLE, ADDON_INSTALL, ADDON_UPGRADE, 또는 ADDON_DOWNGRADE 중의 하나가 됩니다.

shutdown

파이어폭스가 꺼질때, 확장기능이 업그레이드되거나 비활성화 될 때 처럼 확장기능이 종료할 때 호출됩니다. 추가된 UI를 제거하고 태스크는 종료하고 오브젝트는 처리해야 합니다.

void shutdown(
  data,
  reason
);

변수

data: A bootstrap data structure.
reason: reason constants 중의 하나로 왜 확장기능이 종료되었는지를 표시합니다. APP_SHUTDOWN, ADDON_DISABLE, ADDON_UNINSTALL, ADDON_UPGRADE, 또는 ADDON_DOWNGRADE 중의 하나가 됩니다.

install

부트스트랩 스크립트는 확장기능이 설치, 업그레이드, 다운그레이드 되고 나서 첫번째로 startup() 함수를 호출하기 전에 호출할 install() 함수를 포함해야 합니다.

노트: 이 메소드는 확장기능이 실행되지 않으면 호출되지 않습니다; 예를 들어 확장기능이 설치되었지만 파이어폭스의 현재 버전과 호환되지 않으면 install() 함수는 확장기능이 제거되기 전까지 호환성 문제를 해결하지 않는 이상 호출되지 않습니다. 그러나 만약 확장기능이 파이어폭스에 호환되도록 업그레이드된다면 install() 함수는 그때 startup() 함수가 호출되기 전에 호출될 것입니다.

void install(
  data,
  reason
);

변수

data: A bootstrap data structure.
reason: reason constants의 하나로 왜 확장기능이 설치되었는지 표시힙니다. ADDON_INSTALL, ADDON_UPGRADE, or ADDON_DOWNGRADE중 하나가 됩니다.

uninstall

이 함수는 마지막으로 shutdown() 함수가 호출되었을 때 이후 특정 버전의 확장기능이 제거되었을 때 호출됩니다. install() 이 호출되지 않았다면 이 함수는 호출되지 않습니다.

노트: uninstall() 함수는 확장기능이 비활성화 되어있거나 현재 파이어폭스와 버전이 맞지 않더라도 호출될 수 있다는 것을 기억해야 합니다. 그렇기 때문에 현재 파이어폭스에서 지원되지 않는 API들을 우아하게 다루는 것이 중요합니다. 또한 이 함수는 파이어폭스가 실행되지 않을 때 써드파티 애플리케이션이 확장기능을 제거했을 때는 호출되지 않습니다. uninstall 코드가 있는데 실행이 안될 때install() {} 만 있는것은 충분하지 않습니다. install 함수에서 몇몇 코드를 실행하던지, 최소한 install function에 이런 식으로 선언해야 합니다: function install(aData, aReason) {} 그러면 uninstall 코드가 실행될 것입니다.

노트: 부가 기능 관리자에서 부가기능의 "제거"를 클릭할 경우는 바로 uninstall 함수를 호출하진 않습니다. 왜냐하면 "취소"버튼이 있기 때문입니다. 부가기능 관리자를 닫거나 해서 "취소" 버튼이 사라지면 그때 호출됩니다.

노트: uninstall 함수는 업그레이드와 다운그레이드 시에도 호출되기 때문에 다음과 같이 표시해주어야 합니다:
function uninstall(aData, aReason) {
     if (aReason == ADDON_UNINSTALL) {
          console.log('really uninstalling');
     } else {
          console.log('not a permanent uninstall, likely an upgrade or downgrade');
     }
}

void uninstall(
  data,
  reason
);

변수

data: A bootstrap data structure.
reason: reason constants의 하나로 왜 확장기능이 제거되었는지 표시해줍니다. ADDON_UNINSTALL, ADDON_UPGRADE, 또는 ADDON_DOWNGRADE 중의 하나가 됩니다.

Reason 상수

부트스트랩의 함수는 reason 변수를 허용합니다. 이는 확장기능에게 왜 호출되었는지를 설명합니다. reason 상수는 다음과 같습니다:

상수	값	설명
`APP_STARTUP`	1	파이어폭스가 실행
`APP_SHUTDOWN`	2	파이어폭스가 종료
`ADDON_ENABLE`	3	부가기능이 활성화
`ADDON_DISABLE`	4	부가기능이 비활성화 (혹은 제거중 호출됨)
`ADDON_INSTALL`	5	부가기능이 설치됨
`ADDON_UNINSTALL`	6	부가기능이 제거됨
`ADDON_UPGRADE`	7	부가기능이 업그레이드됨
`ADDON_DOWNGRADE`	8	부가기능이 다운그레이드됨

Bootstrap data

각각의 진입점들은 부가기능의 유용한 정보를 담고 있는 간단한 데이터 구조를 갖고 있습니다. 부가기능에 대한 더 많은 정보는 AddonManager.getAddonByID()를 호출하는 것으로 알 수 있습니다. 그 데이터는 다음과 같은 속성을 갖고있는 간단한 자바스크립트 오브젝트입니다:

속성	자료형	설명
`id`	`string`	부가기능의 ID
`version`	`string`	부가기능의 버전
`installPath`	`nsIFile`	부가기능이 설치된 장소. 부가기능이 언팩되어있는지 여부에 따라 디렉터리가 될 수도 있고 XPI 파일이 될 수도 있습니다.
`resourceURI`	`nsIURI`	부가기능의 루트를 가리키는 URI. 부가기능이 언팩되어있는지 여부에 따라 `jar:` 이 될 수도 있고 `file:` URI 이 될 수도 있습니다.
`oldVersion`	`string`	과거 설치된 버전, reason이 `ADDON_UPGRADE` 이거나 `ADDON_DOWNGRADE이고 함수가` `install` 이나 `startup일 경우`.
`newVersion`	`string`	설치될 버전. reason이 `ADDON_UPGRADE` 이나 `ADDON_DOWNGRADE이고 함수가` is `shutdown` 이나 `uninstall일 경우`.

노트: startup 함수의 reason이 APP_STARTUP이고 oldVersion 속성이 설정되어있지 않으면 부가기능은 파이어폭스가 시작될 때 업그레이드/다운그레이드 될 수 있습니다. 또한 어떤 상황에서는 uninstall 함수가 호출되지 않고도 업그레이드/다운그레이드가 일어난다는 것을 주의하세요.

부가 기능 디버거

파이어폭스 31부터 부트스트랩 부가 기능을 디버깅하기 위해서 부가 기능 디버거를 사용할 수 있습니다.

현지화 (L10n)

부트스트랩 부가기능을 현지화하는 것은 chrome.manifest 호환성이 정착된 파이어폭스 7 이후로 거의 같습니다.

JS와 JSM 파일 - 속성 파일 사용하기

.js와 .jsm 파일을 현지화하기 위해서 속성 파일을 사용해야 합니다.

필요한 최소한의 것들은:

파일: install.rdf
파일: chrome.manifest
파일: bootstrap.js
폴더: locale
1. 폴더: VALID_LOCALE_HERE
  1. 파일: ANYTHING.properties

locale 폴더 안에 지원할 각각의 언어를 위한 폴더들이 있어야 합니다; 각각의 폭더는 유효한 로케일의 이름이어야 합니다(예: en-US). 폴더 안에는 속성파일이 들어있어야 합니다. chrome.manifest 파일 안에는 이런 로케일들이 정의되어야 합니다. 예를 들어 locale 폴더 안에 en-US 폴더가 들어있을 경우 chrome.manifest 파일에는 다음 줄이 추가되어야 합니다: locale NAME_OF_YOUR_ADDON en-US locale/en-US/

여기 예가 있습니다: GitHub :: l10n-properties - 이 부가기능을 실행하면 프롬프트에 USA나 Great Britain중 당신의 로케일에 가까운 쪽이 뜰 것입니다. about:config에서 general.useragent.locale을 en-US로 바군 뒤 en-GB로 설정하고 부가기능을 비활성화 한 뒤에 활성화하면서 다른 로케일을 시험해볼 수 있습니다.

XUL과 HTML 파일 - Using Entities from DTD Files

HTML파일은 흔히 사용되지만 DTD을 사용해 번역할 수 없습니다. 변경해야 하는 것이 세가지가 있습니다:

HTML 파일의 확장자를 .xhtml로 변경합니다
doctype에서 locale 폴더 속의 DTD 파일의 위치가 이런 식으로 정의되어야 합니다: <!DOCTYPE html SYSTEM "chrome://l10n/locale/mozilla.dtd">
html 태그에 xmlns 속성을 붙여야 합니다: <html xmlns="https://www.w3.org/1999/xhtml">

최소한으로 필요한 것:

파일: install.rdf
파일: chrome.manifest
파일: bootstrap.js
폴더: locale
1. 폴더: VALID_LOCALE_HERE
  1. 파일: ANYTHING.dtd

chrome.manifest 파일은 이와 같이 내용에 대한 정의를 포함해야 합니다: content NAME_OF_YOUR_ADDON ./

chrome.manifest 파일은 또한 위의 속성 섹션처럼 locale을 가리키는 라인이 포함되어야 합니다. locale의 폴더 이름이 en-US라면chrome.manifest 파일은 다음 줄을 포함해야 합니다: locale NAME_OF_YOUR_ADDON en-US locale/en-US/

이것은 설치되면 HTML과 XUL 페이지를 열어주는 예시 부가기능입니다: GitHub :: l10n-xhtml-xul. 이것은 어떻게 현지화된 HTML파일을 옵션으로 쓸 수 있는지의 예입니다: GitHub :: l10n-html-options. about:config에서 general.useragent.locale을 en-US로 바꾼 뒤 en-GB로 바꾸고 열린 페이지를 새로고침 하면 현지화의 변화를 알 수 있습니다.

더 읽어보기

How to convert an overlay extension to restartless a step by step guide. Some code samples are provided. The page is based on and expanded from Dave Garrett's step-by-step guide to convert an old overlay based extension into a restartless addon.
Dave Townsend provides a basic code base to load UI for each opened window in a bootstrapped extension.
Mark Finkle provides some simple example code for restartless add-ons in mobile Firefox, adding resources (like the options window) to bootstrapped extensions and using default preferences without a default/preferences/prefs.js file.
Kris Maglione writes about the requirements for the cleanup procedures in bootstrapped extensions.
Edward Lee shows off some helpful coding patterns and examples you can use in your bootstrapped add-on.
Documentation for Inline Options in Firefox 7 and later.