From da78a9e329e272dedb2400b79a3bdeebff387d47 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:42:17 -0500 Subject: initial commit --- files/ko/places/accessing_bookmarks/index.html | 81 ++++++++++++ files/ko/places/custom_containers/index.html | 21 +++ files/ko/places/index.html | 70 ++++++++++ files/ko/places/instantiating_views/index.html | 70 ++++++++++ files/ko/places/query_system/index.html | 173 +++++++++++++++++++++++++ files/ko/places/views/index.html | 43 ++++++ 6 files changed, 458 insertions(+) create mode 100644 files/ko/places/accessing_bookmarks/index.html create mode 100644 files/ko/places/custom_containers/index.html create mode 100644 files/ko/places/index.html create mode 100644 files/ko/places/instantiating_views/index.html create mode 100644 files/ko/places/query_system/index.html create mode 100644 files/ko/places/views/index.html (limited to 'files/ko/places') diff --git a/files/ko/places/accessing_bookmarks/index.html b/files/ko/places/accessing_bookmarks/index.html new file mode 100644 index 0000000000..76d52c1ab7 --- /dev/null +++ b/files/ko/places/accessing_bookmarks/index.html @@ -0,0 +1,81 @@ +--- +title: Accessing Bookmarks +slug: Places/Accessing_Bookmarks +tags: + - Firefox 3 + - Places +translation_of: Mozilla/Tech/Places/Manipulating_bookmarks_using_Places +--- +

+

이 문서는 북마크 트리의 일부를 빠르게 구하기를 원하는 사람들을 위한 빠른 시작을 제공합니다. 북마크는 플레이스 질의 시스템을 이용하여 구할 수 있으며, 이는 더 일반적인 정보를 담고 있습니다. 북마크 서비스 API에 대해서는 북마크 서비스를 참고하시기 바랍니다.

+

질의와 옵션 개체 얻기

+

모든 질의는 히스토리 서비스를 통해 실행합니다. 먼저 히스토리 서비스에서 빈 질의와 옵션 개체를 얻어야 합니다.

+
var historyService = Components.classes["@mozilla.org/browser/nav-history-service;1"]
+                               .getService(Components.interfaces.nsINavHistoryService);
+var options = historyService.getNewQueryOptions();
+var query = historyService.getNewQuery();
+
+

원하는 폴더 찾기

+

알려진 폴더 ID는 북마크 서비스에서 구할 수 있습니다. /toolkit/components/places/public/nsINavBookmarksService.idl에 정의된 속성은 bookmarksMenuFolder, tagsFolder, unfiledBookmarksFolder, toolbarFolder입니다. 이전 질의에서 폴더 ID를 얻을 수도 있습니다.

+

이 예제는 북마크 도구 막대의 ID를 얻는 것입니다.

+
var bookmarksService = Components.classes["@mozilla.org/browser/nav-bookmarks-service;1"]
+                                 .getService(Components.interfaces.nsINavBookmarksService);
+var toolbarFolder = bookmarksService.toolbarFolder;
+
+

placesRoot는 전체 플레이스 계층 구조의 최상위 폴더입니다. 이는 사용자 데이터 뿐만 아니라 관리 데이터를 포함하고 있어서 질의에 사용하는 것은 바람직하지 않습니다.

+

질의와 옵션 개체 채우기

+

전체 북마크 트리를 원하면 그룹화 옵션 GROUP_BY_FOLDER을 사용해야 합니다. 현재, 질의 시스템은 이 플래그가 필요하지 않으며 정확하게 한 폴더의 내용을 요청하면 항상 계층 구조를 반환합니다. 이는 bug 331487입니다. 버그가 수정되면 GROUP_BY_FOLDER이 없는 북마크 질의는 모든 폴더와 서브폴더에서 질의에 부합하는 모든 북마크의 단순 목록을 반환할 것입니다.

+

통상의 북마크 질의에서 여러분은 하나의 최상위 폴더를 갖습니다. 질의 개체에서 이 폴더는 setFolders에 주어집니다.

+
options.setGroupingMode([options.GROUP_BY_FOLDER],1);
+query.setFolders([toolbarFolder], 1);
+
+

질의 실행하기

+

executeQuery 및 executeQueries 함수는 질의 결과를 포함한 nsINavHistoryResult 개체를 반환합니다.

+
var result = historyService.executeQuery(query, options);
+
+

결과 얻기

+

(예제와 같이) 키워드나 날짜 범위와 같은 고급 매개 변수가 없이 폴더로 분류된 딱 하나의 폴더를 질의할 때, 결과의 root는 폴더에 해당하는 nsINavHistoryContainerResultNode가 됩니다. 질의가 복잡하거나 GROUP_BY_FOLDER를 사용하지 않았다면 루트는 nsINavHistoryQueryResultNode가 됩니다.

+

