A Web Component that provides an interface for performing keyword searches
for traits and displaying results in a paginated table. Note that the
component saves its state to the URL query string parameters and a search
will be automatically performed if the parameters are present when the
componnent is loaded. The component uses the
LisPaginatedSearchMixin mixin. See
the mixin docs for further details.
Query String Parameters
query: The text in the query field of the search form.
page: What page of results is loaded.
Example
HTMLElement properties can only be set via
JavaScript. This means the searchFunction property
must be set on a <lis-trait-search-element> tag's instance of the
LisTraitSearchElement class. For example:
<!-- add the Web Component to your HTML --> <lis-trait-search-elementid="trait-search"></lis-trait-search-element>
<!-- configure the Web Component via JavaScript --> <scripttype="text/javascript"> // a site-specific function that sends a request to a trait search API functiongetTraits(searchData, {abortSignal}) { // returns a Promise that resolves to a search result object } // get the trait search element constsearchElement=document.getElementById('trait-search'); // set the element's searchFunction property searchElement.searchFunction=getTraits; </script>
Example
The LisTraitSearchElement class inherits the
resultAttributes and
tableHeader properties from
LisPaginatedSearchMixin mixin. These are
used to define what attributes of the results provided by the
searchFunction will be shown in the results table and
what their corresponding headers will be in the table. These properties can be
overridden via JavaScript. For example:
<!-- add the Web Component to your HTML --> <lis-trait-search-elementid="trait-search"></lis-trait-search-element>
<!-- configure the Web Component via JavaScript --> <scripttype="text/javascript"> // get the trait search element constsearchElement=document.getElementById('trait-search'); // set the element's resultAttributes property searchElement.resultAttributes= ["name", "identifier", "description", "link"]; // set the element's tableHeader property searchElement.tableHeader= { name:"Name", identifier:"Identifier", description:"Description", link:"Link", }; </script>
Example
The traitExample property can be used to set the
example text in the search form. For example:
<!-- set the example text via HTML --> <lis-trait-search-elementtraitExample="flower"></lis-trait-search-element>
<!-- set the example text via JavaScript --> <lis-trait-search-elementid="trait-search"></lis-trait-search-element>
<scripttype="text/javascript"> // get the trait search element constsearchElement=document.getElementById('trait-search'); // set the element's traitExample property searchElement.traitExample='flower'; </script>
Current Web standards do not allow Promises to be
cancelled. Components that use the
LisPaginatedSearchMixin mixin can use
this controller to make Promises cancelable. Event
listeners can also subscribe to the controller and will be called whenever
it cancels. The underlying AbortSignal is also
available for more low-level access. This is the value of the abortSignal
attribute of the PaginatedSearchOptions
object passed to the component's SearchFunction | SearchFunction.
Components that use the
LisPaginatedSearchMixin mixin can use
this controller to subscribe to the
DOMContentLoaded event. The advantage to
using the controller instead of subscribing to the event directly is that
the controller triggers a redraw of the component's template, meaning if a
listener updates a property that should change the template, triggering a
redraw of the template will be handled by the controller.
Components that use the
LisPaginatedSearchMixin mixin can use
this controller to interact with URL query string parameters. For example,
it can be used to set values of form elements reactively, i.e. if the
query string parameter a form element gets its value changes, then the
element's value will be updated in the component's template.
ProtectedrequiredQueryStringParams
requiredQueryStringParams:string[][]
The LisPaginatedSearchMixin mixin will
automatically perform a search when loaded if certain parameters are
present in the URL query string. Components that use the mixin can specify
what parameters are necessary by setting this property in their
constructor. Specifically, this property represents groups of parameters that will
trigger a search if all parameters within a group are present.
resultAttributes
resultAttributes:string[]
Components that use the
LisPaginatedSearchMixin mixin must
define what attributes their search results will have so the mixin can
correctly parse and display the results in a table. These attributes
can be specified by setting this property in a component's constructor.
Additionally, this property may be used by the end user at run-time to override the
default result attributes defined by the component.
ProtectedresultsInfo
resultsInfo:string
Info about the results returned by the searchFunction.
Components that use the
LisPaginatedSearchMixin mixin will
inherit this property. It stores an external function that must be provided
by users of the component that performs a search using the data from the
component's submitted search form.
Components that use the
LisPaginatedSearchMixin mixin can optionally
define CSS classes for the columns of the table results are displayed in a table.
The classes are set from an object that has attributes matching the
resultAttributes. The object can be specified by setting this property in a
component's constructor. Additionally, this property may be used by the end used at
run-time to override the default table column classes defined by the component.
Components that use the
LisPaginatedSearchMixin mixin must
define what attributes their search results will have so the mixin can
correctly parse and display the results in a table. The header of the
table is set from an object that has these attributes. The object can
be specified by setting this property in a component's constructor. Additionally,
this property may be used by the end used at run-time to override the default table
headers defined by the component.
An optional property to set the example text for the Trait name input field.
translate
translate:boolean
Static[metadata]
[metadata]:object & Record<PropertyKey, unknown>
Static_$litElement$
_$litElement$:boolean
StaticOptional_initializers
_initializers?:Initializer[]
StaticProtectedfinalized
finalized:undefined | true
Marks class as having been finalized, which includes creating properties
from static properties, but does not include all properties created
from decorators.
Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.
When the form of a component that use the
LisPaginatedSearchMixin mixin is
submitted, the mixin parses the form contents into a
!FormData | FormData instance. This instance is converted into
a simple object mapping form element names to their values. This conversion
is done with the formToObject method. If the object doesn't match the
expected SearchData template type or if there are redundant names in the
!FormData | FormData instance that need to be resolved, then the
component should override the formToObject method.
Parameters
formData: FormData
The !FormData | FormData instance to convert
into an object.
Returns a HTMLCollection of the elements in the object on which the method was invoked (a document or an element) that have all the classes given by classNames. The classNames argument is interpreted as a space-separated list of classes.
By default, the LisPaginatedSearchMixin
displays search results using the
LisSimpleTableElement. Components that use the
mixin can override this portion of the template by implementing their own
renderResults method. The results data will be available via the inherited
searchResults variable.
Returns unknown
The results portion of the template.
ProtectedrenderResultsInfo
renderResultsInfo(): unknown
By default, the LisPaginatedSearchMixin
displays search results info using the in paragraph tags. Components that use the
mixin can override this portion of the template by implementing their own
renderResultsInfo method.
Displays element fullscreen and resolves promise when done.
When supplied, options's navigationUI member indicates whether showing navigation UI while in fullscreen is preferred or not. If set to "show", navigation simplicity is preferred over screen space, and if set to "hide", more screen space is preferred. User agents are always free to honor user preference over the application's. The default value "auto" indicates no application preference.
Components that use the
LisPaginatedSearchMixin mixin will
inherit this method. It allows the component's search form to be submitted
programmatically.
Returns void
toggleAttribute
toggleAttribute(qualifiedName, force?): boolean
If force is not given, "toggles" qualifiedName, removing it if it is present and adding it if it is not present. If force is true, adds qualifiedName. If force is false, removes qualifiedName.
Returns true if qualifiedName is now present, and false otherwise.
Adds an initializer function to the class that is called during instance
construction.
This is useful for code that runs against a ReactiveElement
subclass, such as a decorator, that needs to do work for each
instance, such as setting up a ReactiveController.
constmyDecorator = (target: typeofReactiveElement, key: string) => { target.addInitializer((instance: ReactiveElement) => { // This is run during construction of the element newMyController(instance); }); }
Decorating a field will then cause each instance to run an initializer
that adds a controller:
Initializers are stored per-constructor. Adding an initializer to a
subclass does not add it to a superclass. Since initializers are run in
constructors, initializers will run in order of the class hierarchy,
starting with superclasses and progressing to the instance's class.
Parameters
initializer: Initializer
Returns void
Nocollapse
StaticProtectedfinalize
finalize(): void
Finishes setting up the class so that it's ready to be registered
as a custom element and instantiated.
This method is called by the ReactiveElement.observedAttributes getter.
If you override the observedAttributes getter, you must either call
super.observedAttributes to trigger finalization, or call finalize()
yourself.
Returns void
Nocollapse
attributes
StaticobservedAttributes
get observedAttributes(): string[]
Returns a list of attributes corresponding to the registered properties.
Returns string[]
Nocollapse
attributeChangedCallback
attributeChangedCallback(name, _old, value): void
Synchronizes property values when attributes change.
Specifically, when an attribute is set, the corresponding property is set.
You should rarely need to implement this callback. If this method is
overridden, super.attributeChangedCallback(name, _old, value) must be
called.
Registers a ReactiveController to participate in the element's reactive
update cycle. The element automatically calls into any registered
controllers during its lifecycle callbacks.
If the element is connected when addController() is called, the
controller's hostConnected() callback will be immediately called.
Parameters
controller: ReactiveController
Returns void
removeController
removeController(controller): void
Removes a ReactiveController from the element.
Parameters
controller: ReactiveController
Returns void
dev-mode
StaticOptionaldisableWarning
disableWarning?:((warningKind) => void)
Disable the given warning category for this class.
This method only exists in development builds, so it should be accessed
with a guard like:
// Disable for all ReactiveElement subclasses ReactiveElement.disableWarning?.('migration');
// Disable for only MyElement and subclasses MyElement.disableWarning?.('migration');
Type declaration
(warningKind): void
Disable the given warning category for this class.
This method only exists in development builds, so it should be accessed
with a guard like:
// Disable for all ReactiveElement subclasses ReactiveElement.disableWarning?.('migration');
// Disable for only MyElement and subclasses MyElement.disableWarning?.('migration');
Parameters
warningKind: WarningKind
Returns void
Nocollapse
Nocollapse
StaticOptionalenableWarning
enableWarning?:((warningKind) => void)
Enable the given warning category for this class.
This method only exists in development builds, so it should be accessed
with a guard like:
// Enable for all ReactiveElement subclasses ReactiveElement.enableWarning?.('migration');
// Enable for only MyElement and subclasses MyElement.enableWarning?.('migration');
Type declaration
(warningKind): void
Enable the given warning category for this class.
This method only exists in development builds, so it should be accessed
with a guard like:
// Enable for all ReactiveElement subclasses ReactiveElement.enableWarning?.('migration');
// Enable for only MyElement and subclasses MyElement.enableWarning?.('migration');
Parameters
warningKind: WarningKind
Returns void
Nocollapse
Nocollapse
StaticOptionalenabledWarnings
enabledWarnings?:WarningKind[]
Read or set all the enabled warning categories for this class.
This property is only used in development builds.
Nocollapse
lifecycle
connectedCallback
connectedCallback(): void
Invoked when the component is added to the document's DOM.
In connectedCallback() you should setup tasks that should only occur when
the element is connected to the document. The most common of these is
adding event listeners to nodes external to the element, like a keydown
event handler added to the window.
Typically, anything done in connectedCallback() should be undone when the
element is disconnected, in disconnectedCallback().
Returns void
disconnectedCallback
disconnectedCallback(): void
Invoked when the component is removed from the document's DOM.
This callback is the main signal to the element that it may no longer be
used. disconnectedCallback() should ensure that nothing is holding a
reference to the element (such as event listeners added to nodes external
to the element), so that it is free to be garbage collected.
An element may be re-connected after being disconnected.
Returns void
properties
StaticelementProperties
elementProperties:PropertyDeclarationMap
Memoized list of all element properties, including any superclass
properties. Created lazily on user subclasses when finalizing the class.
Nocollapse
Staticproperties
properties:PropertyDeclarations
User-supplied object that maps property names to PropertyDeclaration
objects containing options for configuring reactive properties. When
a reactive property is set the element will update and render.
By default properties are public fields, and as such, they should be
considered as primarily settable by element users, either via attribute or
the property itself.
Generally, properties that are changed by the element should be private or
protected fields and should use the state: true option. Properties
marked as state do not reflect from the corresponding attribute
However, sometimes element code does need to set a public property. This
should typically only be done in response to user interaction, and an event
should be fired informing the user; for example, a checkbox sets its
checked property when clicked and fires a changed event. Mutating
public properties should typically not be done for non-primitive (object or
array) properties. In other cases when an element needs to manage state, a
private property set with the state: true option should be used. When
needed, state properties can be initialized via public properties to
facilitate complex interactions.
Nocollapse
StaticcreateProperty
createProperty(name, options?): void
Creates a property accessor on the element prototype if one does not exist
and stores a PropertyDeclaration for the property with the
given options. The property setter calls the property's hasChanged
property option or uses a strict identity check to determine whether or not
to request an update.
This method may be overridden to customize properties; however,
when doing so, it's important to call super.createProperty to ensure
the property is setup correctly. This method calls
getPropertyDescriptor internally to get a descriptor to install.
To customize what properties do when they are get or set, override
getPropertyDescriptor. To customize the options for a property,
implement createProperty like this:
Returns a property descriptor to be defined on the given named property.
If no descriptor is returned, the property will not become an accessor.
For example,
Returns the property options associated with the given property.
These options are defined with a PropertyDeclaration via the properties
object or the @property decorator and are registered in
createProperty(...).
Note, this method should be considered "final" and not overridden. To
customize the options for a given property, override
createProperty.
Node or ShadowRoot into which element DOM should be rendered. Defaults
to an open shadowRoot.
StaticshadowRootOptions
shadowRootOptions:ShadowRootInit
Options used when calling attachShadow. Set this property to customize
the options for the shadowRoot; for example, to create a closed
shadowRoot: {mode: 'closed'}.
Note, these options are used in createRenderRoot. If this method
is customized, options should be respected if possible.
Invoked on each update to perform rendering tasks. This method may return
any value renderable by lit-html's ChildPart - typically a
TemplateResult. Setting properties inside this method will not trigger
the element to update.
Returns unknown
styles
StaticelementStyles
elementStyles:CSSResultOrNative[]
Memoized list of all element styles.
Created lazily on user subclasses when finalizing the class.
Nocollapse
StaticProtectedfinalizeStyles
finalizeStyles(styles?): CSSResultOrNative[]
Takes the styles the user supplied via the static styles property and
returns the array of styles to apply to the element.
Override this method to integrate into a style management system.
Styles are deduplicated preserving the last instance in the list. This
is a performance optimization to avoid duplicated styles that can occur
especially when composing via subclassing. The last item is kept to try
to preserve the cascade order with the assumption that it's most important
that last added styles override previous styles.
Parameters
Optionalstyles: CSSResultGroup
Returns CSSResultOrNative[]
Nocollapse
updates
hasUpdated
hasUpdated:boolean
Is set to true after the first update. The element code cannot assume
that renderRoot exists before the element hasUpdated.
isUpdatePending
isUpdatePending:boolean
True if there is a pending update as a result of calling requestUpdate().
Should only be read.
Returns a Promise that resolves when the element has completed updating.
The Promise value is a boolean that is true if the element completed the
update without triggering another update. The Promise result is false if
a property was set inside updated(). If the Promise is rejected, an
exception was thrown during the update.
To await additional asynchronous work, override the getUpdateComplete
method. For example, it is sometimes useful to await a rendered element
before fulfilling this Promise. To do this, first await
super.getUpdateComplete(), then any subsequent state.
A promise of a boolean that resolves to true if the update completed
without triggering another update.
ProtectedenableUpdating
enableUpdating(_requestedUpdate): void
Note, this method should be considered final and not overridden. It is
overridden on the element instance with a function that triggers the first
update.
Parameters
_requestedUpdate: boolean
Returns void
ProtectedfirstUpdated
firstUpdated(_changedProperties): void
Invoked when the element is first updated. Implement to perform one time
work on the element after update.
It is not safe to override the updateComplete getter directly due to a
limitation in TypeScript which means it is not possible to call a
superclass getter (e.g. super.updateComplete.then(...)) when the target
language is ES5 (https://github.com/microsoft/TypeScript/issues/338).
This method should be overridden instead. For example:
A promise of a boolean that resolves to true if the update completed
without triggering another update.
ProtectedperformUpdate
performUpdate(): void
Performs an element update. Note, if an exception is thrown during the
update, firstUpdated and updated will not be called.
Call performUpdate() to immediately process a pending update. This should
generally not be needed, but it can be done in rare cases when you need to
update synchronously.
Returns void
requestUpdate
requestUpdate(name?, oldValue?, options?): void
Requests an update which is processed asynchronously. This should be called
when an element should update based on some state not triggered by setting
a reactive property. In this case, pass no arguments. It should also be
called when manually implementing a property setter. In this case, pass the
property name and oldValue to ensure that any configured property
options are honored.
Schedules an element update. You can override this method to change the
timing of updates by returning a Promise. The update will await the
returned Promise, and you should resolve the Promise to allow the update
to proceed. If this method is overridden, super.scheduleUpdate()
must be called.
For instance, to schedule updates to occur just before the next frame:
overrideprotectedasyncscheduleUpdate(): Promise<unknown> { await new Promise((resolve) =>requestAnimationFrame(() =>resolve())); super.scheduleUpdate(); }
Controls whether or not update() should be called when the element requests
an update. By default, this method always returns true, but this can be
customized to control when to update.
Updates the element. This method reflects property values to attributes
and calls render to render DOM via lit-html. Setting properties inside
this method will not trigger another update.
Invoked before update() to compute values needed during the update.
Implement willUpdate to compute property values that depend on other
properties and are used in the rest of the update process.
willUpdate(changedProperties) { // only need to check changed properties for an expensive computation. if (changedProperties.has('firstName') || changedProperties.has('lastName')) { this.sha = computeSHA(`${this.firstName}${this.lastName}`); } }
<lis-trait-search-element>
A Web Component that provides an interface for performing keyword searches for traits and displaying results in a paginated table. Note that the component saves its state to the URL query string parameters and a search will be automatically performed if the parameters are present when the componnent is loaded. The component uses the
LisPaginatedSearchMixin
mixin. See the mixin docs for further details.Query String Parameters
Example
HTMLElement
properties can only be set via JavaScript. This means thesearchFunction
property must be set on a<lis-trait-search-element>
tag's instance of theLisTraitSearchElement
class. For example:Example
The
LisTraitSearchElement
class inherits theresultAttributes
andtableHeader
properties fromLisPaginatedSearchMixin
mixin. These are used to define what attributes of the results provided by thesearchFunction
will be shown in the results table and what their corresponding headers will be in the table. These properties can be overridden via JavaScript. For example:Example
The
traitExample
property can be used to set the example text in the search form. For example: