Widget Api - adamfowleruk/mljs GitHub Wiki

Wiki ▸ Widget 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)