결과 콘테이너의 자식을 접근하기 전에 먼저 그것을 열고 나서 자식을 탐색할 수 있습니다. 콘테이너가 열려 있는 동안 북마크 시스템의 공지를 듣고 자신을 최신 상태로 유지하게 됩니다. 작업을 마치면 꼭 콘테이너를 닫아 자원을 해제하십시오. 그렇지 않으면 콘테이너는 계속 알림을 받고 자신을 갱신하여 전체 브라우저를 느리게 합니다.

+
var rootNode = result.root;
+rootNode.containerOpen = true;
+
+// iterate over the immediate children of this folder and dump to console
+for (var i = 0; i < rootNode.childCount; i ++) {
+  var node = rootNode.getChild(i);
+  dump("Child: " + node.title + "\n");
+}
+
+// close a container after using it!
+rootNode.containerOpen = false;
+
+

RESULT_TYPE_FOLDER 형식이나 다른 형식의 노드를 만나면 이 폴더를 열고 계층 구조의 아래로 내려갈 수 있습니다. 여러 가지 결과 형식을 이해하려면 플레이스:질의 시스템의 "결과 이용하기" 섹션을 참고하시기 바랍니다.

+

전체 코드

+
var historyService = Components.classes["@mozilla.org/browser/nav-history-service;1"]
+                               .getService(Components.interfaces.nsINavHistoryService);
+var options = historyService.getNewQueryOptions();
+var query = historyService.getNewQuery();
+
+var bookmarksService = Components.classes["@mozilla.org/browser/nav-bookmarks-service;1"]
+                                 .getService(Components.interfaces.nsINavBookmarksService);
+var toolbarFolder = bookmarksService.toolbarFolder;
+
+//comment out the next line for now; the bug hasn't been fixed; final version should include the next line
+options.setGroupingMode([options.GROUP_BY_FOLDER],1);
+query.setFolders([toolbarFolder], 1);
+
+var result = historyService.executeQuery(query, options);
+var rootNode = result.root;
+rootNode.containerOpen = true;
+
+// iterate over the immediate children of this folder and dump to console
+for (var i = 0; i < rootNode.childCount; i ++) {
+  var node = rootNode.getChild(i);
+  dump("Child: " + node.title + "\n");
+}
+
+// close a container after using it!
+rootNode.containerOpen = false;
+
+
+  
+

diff --git a/files/ko/places/custom_containers/index.html b/files/ko/places/custom_containers/index.html new file mode 100644 index 0000000000..305255ee4d --- /dev/null +++ b/files/ko/places/custom_containers/index.html @@ -0,0 +1,21 @@ +--- +title: Custom Containers +slug: Places/Custom_Containers +tags: + - Places +--- +

사용자 정의 콘테이너는 확장이나 기타 서비스가 플레이스 폴더의 결과를 동적으로 제공하는 것을 가능하게 합니다. 이 문서를 읽기 전에 질의와 결과의 작동 방법에 대한 플레이스 질의 시스템을 숙지하는 것이 좋습니다.

+ +

원격 콘테이너

+ +

원격 콘테이너는 확장 작성자 등이 플레이스 질의 결과에 콘테이너의 내용을 제공하는 방법입니다. 먼저 nsIRemoteContainer를 구현하는 콤포넌트를 생성해야 합니다. 그리고 나서, nsINavBookmarksService.createContainer를 사용하여 여러분의 콤포넌트와 연관된 북마크 폴더를 생성합니다. type 매개 변수는 콤포넌트의 contract ID를 포함한 문자열입니다. 북마크 서비스와 기타 콤포넌트는 여러분의 nsIRemoteContainer 구현을 얻기 위하여 이 contract ID를 사용하여 CreateService를 호출합니다.

+ +

여러분의 서비스가 폴더와 관련을 맺으면, 폴더가 이동하거나 삭제될 때 알림을 받게 됩니다. 이러한 동작에 대응하여 여러분의 서비스는 폴더와 관련한 관리 정보를 갱신해야 합니다.(여러분의 콘테이너를 나타내는 콘테이너 결과 노드를 결과 사용자가 열거나 닫을 때 발생하는 알림은 테스트 부족으로 주석 처리되어 있습니다.) 또한, 여러분의 서비스는 콘테이너가 읽기 전용 자식을 가지고 있는지 또는 보통의 북마크와 마찬가지로 수정이 가능한지를 선언할 수 있습니다.

+ +

모드

+ +

원격 콘테이너 구현이 사용할 수 있는 작동 모드에는 두 가지가 있습니다. 첫 번째 모드는 북마크 제공자처럼 동작하여 일반 북마크 폴더 안에 실제 북마크를 생성합니다. 이러한 예가 라이브마크 서비스입니다. 라이브마크 서비스는 피드를 읽고 해당 스트림 안의 항목에 해당하는 폴더에 북마크를 생성합니다. 이 북마크는 북마크 서비스가 관리하므로 라이브마크 서비스는 콘테이너가 언제 열리고 닫히는지 상관하지 않습니다. (폴더의 피드와 관련한 정보를 갱신하기 위하여) 폴더가 이동하거나 삭제되는 경우를 처리하는 것과 라이브마크가 읽기 전용이라고 선언하는 것만 필요합니다.

