Widget Api

adamfowleruk edited this page Aug 11, 2013 · 2 revisions

WikiWidget Api

##Widget API

This document has been replaced by the Core API page and the Browser API page on github.io.

This page describes the features present in the browser JavaScript Widget libraries built on top of the Core MLDB API.

##Conventions used in this document

All Widgets follow a common pattern. They all have a constructor that takes the string name of a HTML ID that already exists in the document. This is the parent element for the newly instantiated widget.

###Event Handling

All event management is done using instances of the Publisher class. This class has subscribe and unsubscribe methods, and is intended to handle one class of event only so that the receiver of the event does not have to worry about querying the type or data within an event. Widgets implement addEVENTCLASSListener(callback(event)) and removeEVENTCLASSListener(callback(event)) functions. For example, a searchbar widget has addResultsListener and removeResultsListener functions.

The convention used by widget functions that are designed to receive events follows the updateEVENTCLASS(json object) pattern. E.g. updateResults. This is not a hard and fast requirement yet. Note to use a wraper function when linking one of these methods to an addEventListener method - this is so that the value of javascript 'this' is set to the correct object.

##Widgets API

###Globals defined by widgets.js

window.*

  • bubbleSort - Bubblesort's an array of JSON objects based on the value at a specified path within each object (parent.child.value format)
  • jsonExtractValue - Extracts a value at the specified JSON path from a JSON object (parent.child.value format)

Array.prototype.*

  • swap - Swaps two items in an Array
  • contains - Returns true if the Array contains the value specified
  • position - Returns the index of the object specified within an array

###Helper Classes in widgets.js

com.marklogic.event.Event

  • Event Constructor - Creates an instance of an event given the type string and data object

com.marklogic.event.Publisher

  • Publisher Constructor - Creates an instance of a Publisher object
  • subscribe - Subscribe the given function to this Publisher's events
  • unsubscribe - Unsubscribes the given function from this Publisher's events
  • publish - Fires an event (any value, not necessarily an Event object) to the subscribers

###Helper Classes in widgets-search.js

com.marklogic.widgets.options in widget-search.js - NB may be refactored in to mldb.js Core API

  • options Constructor - Creates an instance of an options builder object. (Wraps an options JSON object)
  • toJson - Returns the JSON options object for use in MLDB and thus the REST API
  • additionalQuery - Sets the additional query. I.e. restricts the results of any search that uses these options
  • defaultCollation - Sets the default collation for subsequent calls to this object, returns this for chaining
  • defaultSortOrder - Sets the default sort order for subsequent calls to this object
  • defaultType - Sets the default index type for subsequent calls to this object, returns this for chaining
  • defaultNamespace - Sets the default index namespace for subsequent calls to this object, returns this for chaining
  • rangeConstraint - Adds a range constraint definition to the search options, returns this for chaining. Adds range index to sort options too.
  • addConstraint - Adds any valid constraint definition to the search options. Used by other constraint creation functions, returns this for chaining
  • collectionConstraint - Adds a collection constraint to the search options, returns this for chaining
  • pageLength - Sets the default search page length for results (can be overridden by search parameters)
  • transformResults - Sets the transform to use on the results ("raw" or "snippet" or custom (with ns and module specified))
  • sortOrderClear - Clears the sort order from the wrapped search options. (Defaults to score)
  • sortOrderScore - Sets the sort order to score
  • sortOrder - Sets the sort order to the specified XML element or JSON key, with optional direction and collation
  • tuples - Adds a tuples definition to the search options.

com.marklogic.widgets.query in widget-search.js - NB may be refactored in to mldb.js Core API

  • toJson - Returns the query JSON object for use by the MLDB and thus REST API
  • and - creates an and-query JSON, and returns it
  • or - creates an or-query JSON, and returns it
  • query - copies properties from the provided JSON query in to the query wrapped by this object
  • collection - create a collection query, and returns it
  • georadius - creates a geospatial radius query, and returns it

com.marklogic.widgets.searchhelper in widget-search.js

  • processValueAll - Processes a string to convert to a human readable form. Applies all of splitdash, splitunderscore, and camelcase
  • processValue - Processes a string to convert to a human readable form, applying the specified mode
  • splitdash - Splits a string into multiple words using the - symbol as a delimiter, if mode is "all" or "splitdash"
  • splitunderscore - Splits a string into multiple words using the _ symbol as a delimiter, if mode is "all" or "splitunderscore"
  • camelcase - Takes each word in the string and makes the first letter uppercase (does not alter other letters)

