vsm-autocomplete
Advanced tools
vsm-autocomplete is a web-page component for looking up terms that are
linked to identifiers. These are fetched from a given
vsm-dictionary.
Its main purpose is to be a subcomponent of
vsm-box.
But it can also be used in other applications that need an input-field
with term+ID lookup.
vsm-autocomplete is a Vue.js-based
input field component,
that a web developer can embed inside one of these:
vsm-box.vsm-autocomplete +
vsm-dictionary-bioportal +
a
webpack setup,vsm-autocomplete-bioportal.<vsm-autocomplete>', which
requires at least a 'vsm-dictionary="..."' attribute.item-select signal is emitted, together with the term, ID,
and other info.vsm-autocomplete supports what vsm-dictionary supports too, i.a.:
string-style-html).To see an interactive demo (that uses example dictionary-data), run:
git clone git@github.com:vsm/vsm-autocomplete.git
cd vsm-autocomplete
npm install
npm start
Here we embed it in another Vue component, e.g. in a MyComp.vue:
<template>
<div class="my-comp">
<vsm-autocomplete
:vsm-dictionary="vsmDictionary"
:autofocus="true"
initial-str="a"
@item-select="onItemSelect"
/>
</div>
</template>
<script>
// 1.) Create a VsmDictionary data source.
import VsmAutocomplete from 'vsm-autocomplete';
import VsmDictionaryLocal from 'vsm-dictionary-local'; // Or any other one.
import cacher from 'vsm-dictionary-cacher'; // Recommended for speed.
var CachedVsmDictionaryLocal = cacher(VsmDictionaryLocal);
var dict = new CachedVsmDictionaryLocal({ // Initialize with demo data:
dictData: [
{ id: 'Dict1',
name: 'Example subdictionary 1',
entries: [
{ id: 'D1:001', terms: ['aaa', 'aasynonym'], descr: 'description' },
{ id: 'D1:002', terms: 'aab', descr: 'descr2' },
{ id: 'D1:003', terms: 'abc', descr: 'descr3' },
{ id: 'D1:004', terms: [{ str: 'acd', style:'i' }], descr: 'descr4' }
]
}
]
});
// 2.) Create a parent component 'MyComp' that embeds a VsmAutocomplete.
export default {
name: 'MyComp',
components: {
'vsm-autocomplete': VsmAutocomplete // Use it as a sub-component of MyComp.
},
data: function() {
return {
vsmDictionary: dict
};
},
methods: {
onItemSelect(match) {
console.log(match.id, match.str, match.descr, JSON.stringify(match.terms));
}
}
};
</script>
<style scoped> /* Add CSS-styling around the vsm-autocomplete */
.my-comp {
width: 200px;
border: 1px solid #ddd;
}
</style>
The example shows that the <vsm-autocomplete> HTML-tag accepts
two types of attributes:
:vsm-dictionary="...", :autofocus="...", and initial-str="...".@item-select="...".An extra 'item-literal' can be shown at the bottom of the autocomplete selection-list.
@item-literal-select event-listener
is attached.vsm-box) can interpret this as a signal that
the user wants to access some more advanced term-search dialog window.:custom-item-literal prop.| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
| vsm-dictionary | Object | true | A subclass of VsmDictionary: an interface to a provider of terms, IDs, styling info, subdictionary info, refTerms and fixedTerms | |
| autofocus | Boolean | false | When true, automatically focuses the input-field at page load | |
| placeholder | String|Boolean | false | • String: shows this placeholder message in an empty input-field | • false/absent: adds none | |
| initial-value | String | '' | The initial content for the input-field | |
| query-options | Object | { perPage: 20 } | Options for filters, fixedTerms, etc., sent along with calls to vsmDictionary.getMatchesForString() | |
| max-string-lengths | Object | { str: 40, strAndDescr: 70 } | Limits the length of matches' str and descr shown in list-items(in number of characters) | |
| fresh-list-delay | Number | 0 | Prevents selection of matches in the list, until this amount of milliseconds has passed | |
| custom-item | Function|Boolean | false | • Function: returns HTML-content for each part of normal list-items (see below) | • false/absent: default content is used | |
| custom-item-literal | Function|Boolean | false | • Function: returns HTML-content (see below) for the item-literal | • false/absent: the default item-literal is used |
Notes:
placeholder is hidden when the input-field is focused.query-options's perPage sets the length of the selection-list.
query-options's idts specifies a list of fixedTerms (see
vsm-dictionary's spec), only if this autocomplete component should use any.max-string-lengths's strAndDescr sets the maximum length
of an already length-trimmed str, plus its descr.fresh-list-delay (of e.g. a few 100 milliseconds),
one can delay when the list starts to respond, and prevent an impatient user
from mistakenly Entering/selecting an item that only just appeared.custom-item and custom-item-literal functions are described in the
"Customized content" section, further below.| Event | Output | Description (-> output) |
|---|---|---|
| focus | When the input-field gets the page focus | |
| blur | When the input-field loses the focus | |
| input-change | String | When the input-field's content changes, after trimming (-> the latest value, trimmed) |
| input | String | When the input-field's content changes (-> the latest value) |
| key-esc | When Esc is pressed, while the selection-list is closed | |
| key-bksp | When Backspace is pressed, while the input-field is empty | |
| key-ctrl-enter | When Ctrl+Enter is pressed, while the input-field has no string-codes | |
| key-shift-enter | When Shift+Enter is pressed | |
| key-tab | String | When Tab or Shift+Tab is pressed (-> modifier key: '' or 'shift') |
| dblclick | When the input-field is double-clicked | |
| mouseover-input | When the input-field is mouse-hovered (not the selection-list) | |
| list-open | When the selection-list opens | |
| list-close | When the selection-list closes | |
| item-active-change | false|Object|String | When the active item in the selection-list changes -> • false: none (on list-close) | • Object: a match-object from VsmDictionary | • String: the literal input string (for item-literal) |
| item-select | Object | When an item is selected (-> a match-object from VsmDictionary) |
| item-literal-select | String | When the item-literal is selected (-> the literal input string) |
Notes:
@key-tab listener is attached,
vsm-autocomplete prevents the default behaviour:@key-esc, @key-bksp,
and @key-ctrl-enter.Ctrl+Enter to convert certain string-codes in the input
(if any) to special characters, e.g. '\beta' to β.key-ctrl-enter, which an external
listener may act upon.@item-select is likely the most important event.This is the architecture of vsm-autocomplete in terms of its own subcomponents:
VsmAutocomplete
├── TheInput
├─┬ TheList
│ ├── ListItem (multiple items)
│ └── ListItemLiteral (only 1, or 0)
└── TheSpinner
If this autocomplete component should take into account some fixedTerms, i.e.
if it is given some queryOptions.idts[] (see vsm-dictionary's spec) as prop,
then it makes sure that this fixedTerm data is pre-loaded in the given
vsmDictionary, before making any requests for matching strings to it.
See the tests for details.
They are easiest to read in the following, bottom-up order:
The selection-panel items are given a default content like:
match-string (description) (dictionary-ID),
and each of the three parts may show extra info when the user mouse-hovers it;
e.g. if "(descri...)" was cut short, then hovering shows the full description.
Any of these parts can be customized by giving a customizing function as the
custom-item prop.
• E.g.: for items that represent a match from a Human Genes
subdictionary, it could insert a list of gene-name synonyms in the description
part.
• Or: for a list of items representing a mix of matches
from a Human Genes and a Mouse Genes subdictionary resp.,
it could add an image of the species so that users can
more quickly distinguish between identically named matches.
customItem() (if given) is called during the construction of each ListItem.
It is called with one argument: an Object with useful properties, representing
useful information for building a custom ListItem:
customItem(data):
data: {Object}:
item: the complete 'match'-object that this ListItem represents.
(The 'match' data-type is described in VsmDictionary's
spec).searchStr: the string that the user typed to find this match.maxStringLengths: the max-string-lengths prop that was set
on this <vsm-autocomplete>.queryOptions: the prop query-options that was set
on this <vsm-autocomplete>.queryOptions.filter.dictIDs[], a multi-purpose
customization function could detect if this particular autocomplete is
combining gene-IDs from multiple species, and if so, add an icon (image of
the species) in front of gene-names for clarity).dictInfo: the info-object of the subdictionary
from which this match came (which contains customItem()).vsmDictionary: the VsmDictionary instance being used.vsmDictionary.numberMatchConfig details).strs: the default content for the different parts of the ListItem.customItem() does not change it.
str: the match's term-string, which is matchObj.str,maxStringLengths.str,matchObj.style's custom CSS-styling already applied.descr: the match's description, which is matchObj.descr,maxStringLengths.strAndDescr.info: the dictionary-ID, which is matchObj.dictID;strTitle: the str-part's HTML 'title=".."' attribute,str was length-trimmed, then this is matchObj.str, else empty).descrTitle: the descr-part's HTML 'title=".."' attribute.descr was length-trimmed, then this is matchObj.descr, else empty).infoTitle: the info-part's HTML 'title=".."' attribute.matchObj.id and dictInfo.name).extra: an extra part that is added at the end of the ListItem,
and which is empty by default.customItem() must return an Object like its argument data.strs.
It may simply return the given strs object, after directly modifying just
those properties it needs to.
customItem: data => { if (data.item.dictID == 'X') data.strs.descr += '!'; return data.strs; }The item-literal can be customized by giving a customizing function as the
custom-item-literal prop.
customItemLiteral() (if given) is called during the construction of a
ListItemLiteral.
It is called with one argument: an Object with useful properties:
customItemLiteral(data):
data: {Object}:
searchStr: the string that the user typed in TheInput.maxStringLengths: the max-string-lengths prop that was set
on this <vsm-autocomplete>.strs: the default content for the different parts of the ListItemLiteral
(similar to customItem's data.strs):
str: the default (text/HTML) content for the ListItemLiteral, which is:max-string-lengths.strTitle: its HTML-element's 'title=".."' attribute,
which appears on mouse-hover.customItemLiteral() must return an Object like its argument data.strs.
It may simply return the given strs object, after directly modifying just
those properties it needs to.
customItemLiteral: data => { data.strs.strTitle = ''; return data.strs }One can change the look of a <vsm-autocomplete> component by overriding
its CSS-classes.
As an example, the following 'CSS skin' makes everything a bit larger:
vsm-autocomplete-large.css.
This project is licensed under the AGPL license - see LICENSE.md.
FAQs
Vue-component for term+ID lookup based on a vsm-dictionary
The npm package vsm-autocomplete receives a total of 29 weekly downloads. As such, vsm-autocomplete popularity was classified as not popular.
We found that vsm-autocomplete demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Four npm packages disguised as cryptographic tools steal developer credentials and send them to attacker-controlled Telegram infrastructure.
Security News
Ruby maintainers from Bundler and rbenv teams are building rv to bring Python uv's speed and unified tooling approach to Ruby development.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.