+ +

두 번째 작동 모드는 더 적극적입니다.현재 이 모드는 지원하지 않습니다. 함수 호출은 테스트 지연으로 주석 처리되어 있습니다. 서비스는 콘테이너 열기 및 닫기 동작에 대응하여 실행 중에 결과를 채울 수 있습니다. 그러므로 표시되는 순간에 더 동적인 내용을 생성할 수 있습니다. 콘테이너 형식을 가진 폴더가 열리면 서비스는 알림을 받고 콘테이너 결과 노드가 주어집니다. 그러면 서비스는 appendURINode, appendFolderNode 등을 이용하여 해당 콘테이너에 자식을 생성할 수 있습니다. appendContainerNode를 특히 주목하십시오. 이는 다른 원격 콘테이너를 생성하는데 사용할 수 있습니다. 이러한 원격 콘테이너는 어떠한 북마크 폴더와도 관련이 없습니다(관련을 맺으려면 appendFolderNode를 사용하십시오). 예를 들어, 하위 폴더와 관련한 콘테이너를 동적으로 생성할 수 있는 파일 브라우저를 생성할 수 있습니다. 각 콘테이너는 속성 백(property bag)을 가지고 있어서 경로와 같은 임의의 정보를 노드에 연결하는데 사용할 수 있다는 점을 기억하십시오.

+ +
diff --git a/files/ko/places/index.html b/files/ko/places/index.html new file mode 100644 index 0000000000..99ffcc3778 --- /dev/null +++ b/files/ko/places/index.html @@ -0,0 +1,70 @@ +--- +title: Places +slug: Places +tags: + - Add-ons + - Developing Mozilla + - Extensions + - Places +translation_of: Mozilla/Tech/Places +--- +

+ +

플레이스(Places)는 Firefox의 북마크와 히스토리 시스템을 재작성한 것입니다. 이는 상당한 유연성과 복잡한 질의가 가능한 것을 목표로 삼고 있습니다. 파비콘(favicon) 저장소나 임의의 정보로 페이지에 주석을 달 수 있는 것과 같은 새로운 기능도 포함하고 있습니다. 또한, 다양한 새로운 사용자 인터페이스도 포함하고 있는데 본 개발자 문서에서는 이에 대해 다루지 않습니다(플레이스에 대한 모질라 위키 페이지를 참고하십시오).

+ +

플레이스는 mozStorage 인터페이스를 이용하여 sqlite 데이터베이스에 데이터를 저장합니다.

+ +

주제

+ +
+
질의 시스템(Query System)
+
특정 매개 변수로 북마크와 히스토리 시스템을 질의하는 방법.
+
+ +
+
북마크 접근하기(Accessing Bookmarks)
+
북마크를 접근하는 방법.
+
+ +
+
사용자 정의 콘테이너(Custom Containers)
+
플레이스 뷰에 서드파티 원본의 링크를 표시하기 위하여 사용자 정의 콘테이너를 생성하는 방법.
+
+ +
+
뷰(Views)
+
자신의 애플리케이션이나 확장에 플레이스 뷰를 생성하고 구성하는 방법.
+
+ +
+
뷰 생성하기(Instantiating Views)
+
자신의 확장이나 애플리케이션에 사용하기 위하여 내장된 플레이스 뷰를 포함한 콘트롤을 생성하는 방법.
+
+ +

서비스 API 문서

+ +
+
히스토리 서비스(History Service)
+
북마크 서비스(Bookmarks Service)
+
주석 서비스(Annotation Service)
+
라이브마크 서비스(Livemark Service)
+
파비콘 서비스(Favicon Service)
+
태깅 서비스(Tagging Service)
+
+ +

설계 문서

+ +
+
플레이스 데이터베이스 디자인(Places Database Design)
+
플레이스 데이터베이스 설계에 대한 고수준 개요.
+
히스토리 서비스 설계(History Service Design)
+
히스토리 서비스 설계.
+
북마크 서비스 설계(Bookmark Service Design)
+
북마크 서비스 설계.
+
주석 서비스 설계(Annotation Service Design)
+
주석 서비스 설계.
+
위치 막대 설계(Location Bar Design)
+
멋진 막대(awesomebar)라는 별명을 가진 플레이스 구동 위치 막대(Places-driven Location Bar)의 설계 및 알고리즘.
+
+ +

diff --git a/files/ko/places/instantiating_views/index.html b/files/ko/places/instantiating_views/index.html new file mode 100644 index 0000000000..4fdcc5d1c9 --- /dev/null +++ b/files/ko/places/instantiating_views/index.html @@ -0,0 +1,70 @@ +--- +title: Instantiating Views +slug: Places/Instantiating_Views +tags: + - Places +--- +

여러분의 확장이나 애플리케이션에서 북마크나 히스토리의 내용을 보여주려면 내장 플레이스 뷰를 사용할 수 있습니다. 이는 포괄적이며, 기본 기능을 작성하는 시간을 많이 아껴주므로 여러분은 애플리케이션을 작성하는데 집중할 수 있습니다.

