People Search

Already a member? •

AJAX People Search

API Key

Code Reference

Wink AJAX People Search API Class Reference

The Wink AJAX People Search API is a JavaScript API implemented in the following classes.

WinkSearchControl - Constructor

Constructor Description

Constructor	Description
`WinkSearchControl()`	Creates a new search control object. The search control object is a container for searchers, objects which implement the WinkSearch interface. The search control object is not operational until is has at least one searcher child. A search control is bound to an html container using the .draw() method. The expected order of operations is: sc = new WinkSearchControl(); sc.addSearcher(); sc.draw(); Once these steps have occurred, the search control is active and ready to begin performing searches.

WinkSearchControl()

Creates a new search control object. The search control object is a container for searchers, objects which implement the WinkSearch interface. The search control object is not operational until is has at least one searcher child. A search control is bound to an html container using the .draw() method.

The expected order of operations is:

  sc = new WinkSearchControl();
  sc.addSearcher();
  sc.draw();

Once these steps have occurred, the search control is active and ready to begin performing searches.

WinkSearchControl - Methods

Method Description

Method	Description
`.draw(element)`	This method is the final step needed to activate a search control object. It may only be called once all searchers have been added into the search control. When called, this method produces the user interface, search result containers for each configured searcher, and finally sets of the various linkages needed to coordinate parallel searches across all of the searchers. The method requires that the caller supply an html block element, typically a div element which the control draws within. The control operates best when provided with at least 300px of width and will scale reasonably well down to ~250px. The default user interface style is a linear style where the control inputs are at the top followed by a linear set of stacked results. Optionally, callers may request a tabbed user interface which works well when vertical real estate is at a premium. element - supplies an html block element that acts as a container for the control returns - void

.draw(element)

This method is the final step needed to activate a search control object. It may only be called once all searchers have been added into the search control. When called, this method produces the user interface, search result containers for each configured searcher, and finally sets of the various linkages needed to coordinate parallel searches across all of the searchers.

The method requires that the caller supply an html block element, typically a div element which the control draws within. The control operates best when provided with at least 300px of width and will scale reasonably well down to ~250px.

The default user interface style is a linear style where the control inputs are at the top followed by a linear set of stacked results. Optionally, callers may request a tabbed user interface which works well when vertical real estate is at a premium.

element - supplies an html block element that acts as a container for the control
returns - void

WinkSearchForm - Constructor

Constructor Description

