From 1109132f09d75da9a28b649c7677bb6ce07c40c0 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:41:45 -0500 Subject: initial commit --- .../index.html" | 645 +++++++++++++++++++++ 1 file changed, 645 insertions(+) create mode 100644 "files/es/lugares/gu\303\255a_para_migraci\303\263n_con_lugares/index.html" (limited to 'files/es/lugares') diff --git "a/files/es/lugares/gu\303\255a_para_migraci\303\263n_con_lugares/index.html" "b/files/es/lugares/gu\303\255a_para_migraci\303\263n_con_lugares/index.html" new file mode 100644 index 0000000000..1f093b487d --- /dev/null +++ "b/files/es/lugares/gu\303\255a_para_migraci\303\263n_con_lugares/index.html" @@ -0,0 +1,645 @@ +--- +title: Guía para migración con lugares +slug: Lugares/Guía_para_migración_con_lugares +tags: + - páginas_a_traducir +translation_of: Mozilla/Tech/Places/Places_Developer_Guide +--- +

This document is for extension and application developers who want to use the bookmarks and history APIs in Firefox 3. It provides code samples for many common use-cases, such as CRUD operations, searching, and observing.

+ +

Overview

+ +

Places is the umbrella term for a set of APIs for managing browsing history and URI metadata first introduced in Firefox 3. It encompasses history, bookmarks, tags, favicons, and annotations. There are two models of identity in the system: URIs, and unique integer identifiers for items in the bookmark system. Some of the APIs are URI-centric, some use item ids. The API signature and context usually make clear which is required.

+ +

Bookmarks

+ +

The toolkit bookmarks service is nsINavBookmarksService:

+ +
var bookmarks = Cc["@mozilla.org/browser/nav-bookmarks-service;1"]
+                .getService(Ci.nsINavBookmarksService);
+
+ +

This service provides methods for adding, editing and deleting items in the bookmarks collection.

+ +

Types in the Bookmark System

+ +

There are the four types of items in the bookmarks system, and their identifiers in the IDL:

+ + + +

Identifying Items in the Bookmark System

+ +

Items in the bookmarks collection are identified by an id unique to the user's profile. Most of the APIs provided by the bookmarks service use an item's id to identify what to act on.

+ +

The bookmarks datastore is hierarchical, modeling folders and their contents. The ids of several significant folders are made available as attributes of nsINavBookmarksService.

+ + + +

Other Bookmarks APIs

+ +

Note: This document covers the toolkit Places services. However, Firefox developers can take advantage of several helper APIs that are browser-specific:

+ + + +

Creating Bookmarks, Folders and Other Items

+ +

Creating a Bookmark

+ +
// create an nsIURI for the URL to be bookmarked.
+var bookmarkURI = Cc["@mozilla.org/network/io-service;1"]
+                  .getService(Ci.nsIIOService)
+                  .newURI("http://www.mozilla.com", null, null);
+
+var bookmarkId = bookmarks.insertBookmark(
+  bookmarks.toolbarFolder, // The id of the folder the bookmark will be placed in.
+  bookmarkURI,             // The URI of the bookmark - an nsIURI object.
+  bookmarks.DEFAULT_INDEX, // The position of the bookmark in its parent folder.
+  "my bookmark title");    // The title of the bookmark.
+
+ +

Creating a Folder

+ +
var folderId = bookmarks.createFolder(
+  bookmarks.toolbarFolder, // The id of the folder the new folder will be placed in.
+  "my folder title",       // The title of the new folder.
+  bookmarks.DEFAULT_INDEX);    // The position of the new folder in its parent folder.
+
+ +

Creating a Separator

+ +
var separatorId = bookmarks.insertSeparator(
+  bookmarks.toolbarFolder, // The id of the folder the separator will be placed in.
+  bookmarks.DEFAULT_INDEX);    // The position of the separator in its parent folder.
+
+ +

Creating a Livemark