+ +

다른 콘트롤 형식을 위해서 또는 더욱 사용자 정의된 뷰를 얻기 위해서 여러분 자신의 뷰를 구현할 수도 있습니다. Places:Views는 이 주제에 대해서 다룹니다.

+ +

보기

+ +

플레이스에서는 다음과 같은 내장 뷰를 이용할 수 있습니다.

+ + + +

XUL에서 생성하기

+ +
  <!-- include the places stylesheet to get the XBL bindings -->
+  <?xml-stylesheet href="chrome://browser/content/places/places.css"?>
+
+  <!-- include the required .js files -->
+  <script type="application/x-javascript"
+          src="chrome://global/content/globalOverlay.js"/>
+  <script type="application/x-javascript"
+          src="chrome://browser/content/places/utils.js"/>
+  <script type="application/x-javascript"
+          src="chrome://browser/content/places/controller.js"/>
+  <script type="application/x-javascript"
+          src="chrome://browser/content/places/treeView.js"/>
+
+  <!-- Tree View -->
+  <tree type="places" id="your_tree" place="place:..." ...>
+    <treecols>
+      <treecol id="title" flex="1" primary="true" .../>
+      ...
+    </treecols>
+    <treechildren flex="1"/>
+  </tree>
+
+  <!-- Menu View -->
+  <menu label="Your Menu">
+    <menupopup type="places" place="place:..."/>
+  </menu>
+
+  <!-- Toolbar View -->
+  <toolbaritem type="places" id="your_item" place="place:..."
+               .../>
+
+ +

스크립트에서 DOM 개체를 생성할 수도 있습니다.

+ +

스크립트 가로채기(Hookup)

+ +
var view = document.getElementById("your_view");
+view.init(null);
+view.appendController(PlacesController);
+
+ +

뷰는 null로 초기화되고(기본 뷰 구성입니다. ViewConfig 개체를 사용하여 뷰의 기능을 수정하는 것에 대한 자세한 정보는 Places:View Configurations를 참고하십시오.) 콘트롤러가 붙습니다. 뷰는 이제 사용할 준비가 되었습니다.

+ +

플레이스뷰 인터페이스

+ +

플레이스뷰 인터페이스를 통하여 뷰와 상호작용하는 것에 대한 정보는 Places:PlacesView Interface를 참고하시기 바랍니다.

+ +
diff --git a/files/ko/places/query_system/index.html b/files/ko/places/query_system/index.html new file mode 100644 index 0000000000..1a3dccf574 --- /dev/null +++ b/files/ko/places/query_system/index.html @@ -0,0 +1,173 @@ +--- +title: Query System +slug: Places/Query_System +tags: + - Firefox 3 + - Places +--- +

+

Firefox의 히스토리와 북마크 데이터는 "플레이스" 질의 API를 이용하여 접근할 수 있습니다. 이 API는 히스토리, 북마크, 그리고 두 가지 모두에 대하여 복잡한 질의를 실행할 수 있는 기능을 제공합니다. 질의의 결과는 조건에 맞는 데이터의 단순 목록이나 트리 구조를 포함한 개체입니다. 질의 API와 결과 데이터의 구조에 대한 정의는 toolkit/components/places/public/nsINavHistoryService.idl에 있습니다. 이 페이지는 일반적인 작업에 대한 소개와 핵심 API 사용법에 대한 예제를 제공합니다.

+

질의 실행

+

플레이스 질의는 몇 가지 기본 요소을 가지고 있습니다.

+ +

첫 번째 단계는 질의와 옵션을 생성하고 원하는 매개 변수를 채우는 것입니다. 빈 개체를 얻으려면 nsINavHistoryService.getNewQuery()와 nsINavHistoryService.getNewQueryOptions()를 사용합니다. 이 개체의 기본 값은 모든 브라우저 히스토리를 단순 목록으로 반환하는 질의를 낳습니다.

+
var historyService = Components.classes["@mozilla.org/browser/nav-history-service;1"]
+                               .getService(Components.interfaces.nsINavHistoryService);
+
+// no query parameters will get all history
+// XXX default sorting is... ?
+var options = historyService.getNewQueryOptions();
+
+// no query parameters will return everything
+var query = historyService.getNewQuery();
+
+// execute the query
+var result = historyService.executeQuery(query, options);
+
+
+

결과 형식

+

nsINavHistoryQueryOptions는 resultType 속성을 가지고 있는데 이는 결과로 반환되는 그룹화와 세부사항 수준의 구성을 가능하게 합니다. 이 속성의 여러 가지 값은 아래에 나와 있습니다. 이 값은 nsINavHistoryQueryOptions의 속성이기도 한데, Components.interfaces.nsINavHistoryQueryOptions.RESULTS_AS_VISIT와 같이 접근할 수 있습니다.

+ +

기본 질의 검색 매개 변수