Constructor	Description
`WinkSearchForm(enableClear, element)`	Creates a new search form object. The search form object supplies user interface elements, methods, properties, and callbacks designed to allow applications to control a collection of `WinkSearch()` objects. The user interface and capabilities match whats available to applications using the `WinkSearchControl()` (in fact, the `WinkSearchControl()` is internally based on this object. The expected order of operations is: sf = new WinkSearchForm(true/false, container); sf.setOnSubmitCallback(object, method); optional - sf.setOnClearCallback(object, method); Once these steps have occurred, the search form is active and ready to begin receiving and processing user input. The method accepts a required `enableClear` argument as well as a required element argument enableClear - when true, the search form should contain a clear button, otherwise, no clear button is created element - supplies the HTML node that should act as a container for this form

WinkSearchForm(enableClear, element)

Creates a new search form object. The search form object supplies user interface elements, methods, properties, and callbacks designed to allow applications to control a collection of WinkSearch() objects. The user interface and capabilities match whats available to applications using the WinkSearchControl() (in fact, the WinkSearchControl() is internally based on this object.

The expected order of operations is:

  sf = new WinkSearchForm(true/false, container);
  sf.setOnSubmitCallback(object, method);
  optional - sf.setOnClearCallback(object, method);

Once these steps have occurred, the search form is active and ready to begin receiving and processing user input.

The method accepts a required enableClear argument as well as a required element argument

enableClear - when true, the search form should contain a clear button, otherwise, no clear button is created
element - supplies the HTML node that should act as a container for this form

WinkSearchForm - Methods

Method Description

Method	Description
`.setOnSubmitCallback(object, method)`	This method registers an object/method combination that is called when the search form is "submitted". This event occurs when the user clicks on the search button, or when the user hits enter while focused on the text input element. When this occurs, the specified object becomes the active object and the specified method is called. The argument passed to the method is this search form. A typical method might look like this: App.prototype.onSubmit = function(form) { if (form.input.value) { this.localSearcher.execute(form.input.value); } return false; } Note in the above example that the search form is passed to the method, and that the method returns false indicating that it has processed the submit event. object - supplies an application level object that defines the context that the specified method will be called in. method - supplies the method to call. The method is passed a reference to this form and must return false. returns - void
`.setOnClearCallback(object, method)`	This method registers an object/method combination that is called when the clear button in the search form is pressed. It is an error to call this method if the search form was created without a clear button. When this occurs, the specified object becomes the active object and the specified method is called. The argument passed to the method is this search form. A typical method might look like this: App.prototype.onClear = function(form) { this.myClearFunction(); return false; } Note in the above example that the search form is passed to the method, and that the method returns false indicating that it has processed the clear event. object - supplies an application level object that defines the context that the specified method will be called in. method - supplies the method to call. The method is passed a reference to this form and must return false. returns - void
`.execute(opt_string? \|\| opt_query?)`	This method allows an application to "submit" the form. This involves optionally setting the form's text input element and then calling the registered on-submit callback method established using `.setOnSubmitCallback()`. opt_string - if present, supplies a string value that is placed in the form's text input element prior to invoking the on-submit callback method. opt_query [WinkPeopleQuery object] - if present, supplies a set of values that is placed in the form's text input element prior to invoking the on-submit callback method. returns - void

.setOnSubmitCallback(object, method)

This method registers an object/method combination that is called when the search form is "submitted". This event occurs when the user clicks on the search button, or when the user hits enter while focused on the text input element. When this occurs, the specified object becomes the active object and the specified method is called. The argument passed to the method is this search form.

A typical method might look like this:


  App.prototype.onSubmit = function(form) {
      if (form.input.value) {
          this.localSearcher.execute(form.input.value);
      }
      return false;
  }

Note in the above example that the search form is passed to the method, and that the method returns false indicating that it has processed the submit event.

object - supplies an application level object that defines the context that the specified method will be called in.
method - supplies the method to call. The method is passed a reference to this form and must return false.
returns - void

.setOnClearCallback(object, method)

This method registers an object/method combination that is called when the clear button in the search form is pressed. It is an error to call this method if the search form was created without a clear button. When this occurs, the specified object becomes the active object and the specified method is called. The argument passed to the method is this search form.

A typical method might look like this:


  App.prototype.onClear = function(form) {
      this.myClearFunction();
      return false;
  }

Note in the above example that the search form is passed to the method, and that the method returns false indicating that it has processed the clear event.

object - supplies an application level object that defines the context that the specified method will be called in.
method - supplies the method to call. The method is passed a reference to this form and must return false.
returns - void

.execute(opt_string? || opt_query?)

This method allows an application to "submit" the form. This involves optionally setting the form's text input element and then calling the registered on-submit callback method established using .setOnSubmitCallback().

opt_string - if present, supplies a string value that is placed in the form's text input element prior to invoking the on-submit callback method.
opt_query [WinkPeopleQuery object] - if present, supplies a set of values that is placed in the form's text input element prior to invoking the on-submit callback method.
returns - void

WinkSearch - Constructor

Constructor	Description
`WinkPeopleSearch()`	Creates a new searcher object. Note: Since this is a base class, it is unlikely that applications will make direct use of this constructor and instead will use the constructor as a side effect of creating a service specific searcher object (e.g., `WinkPeopleSearch`).

WinkSearch - Methods

Method	Description
`.setResultSetSize(indicator)`
`.getResultSetSize()`
`.clearResults()`	Upon successful completion of a search, the searcher object holds on to a collection of search results which describe the outcome of a particular search. This method is used to reset the searcher, clearing out all results. This method is implicitly called prior to the execution of a new search. returns - void
`.execute(query)`	This method is called to begin a new search. The query (either a WinkQueryObject or a string) argument supplies the search term. Upon completion, the object becomes populated with the corresponding set of results, and the registered search completion handler is called. query - [either a String or WinkQueryObject] supplies the query term used to perform the search returns - void
`.setSearchCompleteCallback(object, method, opt_arguments?)`	This method is used to register and object and method to notify on the completion of a search. Applications may optionally pass in a context argument using opt_arguments which is then passed to the specified method. object - supplies an application level object that defines the context that the specified method will be called in. method - supplies the method to call. For instance, if this method is called as .setSearchCompleteCallback(foo, MyObject.prototype.mySearchCompleteHandler), when a search on this searcher completes, a call to foo.mySearchCompleteHandler(opt_arguments?) is called. returns - void
`.setUserDefinedLabel(label)`	stub - no functionality is performed
`.setUserDefinedClassSuffix(classSuffix)`	This method is used to set a user defined class suffix for the search results section, and for the collection of search results produced by this searcher in the search control. The motivation for this method is to allow applications to set unique styling for the results and header of a particular set of search results. Assuming this method is called with a value of "siteSearch", a class of `wink-resultsRoot-siteSearch` will be applied to the `DIV` element that wraps the header and results associated with this searcher. Note, this is in addition to the generic `wink-resultsRoot` class. classSuffix - supplies a user defined class suffix that is appended to wink-resultsRoot-. This class is added to the DIV element that wraps the header and results associated with this searcher. returns - void
`.setLinkTarget(linkTarget)`	This method is called to set the link target used for links embedded in search results. The default value is `WinkSearch.LINK_TARGET_BLANK` which specifies that links will open in a new browser window. When a searcher is added to a search control, the search control makes an implicit call to this method using the current link target setting for the search control. This means that if your application needs a searcher to operate with a different link target setting than the setting established by the search control, you need to call this method after adding the searcher to the search control. linkTarget - supplies the target frame that links should open within, valid values include: WinkSearch.LINK_TARGET_BLANK - links will open in a new window, e.g., <A href=... target=_blank ...> WinkSearch.LINK_TARGET_SELF - links will open in the same window and frame, e.g., <A href=... target=_self ...> WinkSearch.LINK_TARGET_TOP - links will open in the topmost frame, e.g., <A href=... target=_top ...> WinkSearch.LINK_TARGET_PARENT - links will open in either the topmost frame, or the replace the current frame, e.g., <A href=... target=_parent ...> anything-else - links will open in the specified frame or window, e.g., <A href=... target=anything-else ...> returns - void
`.setNoHtmlGeneration()`	There are times when your application is not using the search control and is only using a small set of properties from a search result and you are displaying these in a highly customized format. When this is the case, a small optimization is available to your application. The searcher can be programmed to NOT generate a .html property leaving you with only the raw properties valid in a result. returns - void
`.getAttribution()`	stub function returns - null: no attribute is required
`.setQueryAddition(term)`
`.createResultHtml(result)`	This method allows the caller to either create, or re-generate the .html property of the specified result. Sometimes this is needed when the caller had previously use .setNoHtmlGeneration(), or when the caller is reloading a result object from its own storage system. result - supplies a result object. It's .html property will be deleted and regenerated as a result of this call. If the result does not contain a .html property, one will be created. returns - void

WinkSearch - Static Methods

Method Description

Method	Description
`.getBranding(opt_element?, opt_orientation?)`	This method is a static helper function that returns a "powered by Wink" HTML DOM branding node to your application, and optionally attaches it to your document as the only child of the specified optional element. The purpose of this method is to ensure that your application has a simple way to comply with branding requirements in situations where using wither the search form in the WinkSearchControl or in the WinkSearchForm is not appropriate for your application. opt_element - an optional argument which if supplied, specifies the HTML DOM node that will be populated with a "powered by Wink" branding element. opt_orientation - an optional argument which if supplied, specifies the orientation of the branding node. Valid values include: WinkSearch.HORIZONTAL_BRANDING - request horizontal orientation returns - a "powered by Wink" HTML DOM node that you are free to attach or clone onto your document.
`.setOnLoadCallback(handler)`	This method is a static helper function that registers the specified handler function to be called once the document containing this call loads. Previous documentation recomended that you use the body element's onload attribute (e.g., `<body onload="OnLoad()">`. While this is a fine way to go when you are in complete control of the page and all code loaded by the page, this approach can cause problems with some runtimes to destroy your body.onload handler. The `setOnLoadCallback()` approach does not have these problems and therefore is our recomended way of registiring a callback that calls your code upon document load (a point in time when the AJAX Search APIs are fully loaded and ready for use). handler - a required function that will be called once the containing document is loaded and when the search API is ready for use. returns - void

.getBranding(opt_element?, opt_orientation?)

This method is a static helper function that returns a "powered by Wink" HTML DOM branding node to your application, and optionally attaches it to your document as the only child of the specified optional element. The purpose of this method is to ensure that your application has a simple way to comply with branding requirements in situations where using wither the search form in the WinkSearchControl or in the WinkSearchForm is not appropriate for your application.

opt_element - an optional argument which if supplied, specifies the HTML DOM node that will be populated with a "powered by Wink" branding element.
opt_orientation - an optional argument which if supplied, specifies the orientation of the branding node. Valid values include:
- WinkSearch.HORIZONTAL_BRANDING - request horizontal orientation
returns - a "powered by Wink" HTML DOM node that you are free to attach or clone onto your document.

.setOnLoadCallback(handler)

This method is a static helper function that registers the specified handler function to be called once the document containing this call loads. Previous documentation recomended that you use the body element's onload attribute (e.g., <body onload="OnLoad()">. While this is a fine way to go when you are in complete control of the page and all code loaded by the page, this approach can cause problems with some runtimes to destroy your body.onload handler. The setOnLoadCallback() approach does not have these problems and therefore is our recomended way of registiring a callback that calls your code upon document load (a point in time when the AJAX Search APIs are fully loaded and ready for use).

handler - a required function that will be called once the containing document is loaded and when the search API is ready for use.
returns - void

WinkSearch - Properties

The following collection of public properties are exposed by all objects that implement this interface. Unless otherwise stated, these properties are assumed to be read-only.

Method	Description
`.results[]`	This property contains an array of search result objects, one for each result. Each time a search executes, this property is cleared, and each time a search completes, the array is populated. If there are no results to report, the `.length` property of this array will be set to 0.

WinkPeopleSearch

This object implements the WinkSearch interface (compatabile with the GSearch interface) over the Wink People Search service. Upon completion of a search it delivers a collection WinkPeopleResults objects (compatable with GwebResults).

WinkPeopleSearch - Constructor

Constructor	Description
`WinkPeopleSearch()`	The constructor is used to create an instance of a searcher object designed to provide search results from the Wink People Search service.

WinkPeopleSearch - Methods

Method	Description
`none`	no addtional methods are available at this time. (aka "this page intentionally left blank")

Result Objects

Result objects are produced using a JSON encoding of server search requests. As a result, we have chosen not to implement formal Javascript objects, and instead dynamically create these objects from their serialized form. While there is no formal implementation of the objects, they exist, and we document them as if there was a backing Javascript implementation. The impact of all this is minimal. All that it means is that there is no named constructor. For each result, its as if the system called new Object() and then proceeded to set formal properties on that object. The results are documented below in terms of their properties.

Note: this is compatabile with the Google Result Object

For all objects, there are two common properties:

.GsearchResultClass - specifies the type of result
.html - supplies the root of an html element that may be cloned and attached somewhere into the applications DOM hierarchy.

Result Object - Common Properties

Common Property Description

Common Property	Description
`.GSearchResultClass`	`WinkPeopleSearch.RESULT_CLASS` - indicates WinkPeopleResult
`.html`	Supplies the root of an html element that may be cloned and attached somewhere into the applications DOM hierarchy. We expect that this is the primary property that applications will be concerned with and that their typical interaction will involve cloning this node an attaching it into their DOM hierarchy. We expect that they will use css to control styling and to control which elements are displayed. For instance, we expect the following fragment to be common across all applications that wish to copy and past search results delivered through the Wink AJAX People Search API. // clone the .html node from the result var node = result.html.cloneNode(true); // attach the node into my dom container.appendChild(node)

.GSearchResultClass

WinkPeopleSearch.RESULT_CLASS - indicates WinkPeopleResult

.html

Supplies the root of an html element that may be cloned and attached somewhere into the applications DOM hierarchy. We expect that this is the primary property that applications will be concerned with and that their typical interaction will involve cloning this node an attaching it into their DOM hierarchy. We expect that they will use css to control styling and to control which elements are displayed. For instance, we expect the following fragment to be common across all applications that wish to copy and past search results delivered through the Wink AJAX People Search API.

  // clone the .html node from the result
  var node = result.html.cloneNode(true);

  // attach the node into my dom
  container.appendChild(node)

WinkPeopleQuery Object - Properties

Property	Description
`.qn`	Name to query (e.g. "John Q. Public")
`.qi`	Interest to query (e.g. "kitboarding")
`.l`	location to query (e.g. Los Altos, CA)

WinkPeopleResult Object - Properties

Property	Description
`.click_url`	Supplies the raw URL of the result
`.gender`	Either "male" or "female" or "".
`.age`	Interger age for this person.
`.summary`	A descriptive summary for this person.
`.image_url`	Supplies the raw URL to the profile image.
`.geo.title`	Supplies the title for the result. In some cases, the title and the streetAddress are the same. This typically occurs when the search term is a street address such as Los Altos, CA.
`.geo.lat`	Supplies the latitude value of the result. Note: in some cases this property may be set to ''.
`.geo.lng`	Supplies the longitude value of the result. Note: in some cases this property may be set to ''.
`.geo.city`	Supplies a city name for the result. Note: in some cases, this property may be set to "".
`.geo.region`	Supplies a region name for the result (typically state or province). Note: in some cases, this property may be set to "".
`.geo.country`	Supplies a country name for the result. Note: in some cases, this property may be set to "".
`.places[]`	Supplies an array of places that this user can be found at, where each object contains a .title property and a .url property.