+ +
var IOService = Cc["@mozilla.org/network/io-service;1"]
+                .getService(Ci.nsIIOService);
+
+var siteURI = IOService.newURI("http://www.mozilla.com", null, null);
+var feedURI = IOService.newURI("http://www.mozilla.org/news.rdf", null, null);
+
+var livemarks = Cc["@mozilla.org/browser/livemark-service;2"]
+                .getService(Ci.nsILivemarkService);
+
+livemarks.createLivemark(bookmarks.toolbarFolder, // The id of the folder the livemark will be placed in
+  "My Livemark Title",        // The title of the livemark
+  siteURI,                    // The URI of the site. A nsIURI object.
+  feedURI,                    // The URI of the actual feed. A nsIURI object.
+  bookmarks.DEFAULT_INDEX);   // The position of the livemark in its parent folder.
+
+ +

Accessing Bookmarks and Related Items

+ +

Accessing Item Properties

+ +

For all items:

+ + + +

For bookmarks:

+ + + +

For folders:

+ + + +

Accessing Folder Contents

+ +

Queries in Places are executed through the main history service. The example below shows how to enumerate a bookmark folder's contents, and how to access the properties of the items themselves.

+ +
var history = Cc["@mozilla.org/browser/nav-history-service;1"]
+	 .getService(Ci.nsINavHistoryService);
+var query = history.getNewQuery();
+query.setFolders([myFolderId], 1);
+var result = history.executeQuery(query, history.getNewQueryOptions());
+// The root property of a query result is an object representing the folder you specified above.
+var folderNode = result.root;
+// Open the folder, and iterate over its contents.
+folderNode.containerOpen = true;
+for (var i=0; i < folderNode.childCount; ++i) {
+	var childNode = folderNode.getChild(i);
+	 // Some item properties.
+	var title = childNode.title;
+	var id = childNode.itemId;
+	var type = childNode.type;
+
+	// Some type-specific actions.
+	if (type == Ci.nsINavHistoryResultNode.RESULT_TYPE_URI) {
+		var uri = childNode.uri;
+	}
+	else if (type == Ci.nsINavHistoryResultNode.RESULT_TYPE_FOLDER) {
+		childNode.QueryInterface(Ci.nsINavHistoryContainerResultNode);
+		childNode.containerOpen = true;
+		// now you can iterate over a subfolder's children
+	}
+}
+
+ +

ther available node types are documented in the IDL.

+ +

Searching Bookmarks

+ +

Queries are executed through the history service. The example below shows how to search through all bookmarks, and to iterate over the results.

+ +
var bookmarks = Cc["@mozilla.org/browser/nav-bookmarks-service;1"]
+                .getService(Ci.nsINavBookmarksService);
+var history = Cc["@mozilla.org/browser/nav-history-service;1"]
+              .getService(Ci.nsINavHistoryService);
+
+var query = history.getNewQuery();
+
+// Specify folders to be searched
+var folders = [bookmarks.toolbarFolder, bookmarks.bookmarksMenuFolder,
+               bookmarks.unfiledBookmarksFolder];
+query.setFolders(folders, folders.length);
+
+// Specify terms to search for, matches against title, URL and tags
+query.searchTerms = "firefox";
+
+var options = history.getNewQueryOptions();
+options.queryType = options.QUERY_TYPE_BOOKMARKS;
+
+var result = history.executeQuery(query, options);
+
+// The root property of a query result is an object representing the folder you specified above.
+var resultContainerNode = result.root;
+
+// Open the folder, and iterate over its contents.
+resultContainerNode.containerOpen = true;
+for (var i=0; i < resultContainerNode.childCount; ++i) {
+  var childNode = resultContainerNode.getChild(i);
+
+  // Accessing properties of matching bookmarks
+  var title = childNode.title;
+  var uri = childNode.uri;
+}
+
+ +

Updating Bookmark Items

+ +

For all items:

+ + + +

For bookmarks:

+ + + +

Deleting Bookmark Items

+ +

With the bookmarks service:

+ + + +

Observing Bookmark Events