+

const unsigned long TIME_RELATIVE_EPOCH = 0 const unsigned long TIME_RELATIVE_TODAY = 1 const unsigned long TIME_RELATIVE_NOW = 2 attribute PRTime beginTime attribute unsigned long beginTimeReference readonly attribute boolean hasBeginTime readonly attribute PRTime absoluteBeginTime attribute PRTime endTime attribute unsigned long endTimeReference readonly attribute boolean hasEndTime readonly attribute PRTime absoluteEndTime attribute AString searchTerms readonly attribute boolean hasSearchTerms attribute long minVisits attribute long maxVisits attribute boolean onlyBookmarked attribute boolean domainIsHost attribute AUTF8String domain readonly attribute boolean hasDomain attribute boolean uriIsPrefix attribute nsIURI uri readonly attribute boolean hasUri attribute boolean annotationIsNot attribute AUTF8String annotation readonly attribute boolean hasAnnotation readonly attribute unsigned long folderCount

+

기본 질의 구성 옵션

+

const unsigned short GROUP_BY_DAY = 0 const unsigned short GROUP_BY_HOST = 1 const unsigned short GROUP_BY_DOMAIN = 2 const unsigned short GROUP_BY_FOLDER = 3 const unsigned short SORT_BY_NONE = 0 const unsigned short SORT_BY_TITLE_ASCENDING = 1 const unsigned short SORT_BY_TITLE_DESCENDING = 2 const unsigned short SORT_BY_DATE_ASCENDING = 3 const unsigned short SORT_BY_DATE_DESCENDING = 4 const unsigned short SORT_BY_URI_ASCENDING = 5 const unsigned short SORT_BY_URI_DESCENDING = 6 const unsigned short SORT_BY_VISITCOUNT_ASCENDING = 7 const unsigned short SORT_BY_VISITCOUNT_DESCENDING = 8 const unsigned short SORT_BY_KEYWORD_ASCENDING = 9 const unsigned short SORT_BY_KEYWORD_DESCENDING = 10 const unsigned short SORT_BY_DATEADDED_ASCENDING = 11 const unsigned short SORT_BY_DATEADDED_DESCENDING = 12 const unsigned short SORT_BY_LASTMODIFIED_ASCENDING = 13 const unsigned short SORT_BY_LASTMODIFIED_DESCENDING = 14 const unsigned short SORT_BY_ANNOTATION_ASCENDING = 15 const unsigned short SORT_BY_ANNOTATION_DESCENDING = 16 const unsigned short RESULTS_AS_URI = 0 const unsigned short RESULTS_AS_VISIT = 1 const unsigned short RESULTS_AS_FULL_VISIT = 2 attribute unsigned short sortingMode attribute AUTF8String sortingAnnotation attribute unsigned short resultType attribute boolean excludeItems attribute boolean excludeQueries attribute boolean excludeReadOnlyFolders attribute boolean expandQueries attribute boolean includeHidden attribute boolean showSessions attribute unsigned long maxResults const unsigned short QUERY_TYPE_HISTORY = 0 const unsigned short QUERY_TYPE_BOOKMARKS = 1 const unsigned short QUERY_TYPE_UNIFIED = 2 attribute unsigned short queryType

+

복합 질의

+

하나 이상의 nsINavHistoryQuery 개체를 executeQueries()로 전달할 수 있습니다. 하나의 질의 개체 안에서 모든 매개 변수는 + + AND + 로 연결됩니다. 그리고 서로 다른 질의 개체의 조건들은 + + OR + 로 연결됩니다. 이는 여전히 표현력이 있으면서도 중첩된 절을 가진 완전한 논리 연산보다 더 간단한 구현과 인터페이스를 가능하게 합니다.

+

다음은 방문한 모든 페이지 중 제목이나 URL에 "firefox"라는 단어를 포함한 페이지나 오늘 mozilla.org에서 방문한 페이지를 질의하는 예제입니다.

+
// first query object searches for "firefox" in title/URL
+var query1 = historyService.getNewQuery();
+query1.searchTerms = "firefox";
+
+// second query object searches for visited in past 24 hours AND from mozilla.org
+var query2 = historyService.getNewQuery();
+query2.beginTimeReference = query2.TIME_RELATIVE_NOW;
+query2.beginTime = -24 * 60 * 60 * 1000000; // 24 hours ago in microseconds
+query2.endTimeReference = query2.TIME_RELATIVE_NOW;
+query2.endTime = 0; // now
+query2.domain = "mozilla.org";
+
+var result = historyService.executeQueries([query1, query2], 2, options);
+
+
+ 참고: 키워드 검색은 + + OR + 질의를 가로질러 올바르게 동작하지 않습니다. 현재 작동 방식은 보통의 질의를 실행하고 나서 첫 번째 질의의 키워드를 선택하여 모든 결과를 거릅니다. (달리 이야기하면, 첫 번째 질의의 키워드는 모든 질의와 + + AND + 로 연결됩니다.) 뒤따르는 질의 개체의 키워드는 무시합니다. 이는 bug 320332입니다.
+