###UI widgets

com.marklogic.widgets.error in widgets.js

  • show - Sets the error message and ensures the element is visible (does not have class of hidden)
  • updateError - Alias for show
  • clear - Clears the error message and hides this widget (adds 'hidden' to element's class parameter)

com.marklogic.widgets.searchbar in widget-search.js

  • setCollection - Sets the collection to restrict all query results by. Passed as collection parameter to /v1/search
  • setDirectory - Sets the directory to restrict all query results by. Passed as directory parameter to /v1/search
  • setOptions - Sets the search options object used by this searchbar
  • setOptionsName - Sets the search options object's name. This widget will persist the options before the first search occurs on this page refresh.
  • setDefaultQuery - Sets the default query (usually blank). Only affects the first time the widget is shown (not after each clear() call)
  • setConnection - Sets the underlying MLDB connection object to use for the search request(s)
  • clear - Clears the search bar of its current value. Does not execute the search.
  • execute - Executes the search with the value currently in the searchbar input box
  • setSortWord - Sets the sort word used in this widget, as specified in the search options (usually "sort")
  • addResultsListener - Adds a function as a listener to Results events issued by this widget
  • removeResultsListener - Removes a function from the listener to Results events issued by this widget
  • addSortListener - Adds a function as a listener to Sort events issued by this widget
  • removeSortListener - Removes a function as a listener to Sort events issued by this widget
  • addFacetsListener - Adds a function as a listener to Facet events issued by this widget
  • removeFacetsListener - Removes a function as a listener to Facet events issued by this widget
  • addErrorListener - Adds a function as a listener to Error events issued by this widget (connection or search options or search parameter errors)
  • removeErrorListener - Removes a function as a listener to Error events issued by this widget
  • updateFacets - Event target. Updates the searchbar value for a selected facet. Executes the search again.
  • updatePage - Event target. Reexecutes the search for the specified page index.
  • updateSort - Event target. Updates the searchbar value for the specified sort order. Executes the search again.
  • reset - Resets all search results, facets, and pages. Fires a null event to all listeners (except error).

com.marklogic.widgets.searchfacets in widget-search.js

  • clear - Clears the entire facets widget of values
  • setSizes - Sets the default number of top facet results shown, and amount shown when clicking 'more'
  • setAllowShowAll - Sets whether the 'show all' link is shown when showing extended facet results
  • addSelectionListener - Adds a function as a listener to Selection events fired by this object
  • removeSelectionListener - Removes a function as a listener to Selection events fired by this object
  • updateFacets - Event target. Updates the facets given the search Results (NOT facets) object provided. E.g. from search results
  • updateSelectedFacets - Event target. Updates the selected facets list. E.g. if typed manually in a search

com.marklogic.widgets.searchresults in widget-search.js

  • clear - Clears the shown results in this widget
  • updateResults - Event target. Displays the specified page of results
  • addSelectionListener - Adds a function as a listener to Selection events fired by this object. E.g. title clicked
  • removeSelectionListener - Removes a function as a listener to Selection events fired by this object
  • addProcessor - Adds a custom results processor to the list of those used during results display
  • removeProcessor - Removes a custom results processor
  • setProcessorPriority - Sets the processor priority (NOT USED)

com.marklogic.widgets.searchpager in widget-search.js

  • clear - Clears the pages and results count in this widget's display
  • updatePage - Event target. Updates the page size, page, start index and total values. Receives a full results object.
  • addPageListener - Adds a function as a listener to Page events fired by this object
  • removePageListener - Removes a function as a listener to Page events fired by this object

com.marklogic.widgets.searchsort in widget-search.js

  • addSelectionListener - Adds a function as a listener to sort selection events fired by this object
  • removeSelectionListener - Removes a function as a listener to sort selection events fired by this object
  • updateSort - Event target. Updates the selected sort value based on the string value passed in (NOT IMPLEMENTED)
  • setOptions - Sets the search options object used to draw the total number of available sort options in this widget

com.marklogic.widgets.searchpage in widget-search.js

  • setOptions - Sets the search options object used by all widgets in this search page widget
  • execute - Executes a search in the searchbar widget contained by this widget
  • setConnection - Sets the underlying connection used by this widget (only the searchbar widget currently)
  • reset - Resets to blank all widgets contained in this search page widget

com.marklogic.widgets.cooccurence in widget-cooccurence.js

  • setOptions - Sets the options object used by this co-occurence widget
  • updateValues - Event target. Takes a search results object and uses the tuples values to display co-occurence results. Orders by frequency, descending

com.marklogic.widgets.highcharts in widget-highcharts.js

  • Property: options - Sets the search options object used by this chart object
  • setAggregateFunction - Sets the aggregate function to be used (default: mean average)
  • setAutoCategories - Specifies that category values should be calculated automatically from the results object
  • setSeriesSources - Specifies the JSON path (parameter.valueparam format) of the series name, result category and value sources
  • updateResults - Event target. Updates the chart based on the specified results object (only those on the current page - use a large page length on your search)

com.marklogic.widgets.kratu in widget-kratu.js

  • Property: kratu - Access the underlying kratu object to specify custom parameters
  • updateResults - Event target. Update the kratu display based on the specified results object (defaults to result content JSON, not summary (search time etc.) JSON)

##window.* global functions

# window.bubbleSort(nodeurl,callback_opt)

Unsubscribes a nodeurl from all alerts. Uses Adam Fowler's (Me!) custom subscribe REST API resource and the Alerting framework.


# window.jsonExtractValue(nodeurl,callback_opt)

Unsubscribes a nodeurl from all alerts. Uses Adam Fowler's (Me!) custom subscribe REST API resource and the Alerting framework.


##Array.prototype.* instance function mixins

# Array.prototype.swap(nodeurl,callback_opt)

Unsubscribes a nodeurl from all alerts. Uses Adam Fowler's (Me!) custom subscribe REST API resource and the Alerting framework.


# Array.prototype.contains(nodeurl,callback_opt)

Unsubscribes a nodeurl from all alerts. Uses Adam Fowler's (Me!) custom subscribe REST API resource and the Alerting framework.


# Array.prototype.position(nodeurl,callback_opt)

Unsubscribes a nodeurl from all alerts. Uses Adam Fowler's (Me!) custom subscribe REST API resource and the Alerting framework.


##Event class in widgets.js

# event.init(type,data)

Unsubscribes a nodeurl from all alerts. Uses Adam Fowler's (Me!) custom subscribe REST API resource and the Alerting framework.


##Publisher class in widgets.js

# Publisher Constructor(nodeurl,callback_opt)

Unsubscribes a nodeurl from all alerts. Uses Adam Fowler's (Me!) custom subscribe REST API resource and the Alerting framework.


# Publisher.subscribe(nodeurl,callback_opt)

Unsubscribes a nodeurl from all alerts. Uses Adam Fowler's (Me!) custom subscribe REST API resource and the Alerting framework.


# Publisher.unsubscribe(nodeurl,callback_opt)

Unsubscribes a nodeurl from all alerts. Uses Adam Fowler's (Me!) custom subscribe REST API resource and the Alerting framework.


# Publisher.publish(nodeurl,callback_opt)

Unsubscribes a nodeurl from all alerts. Uses Adam Fowler's (Me!) custom subscribe REST API resource and the Alerting framework.


##Search options class in widgets-search.js (will move to mldb.js soon)

# options.a()


# options.aa()


# options.a()


# options.a()


# options.a()


# options.aa()


# options.a()


# options.a()


# options.a()


# options.aa()


# options.a()


# options.a()


# options.a()


# options.aa()


# options.a()


# options.a()


##Structured search query builder class in widgets-search.js (will move to mldb.js soon)

# query.toJson()


# query.and()


# query.or()


# query.query()


# query.collection()


# query.georadius()


##Search helper class in widgets-search.js

# searchhelper.a()


# searchhelper.a()


# searchhelper.a()


# searchhelper.a()


# searchhelper.a()


##Error UI Widget in widgets.js

# error.show()


# error.updateError()


# error.clear()


##Search Bar in widget-search.js

# searchbar.a()


# searchbar.a()


# searchbar.a()


# searchbar.a()


# options.a()


# options.a()


# options.a()


# options.a()


# options.a()


# options.a()


# options.a()


# options.a()


You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.