+ +

The nsINavBookmarkObserver interface is used for observing bookmarks activity such as item additions, changes and deletions.

+ +
// Create a bookmark observer
+var observer = {
+  onBeginUpdateBatch: function() {
+    // This method is notified when a batch of changes are about to occur.
+    // Observers can use this to suspend updates to the user-interface, for example
+    // while a batch change is occurring.
+  },
+  onEndUpdateBatch: function() {
+    this._inBatch = false;
+  },
+  onItemAdded: function(id, folder, index) {
+  },
+  onItemRemoved: function(id, folder, index) {
+  },
+  onItemChanged: function(id, property, isAnnotationProperty, value) {
+    // isAnnotationProperty is a boolean value that is true of the changed property is an annotation.
+    // You can access a bookmark item's annotations with the <code>nsIAnnotationService</code>.
+  },
+  onItemVisited: function(id, visitID, time) {
+    // The visit id can be used with the History service to access other properties of the visit.
+    // The time is the time at which the visit occurred, in microseconds.
+  },
+  onItemMoved: function(id, oldParent, oldIndex, newParent, newIndex) {
+    // oldParent and newParent are the ids of the old and new parent folders of the moved item.
+  },
+  QueryInterface: function(iid) {
+    if (iid.equals(Ci.nsINavBookmarkObserver) ||
+        iid.equals(Ci.nsISupports)) {
+      return this;
+    }
+    throw Cr.NS_ERROR_NO_INTERFACE;
+  },
+};
+
+// Register the observer with the bookmarks service
+var bmsvc = Cc["@mozilla.org/browser/nav-bookmarks-service;1"]
+            .getService(Ci.nsINavBookmarksService);
+bmsvc.addObserver(observer, false);
+
+// Un-register the observer when done.
+bmsvc.removeObserver(observer);
+
+
+ +

HTML Import/Export

+ +

The nsIPlacesImportExportService service is used for import and export of bookmarks in the Netscape Bookmarks HTML format. Note that this service is only currently available for Firefox, not other toolkit-based applications.

+ +

Importing:

+ + + +
Note: The method importHTMLFromFileToFolder() method was removed in Gecko 14.0 (Firefox 14.0 / Thunderbird 14.0 / SeaMonkey 2.11).
+ +

Exporting:

+ + + +

Backup/Restore

+ +

The new bookmarks system uses the JSON format for storing backups of users' bookmarks. The APIs are available via the PlacesUtils API in the utils.js Javascript module.

+ +
var Ci = Components.interfaces;
+var Cc = Components.classes;
+var Cu = Components.utils;
+
+// Import PlacesUtils
+Cu.import("resource://gre/modules/PlacesUtils.jsm");
+Cu.import("resource://gre/modules/Services.jsm");
+
+// Create the backup file
+var jsonFile = Services.dirsvc.get("ProfD", Ci.nsILocalFile);
+jsonFile.append("bookmarks.json");
+jsonFile.create(Ci.nsILocalFile.NORMAL_FILE_TYPE, 0600);
+
+// Export bookmarks in JSON format to file
+PlacesUtils.backupBookmarksToFile(jsonFile);
+
+// Restore bookmarks from the JSON file
+// NOTE: This *overwrites* all pre-existing bookmarks
+PlacesUtils.restoreBookmarksFromJSONFile(jsonFile);
+
+ +

History

+ +

The toolkit history service is nsINavHistoryService:

+ +
var history = Cc["@mozilla.org/browser/nav-history-service;1"]
+              .getService(Ci.nsINavHistoryService);
+
+
+ +

The history service provides methods for adding, editing, deleting browser history. It's also the jump-off point for querying and searching the history and bookmarks collections.

+ +

While nsINavHistory is the main interface for history, there are a couple of other interfaces available for legacy and context-specific uses:

+ + + +

Adding to History

+ +

Places provides a couple of interfaces for adding to, and editing the browsing history. The main interface is nsINavHistoryService. Other interfaces that provide specialized abilities are nsIBrowserHistory and nsIGlobalHistory. Examples of the capabilities of each are provided below.