북마크 질의

+

간단한 북마크 질의를 실행하기 위한 빠른 시작 설명이 Accessing Bookmarks에 있습니다.

+

북마크 폴더의 내용은 질의 개체에 "folders" 멤버를 설정하는 것으로 구할 수 있습니다. 이 항목은 북마크 서비스에서 온 폴더 ID의 배열입니다. 일반적으로 이 목록에는 해당 폴더의 내용을 알려줄 하나의 폴더 ID가 있습니다. 여러 개의 폴더를 지정할 수 있으며 결과는 모든 폴더의 교집합이 됩니다.

+
+ 주의: 북마크 질의에 영향을 줄 목적으로 GROUP_BY_FOLDER 옵션이 있습니다. 이는 구현되지 않았는데 bug 331487를 참고하십시오. 북마크 계층 구조를 원한다면 항상 이 옵션을 사용해야 합니다. 이 옵션이 빠지면 질의가 반환하는 모든 폴더의 모든 북마크 항목을 단순한 목록으로 반환하도록 바뀝니다.
+

정렬에 대해서는 보통 (기본 값인) SORT_BY_NONE를 사용하는데 이는 사용자가 북마크 관리자에서 지정한 "자연스러운" 순서로 항목을 반환하기 때문입니다. 그러나 다른 정렬도 작동합니다.

+

북마크 질의에 대해서는 보통 요청한 폴더의 모든 항목을 구하기 위하여 질의 매개 변수가 없습니다. 정확하게 하나의 폴더 및 GROUP_BY_FOLDER를 지정하고 매개 변수가 없으면 이는 정확하게 하나의 폴더에 대응하므로 시스템은 훨씬 효율적인 질의를 수행하고 최신 결과를 유지하게 됩니다.

+
var bookmarkService = Components.classes["@mozilla.org/browser/nav-bookmarks-service;1"]
+                                .getService(Components.interfaces.nsINavBookmarksService);
+// |query| and |options| are objects created in the previous section
+query.setFolders([bookmarkService.toolbarFolder], 1);
+options.setGroupingMode([options.GROUP_BY_FOLDER], 1);
+var result = historyService.executeQuery(query, options);
+
+

질의 직렬화

+

질의와 옵션 개체는 queriesToQueryString를 사용하여 "place:"로 시작하는 문자열로 직렬화할 수 있습니다. 결과 문자열은 저장하거나 북마크할 수 있습니다. "place:" URI를 북마크하면 사용자가 그것을 열 때 질의의 결과로 확장됩니다. 원본 개체는 queryStringToQueries를 사용하여 문자열로부터 직렬화를 해제할 수 있습니다.

+

주의할 점은 문자열이 비어 있으면 queryStringToQueries는 어떠한 질의 개체도 반환하지 않는다는 것입니다. 코드는 이를 처리해야 합니다. 반환되는 옵션 구조는 항상 있습니다. 옵션을 지정하지 않으면 기본 값을 갖게 됩니다. 질의 매개 변수가 없는데 입력 문자열이 빈 것이 아니면(옵션이 있었습니다) 기본 질의 값을 포함하는 하나의 질의 개체를 얻게 됩니다.

+

다음은 두 개의 질의와 하나의 옵션 개체를 직렬화하고 해제하는 예제입니다.

+
var queryString = historyService.queriesToQueryString([query1, query2], 2, options);
+
+var queriesRef = { };
+var queryCountRef = { };
+var optionsRef = { };
+historyService.queryStringToQueries(queryString, queriesRef, queryCountRef, optionsRef);
+// now use queriesRef.value, optionsRef.value
+
+

"place:" URI에서 이용 가능한 용어에 대한 참조는 Places:PlaceURIs를 참고하십시오.

+

결과 사용

+

결과를 사용하는 가장 일반적인 방법은 뷰를 구현하는 것입니다. 결과를 트리 콘트롤에 넣는 내장 뷰가 있으며 여러분 자신의 뷰를 구현할 수도 있습니다. 자세한 사항은 Places:Views를 참고하시기 바랍니다. 이 섹션은 결과를 직접 접근하는 방법에 대해서 다룹니다. 예를 들어, 여러분 자신의 뷰를 생성하거나 결과를 표시하는 대신 처리하는 경우입니다.

+

+ + 참고: 노드를 접근할 대는 참조를 유지하지 않도록 주의하십시오. 정렬과 같은 프로그래머가 실행하는 명령어 뿐만 아니라 히스토리와 북마크 시스템에서 결과로 보내는 알림은 구조가 변경되거나 노드가 삽입, 삭제, 대체되도록 합니다. +

+

executeQuery()/executeQueries()가 반환하는 nsINavHistoryResult 개체는 주어진 히스토리나 북마크 질의에 부합하는 목록을 포함합니다. 이 결과는 노드로 구성된 트리 구조에 포함됩니다. 노드 형식은 type 속성을 이용해서 구할 수 있습니다. 이 형식은 더 자세한 정보를 얻기 위해서 어떤 인테페이스를 QueryInterface 할 수 있는지 알려줍니다.

+ +

다음은 노드의 형식을 구하는 예제입니다.

+
var Ci = Components.interfaces;
+switch(node.type) {
+  case node.RESULT_TYPE_URI:
+    dump("URI result " + node.uri + "\n");
+    break;
+  case node.RESULT_TYPE_VISIT:
+    var visit = node.QueryInterface(Ci.nsINavHistoryVisitResultNode);
+    dump("Visit result " + node.uri + " session = " + visit.sessionId + "\n");
+    break;
+  case node.RESULT_TYPE_FULL_VISIT:
+    var fullVisit = node.QueryInterface(Ci.nsINavHistoryFullVisitResultNode);
+    dump("Full visit result " + node.uri + " session = " + fullVisit.sessionId + " transitionType = " +
+         fullVisit.transitionType + "\n");
+    break;
+  case node.RESULT_TYPE_HOST:
+    var container = node.QueryInterface(Ci.nsINavHistoryContainerResultNode);
+    dump("Host " + container.title + "\n");
+    break;
+  case node.RESULT_TYPE_REMOTE_CONTAINER:
+    var container = node.QueryInterface(Ci.nsINavHistoryContainerResultNode);
+    dump("Remote container " + container.title + " type = " + container.remoteContainerType + "\n");
+    break;
+  case node.RESULT_TYPE_QUERY:
+    var query = node.QueryInterface(Ci.nsINavHistoryQueryResultNode);
+    dump("Query, place URI = " + query.uri + "\n");
+    break;
+  case node.RESULT_TYPE_FOLDER:
+    // Note that folder nodes are of type nsINavHistoryContainerResultNode by default, but
+    // can be QI'd to nsINavHistoryQueryResultNode to access the query and options that
+    // created it.
+    dump("Folder " + node.title + " id = " + node.itemId + "\n");
+    break;
+  case node.RESULT_TYPE_SEPARATOR:
+    dump("-----------\n");
+    break;
+}
+
+

콘테이너

+

콘테이너는 다른 콘테이너 목록과 결과 노드를 포함합니다. 각 결과는 질의의 루트를 나타내는 콘테이너를 가지고 있습니다. 이는 결과의 root 속성을 이용하여 구할 수 있습니다. 일반적인 질의에 대해서 이 루트 콘테이너는 원본 질의에서 여러분이 제공한 질의 매개 변수와 옵션을 포함한 nsINavHistoryQueryResultNode입니다. 하나의 북마크 폴더로 대응하는 질의에 대해서 이는 nsINavHistoryContainerResultNode이 됩니다.

+

콘테이너는 열리거나 닫힐 수 있습니다. 이는 트리 뷰의 열린 상태나 닫힌 상태에 해당하며 메뉴를 보이거나 감추는 것에 대응할 수 있습니다. 콘테이너의 내용을 얻으려면 먼저 콘테이너를 열어야 합니다. 대부분의 콘테이너 형식은 자신을 지연된 방식으로(lazily) 채우기 때문에 콘테이너를 여는 것은 실제 주어진 질의를 실행하는 것에 해당합니다. 콘테이너가 열린 동안에는 히스토리와 북마크 시스템의 알림을 듣고 내용을 수정하여 최신 상태로 유지합니다. 이러한 이유로 작업을 마치자 마자 콘테이너를 닫는 것이 최선인데, 이는 더 나은 성능을 제공하기 때문입니다. 콘테이너를 닫고 히스토리나 북마크 변경 알림이 도착하기 전에 다시 열면 보통 결과는 여전히 존재하고 작업은 빠르게 됩니다.

+

다음은 콘테이너를 탐색하는 예제입니다.

+
var cont = result.root;
+cont.containerOpen = true;
+for (var i = 0; i < cont.childCount; i ++) {
+  var node = cont.getChild(i);
+  dump(node.title + "\n");
+}
+cont.containerOpen = false;
+
+

결과 뷰 인터페이스

+

결과를 UI에 대응하려면 nsINavHistoryResultViewer 인터페이스를 구현하고 그것을 nsINavHistoryResult.viewer 속성과 함께 결과에 붙입니다. 사용자 동작의 결과로서 또는 북마크와 히스토리 시스템의 알림의 결과로서 결과 트리가 바뀌면 이 뷰어가 호출됩니다. 그러면 여러분의 구현은 이러한 변경을 UI에 반영하게 됩니다.

+

nsITreeBoxObject에 대한 미리 준비된 뷰 인터페이스가 제공되는데 이는 트리의 복잡한 뷰 요구사항을 관리합니다. 이 개체의 인터페이스는 nsINavHistoryResultTreeViewer (nsINavHistoryResultViewer의 파생 인터페이스)입니다. 더 자세한 정보와 예제는 Places:Views를 참고하시기 바랍니다.

+
+  
+