+ +
// Places deals in URIs, so here's a helper for creating them.
+function uri(spec) {
+  return Cc["@mozilla.org/network/io-service;1"].
+         getService(Ci.nsIIOService).
+         newURI(spec, null, null);
+}
+
+// Adding a basic visit via the core Places history service.
+var history = Cc["@mozilla.org/browser/nav-history-service;1"].
+              getService(Ci.nsINavHistoryService);
+var ourURI = uri("http://www.mozilla.com");
+var visitDate = Date.now() * 1000; // in microseconds
+var referrerURI = null; // or a URI
+var isRedirect = false;
+var visitType = history.TRANSITION_LINK; // the visit is from a link that was clicked
+var sessionId = 0; // can link the visit with a specific browsing session
+history.addVisit(ourURI, visitDate, referrerURI,
+                 visitType, isRedirect, sessionId);
+
+// Add a visit to a URL, with a page title and visited time
+// via nsIBrowserHistory.
+var browserHistory = histsvc.QueryInterface(Ci.nsIBrowserHistory);
+var ourURI = uri("http://www.mozilla.com");
+var pageTitle = "Mozilla";
+var visitDate = Date.now() * 1000; // in microseconds
+browserHistory.addPageWithDetails(ourURI, "Mozilla", visitDate);
+
+// Add a visit to a URL, with extended behavior information
+// via nsIGlobalHistory3.
+var globalHistory = Cc["@mozilla.org/browser/global-history;2"].
+                    getService(Ci.nsIGlobalHistory2);
+var ourURI = uri("http://www.mozilla.com");
+var isRedirect = false;
+var isTopLevel = true;
+globalHistory.addURI(ourURI, isRedirect, isTopLevel, referrerURI);
+globalHistory.setPageTitle(ourURI, "Mozilla");
+
+ +

Deleting from History

+ +
// Places deals in URIs, so here's a helper for creating them.
+function uri(spec) {
+  return Cc["@mozilla.org/network/io-service;1"].
+         getService(Ci.nsIIOService).
+         newURI(spec, null, null);
+}
+
+var browserHistory = histsvc.QueryInterface(Ci.nsIBrowserHistory);
+var ourURI = uri("http://www.mozilla.com");
+
+// Remove all visits for a single URL from history
+browserHistory.removePage(ourURI);
+
+// Remove all visits for multiple URLs from history
+var urisToDelete = [ourURI];
+// will call nsINavHistoryObserver.onBeginUpdateBatch/onEndUpdateBatch
+var doNotify = false;
+browserHistory.removePages(urisToDelete, urisToDelete.length, doNotify);
+
+// Remove all visits within a given time period
+var endDate = Date.now() * 1000; // now, in microseconds
+var startDate = endDate - (7 * 86400 * 1000 * 1000); // one week ago, in microseconds
+browserHistory.removePagesByTimeframe(startDate, endDate);
+
+// Remove all pages for a given host
+var entireDomain = true; // will delete from all hosts from the given domain
+browserHistory.removePagesFromHost("mozilla.com", true);
+// Remove all history visits
+browserHistory.removeAllPages();
+ +

Querying History

+ +

The code sample below queries the browser history for the ten most visited URLs in the browser history.

+ +
var historyService = Components.classes["@mozilla.org/browser/nav-history-service;1"]
+                               .getService(Components.interfaces.nsINavHistoryService);
+var query = historyService.getNewQuery();
+var options = historyService.getNewQueryOptions();
+options.sortingMode = options.SORT_BY_VISITCOUNT_DESCENDING;
+options.maxResults = 10;
+
+// execute the query
+var result = historyService.executeQuery(query, options);
+
+// iterate over the results
+result.root.containerOpen = true;
+var count = result.root.childCount;
+for (var i = 0; i < count; i++) {
+  var node = result.root.getChild(i);
+  // do something with the node properties...
+  var title = node.title;
+  var url = node.uri;
+  var visited = node.accessCount;
+  var lastVisitedTimeInMicrosecs = node.time;
+  var iconURI = node.icon; // is null if no favicon available
+}
+
+result.root.containerOpen = false;
+
+ +