diff --git a/files/ko/places/views/index.html b/files/ko/places/views/index.html new file mode 100644 index 0000000000..7f4233cc5a --- /dev/null +++ b/files/ko/places/views/index.html @@ -0,0 +1,43 @@ +--- +title: Views +slug: Places/Views +tags: + - Places +--- +

뷰는 nsINavHistoryResult 개체를 사용자에게 표시하는 방법입니다. 뷰는 nsINavHistoryService.idl에 정의된 nsINavHistoryResultViewer 인터페이스를 구현합니다.

+ +

대부분의 애플리케이션에서 내장 뷰를 포함한 플레이스 콘트롤 중의 하나를 사용하면 충분하고 자신의 뷰를 사용하는 복잡함을 피할 수 있습니다. 더 자세한 사항은 Instantiating Views를 참고하시기 바랍니다.

+ +

뷰 등록하기

+ +

nsINavHistoryResult에 viewer 속성을 지정하여 뷰를 등록합니다. 이 때, 결과는 주어진 뷰의 result 속성을 지정하게 됩니다.뷰의 결과 속성을 명시적으로 지정하면 안됩니다. 뷰를 초기화하려면 viewer 속성을 null로 지정합니다. 이는 뷰의 결과 속성 또한 null로 지정하게 합니다.

+ +

참조 고리에 대해 주의하십시오. 뷰와 결과는 모두 서로에 대한 참조를 가지고 있습니다. 이 개체들을 삭제하려면 result.viewer를 null로 지정하여 이 고리를 없애야 합니다. 내장 트리 뷰(아래를 참고하십시오)는 이를 자동으로 처리합니다. 트리가 소멸되거나 다른 nsITreeView가 트리와 결합하면 트리는 nsITreeView.tree = null를 호출합니다. 뷰어는 이 경우를 감지하고 자신을 결과에서 분리합니다.

+ +
내장 트리 뷰
+ +

가장 흔한 형식의 뷰는 트리 콘트롤이지만 이는 구현하기가 상대적으로 어려운 콘트롤이기도 합니다. 그러므로, 플레이스는 여러분이 결과를 트리 뷰에 표시하기를 원하는 경우를 위하여 내장 뷰 개체를 제공합니다. 이는 browser/components/places/content/treeView.js에 구현되어 있습니다.

+ +

이 개체는 nsINavHistoryResultViewer와 nsITreeView를 모두 구현합니다. 그러므로 이 개체를 사용하면 결과(플레이스 질의 시스템 참고)와 트리 사이를 중개할 수 있습니다.

+ +
var result = historyService.executeQuery(...); // your places query result
+var tree = document.getElementById("mytree"); // your tree control
+
+var showRootNodeInTree = true;
+var treeviewer = new PlacesTreeView(showRootNodeInTree);
+
+result.viewer = treeviewer;
+tree.view = treeviewer.QueryInterface(Components.interfaces.nsITreeView);
+
+ +

내장 트리 뷰는 (nsINavHistoryService.idl에 선언된) nsINavHistoryResultViewObserver를 구현한 관찰자(observer) 인터페이스를 붙일 수도 있습니다. 이 관찰자 인터페이스를 이용하면 외부 콤포넌트는 어떤 일이 발생하는지 확인하고 적절한 동작을 취할 수 있습니다. 예를 들어, 플레이스 트리에서는 콘트롤러가 붙어서 무엇인가 트리에 드래그 앤 드롭되는지 알아차릴 수 있습니다. 그리고 나서 적절한 동작을 취합니다.

+ +

뷰 구현하기

+ +

사용자 정의 트리 뷰가 필요할 때는 여러분 자신의 클래스 안에 nsINavHistoryResultTreeViewer를 둘러싸는 것이 가장 쉽습니다. 예를 들어, 특별한 첫 번째 행을 구현하려면 여러분의 개체는 첫 번째 행에 대한 nsITreeView 응답을 제공하고 다른 모든 메시지는 하나 이동한 색인과 함께 내장 트리 뷰에 전달하면 됩니다.

+ +

nsINavHistoryResultNode.viewIndex 속성은 뷰에 사용하기 위하여 명시적으로 제공됩니다. 이 값은 각 노드가 생성될 때 -1로 초기화됩니다. 이 값을 사용하여 보이는 노드는 추적할 수 있습니다. 내장 트리 뷰어는 노드가 켜진 행의 색인을 보관하기 위하여 이 속성을 사용합니다.

+ +

nsINavHistoryResultViewer 또한 관찰자 인터페이스를 가지고 있어서 nsINavHistoryResultViewObserver가 변화를 관찰할 수 있도록 합니다. 그러나 이 관찰자 인터페이스는 트리만을 위한 것입니다. bug 337638는 이를 nsINavHistoryResultTreeViewer 개체로 옮기기 위한 것입니다. nsINavHistoryResultViewer의 다른 구현은 자신의 관찰자를 이용해야 합니다.

+ +
-- cgit v1.2.3-54-g00ecf