Querying History for redirects and from_visit

+ +

Results of type RESULT_TYPE_FULL_VISIT have information about the visit, such as the referring visit, and how the transition happened (typed, redirect, link, etc). The problem is that it is not yet implemented -- see bug 320831. So the only solution for now seems to do one own SQL queries to the Places database.

+ +

Here is how one can get a connection to the Places database:

+ +
function getPlacesDbConn() {
+    return Components.classes['@mozilla.org/browser/nav-history-service;1'].
+      getService(Components.interfaces.nsPIPlacesDatabase).DBConnection;
+}
+
+ +

And then to get the a redirected visit_id from another visit_id:

+ +
function getFromVisit(visit_id) {
+  var sql = <cdata><![CDATA[
+    SELECT from_visit FROM moz_places, moz_historyvisits
+    WHERE moz_historyvisits.id = :visit_id AND moz_places.id = moz_historyvisits.place_id;
+  ]]></cdata>.toString();
+  var sql_stmt = getPlacesDbConn.createStatement(sql);
+  sql_stmt.params.visit_id = visit_id;  
+
+  var from_visit;
+  try {
+    // Here we can't use the "executeAsync" method since have to return a
+    // result right-away.
+    while (sql_stmt.executeStep()) {
+      from_visit = sql_stmt.row.from_visit;
+    }
+  } finally {
+    sql_stmt.reset();
+  }
+  return from_visit;
+}
+
+ +
Note: The <cdata><![CDATA[ xxx ]]></cdata>.toString() notation is E4X and it makes possible to write multi-line strings in JavaScript. This is very useful when writing long SQL statements.
+ +

Searching History

+ +

Queries are executed through the history service. The example below shows how to search through browser history, and to iterate over the results.

+ +
var history = Cc["@mozilla.org/browser/nav-history-service;1"]
+              .getService(Ci.nsINavHistoryService);
+
+var query = history.getNewQuery();
+
+// Specify terms to search for, matches against title and URL
+query.searchTerms = "firefox";
+
+var result = history.executeQuery(query, history.getNewQueryOptions());
+
+// The root property of a query result is an object representing the folder you specified above.
+var resultContainerNode = result.root;
+
+// Open the result, and iterate over it's contents.
+resultContainerNode.containerOpen = true;
+for (var i=0; i < resultContainerNode.childCount; ++i) {
+  var childNode = resultContainerNode.getChild(i);
+
+  // Accessing properties of matching bookmarks
+  var title = childNode.title;
+  var uri = childNode.uri;
+}
+
+ +

Observing History

+ +

The nsINavHistoryObserver interface allows observation of history events such as new visits, page title changes, page expiration and when all history is cleared.

+ +
var history = Cc["@mozilla.org/browser/nav-history-service;1"].
+              getService(Ci.nsINavHistoryService);
+let observer = {
+  onBeginUpdateBatch: function() {
+  },
+  onEndUpdateBatch: function() {
+  },
+  onVisit: function(aURI, aVisitID, aTime, aSessionID, aReferringID, aTransitionType) {
+  },
+  onTitleChanged: function(aURI, aPageTitle) {
+  },
+  onDeleteURI: function(aURI) {
+  },
+  onClearHistory: function() {
+  },
+  onPageChanged: function(aURI, aWhat, aValue) {
+  },
+  onPageExpired: function(aURI, aVisitTime, aWholeEntry) {
+  },
+  QueryInterface: function(iid) {
+    if (iid.equals(Components.interfaces.nsINavHistoryObserver) ||
+        iid.equals(Components.interfaces.nsISupports)) {
+      return this;
+    }
+    throw Cr.NS_ERROR_NO_INTERFACE;
+  }
+};
+
+history.addObserver(observer, false);
+
+ +

New

+ +

Tagging Service

+ +

The tagging of URIs is provided by nsITaggingService. The service is URI-centric, meaning that consumers can tag URIs directly, without first creating a bookmark. The unique identifier is the URI, and all APIs require URIs as nsIURI objects.

+ +
// Get the tagging service
+var tagssvc = Cc["@mozilla.org/browser/tagging-service;1"]
+              .getService(Ci.nsITaggingService);
+
+// Create a URI to tag
+var IOService = Cc["@mozilla.org/network/io-service;1"]
+                .getService(Ci.nsIIOService);
+var myURI = IOService.newURI("http://www.mozilla.com", null, null);
+
+// Tag the URI
+tagssvc.tagURI(myURI, ["mozilla", "firefox"]);
+
+// Get an array of tags for a URI
+var myTags = tagssvc.getTagsForURI(myURI, {});
+
+// Get an array of URIs for a tag
+var taggedURIs = tagssvc.getURIsForTag("mozilla");
+
+// Get an array of all tags
+var arrayOfAllTags = tagssvc.allTags;
+
+// Remove tags from a URI
+tagssvc.untagURI(myURI, ["mozilla", "firefox"]);
+
+ +


+ This service currently integrates with and is internally dependent upon bookmarks:

+ + + +

Annotations

+ +

Annotations provide a way to store small bits of arbitrary data for a URI or a bookmark:

+ +
// Get the annotation service
+var annotations = Cc["@mozilla.org/browser/annotation-service;1"]
+                  .getService(Ci.nsIAnnotationService);
+
+// Create a URI to annotate
+var IOService = Cc["@mozilla.org/network/io-service;1"]
+                .getService(Ci.nsIIOService);
+var myURI = IOService.newURI("http://www.mozilla.com", null, null);
+
+// Add an annotation to the URI, that expires when the URI is deleted
+// or expires from the browser history
+annotations.setPageAnnotation(myURI, "myAnnotation", "notes for this URI...",
+                              0, annotations.EXPIRE_WITH_HISTORY);
+
+// Create a bookmark to annotate
+var bookmarks = Cc["@mozilla.org/browser/nav-bookmarks-service;1"]
+                .getService(Ci.nsINavBookmarksService);
+var myBookmark = bookmarks.insertBookmark(bookmarks.toolbarFolder, myURI,
+                                          bookmarks.DEFAULT_INDEX, "my bookmark");
+
+// Add an annotation to the bookmark, that expires only when
+// the bookmark is deleted
+annotations.setItemAnnotation(myBookmark, "myAnnotation", "notes for this bookmark...",
+                              0, annotations.EXPIRE_WITH_HISTORY);
+
+ +

Note the syntactic difference between the URI and bookmark annotation APIs: URI annotation APIs use "Page" in method names whereas bookmark annotation APIs use "Item" in method names.

+ +

Saved Searches

+ +

New in Firefox 3 is the ability to save searches of bookmarks or history. These saved searches appear as folders in your bookmarks, with a special icon to signify their difference from normal folders. The contents of these folders are updated when expanded, executing the search against the current history and bookmarks collections.

+ +

Saved searches can be formulated as URIs, and added to the bookmarks collection as a normal bookmark. Formulation of search URIs is documented here.

+ +
// Formulate a URI to query for the 10 most visited URIs in the browser history
+var mostVisited = "place:queryType=0&sort=8&maxResults=10";
+
+// Create an nsIURI for the URL to be bookmarked.
+var bookmarkURI = Cc["@mozilla.org/network/io-service;1"]
+                  .getService(Ci.nsIIOService)
+                  .newURI(mostVisited, null, null);
+
+// Add the search to the bookmarks toolbar
+var id = bookmarks.insertBookmark(bookmarks.toolbarFolder, bookmarkURI,
+                                  bookmarks.DEFAULT_INDEX, "Most Visited");
+
-- cgit v1.2.3-54-g00ecf