@oarepo/invenio-api-vuex
Advanced tools
A set of vuex store modules and route utils to work with Invenio 3 REST API.
A set of vuex store modules and route utils to work with Invenio 3 REST API.
yarn add @oarepo/invenio-api-vuex
import Vue from 'vue'
import InvenioAPI from '@oarepo/invenio-api-vuex'
Vue.use(Vuex)
const store = new Vuex.Store({})
Vue.use(InvenioAPI, {
store: store,
apiURL: '/api'
})
yarn add @oarepo/vuex-preloader
To use the library together with url preloader (recommended way), add the following configuration to your routes:
// routes.js
import { routerCollectionList, routerCollection, routerRecord } from '@oarepo/invenio-api-vuex'
export default [
{
path: '/',
redirect: '/collections'
},
routerCollectionList({
path: '/collections',
component: Collections
}),
routerRecord({
path: '/:collectionId/:recordId',
component: Record
}),
routerCollection({
path: '/:collectionId',
component: Collection,
props: query()
})
]
See src/router.js for details
To simplify facet & query handling, record collection can be used together with
@oarepo/vue-query-synchronizer. Add props: query() into router path
as above and see the example at src/components/Collection.vue
Store modules are implemented with vuex-class-modules.
Use this store module only if invenio-oarepo-ui is installed on the backend.
This module returns a list of contained data models/collections together
with extra information about the collections, such as:
This module is registered under the name 'oarepoCollectionList' and is not loaded automatically unless registered in the router.
import { routerCollectionList } from '@oarepo/invenio-api-vuex'
routes = [
routerCollectionList({
name: 'root',
path: '/',
component: MyApp,
children: [...]
})
]
To skip automatic loading and load it manually when needed,
invoke oarepoCollectionList/load action on the store.
// plain old js vuex
{
computed: {
...mapState({
collections: state => state.oarepoCollectionList.collections
})
}
methods: {
...mapActions([
'oarepoCollectionList.reload',
])
reload () {
this['oarepoCollectionList.reload']()
}
}
}
// with with vuex-class-modules and vue-class-component
@Component({})
class MyComponent extends Vue {
get collections() {
return this.$oarepo.collections.collections
}
reload() {
return this.$oarepo.collections.reload()
}
}
Template:
<list>
<ul v-for="collection in collections" :key="collection.code">
<p>{{ collection.title['en-us'] }}</p>
<p>{{ collection.description['en-us'] }}</p>
</ul>
</list>
See https://github.com/oarepo/invenio-oarepo-ui module for data structure details.
stateOne of State.INVALID, State.LOADING, State.LOADED
collectionsAn array of descriptions of collections received from the server
visibleCollectionsAn array of descriptions of collections received from the server that are not marked as hidden
load, reloadFetches the list of collections from the server
Collection module is responsible for loading a single collection of
records (listing of records) and creating a new record. The module
is mapped at oarepoCollection
// plain old js vuex
{
computed: {
...mapState({
records: state => state.oarepoCollection.records,
facets: state => state.oarepoCollection.facets,
})
}
methods: {
...mapActions([
'oarepoCollection.load',
])
load (collectionId) {
this['oarepoCollection.load']({collectionId})
}
}
}
// with with vuex-class-modules and vue-class-component
@Component({})
class MyComponent extends Vue {
get items() {
return this.$oarepo.collection.items
}
get facets() {
return this.$oarepo.collection.facets
}
load(collectionId) {
return this.$oarepo.collection.load({collectionId})
}
}
stateOne of State.INVALID, State.LOADING, State.LOADED
collectionIdID of the currently loaded collection
recordsA list of loaded records as returned from the elasticsearch. Each record looks like:
{
"created":"2019-12-01T23:48:10.851166+00:00",
"id":"32861b6d-1655-4c61-9914-80c5f9a19838",
"links":{
"self":"https://restaurovani.vscht.cz/api/drafts/restorations/objects/32861b6d-1655-4c61-9914-80c5f9a19838"
},
"metadata":{
"$schema":"https://restaurovani.vscht.cz/schemas/draft/krokd/restoration-object-v1.0.0.json",
},
"revision":31,
"updated":"2019-12-12T12:38:25.138961+00:00"
}
facetsA list of loaded facets. Each facet looks like:
{
"element": {}, // original facet element
"facets": [ // transformed and translated values
{
"count": 73,
"label": "textil",
"value": "textil"
},
{
"count": 11,
"label": "sklo",
"value": "sklo"
},
{
"count": 92,
"label": "kovy",
"value": "kovy"
},
{
"count": 18,
"label": "keramika",
"value": "keramika"
}
],
"label": "category", // translated label
"code": "category",
// type of the facet, will always be 'buckets' unless custom aggregation extractor is provided
"type": "buckets"
}
See Configuration section of this readme for details how to configure extractors and translators.
totalPagesTotal pages available
responseThe last axios response without any modifications
queryParamsQuery params (after ?) passed to the API call
reloadNeededThis state parameter works together with vuex-preloader. Set it to true to force reloading of the state on the next route change
load({query, collectionId})Fetches apiURL/${collectionId}?{query}
reloadReloads the state
transformTransforms the remembered response and refills facets and records. This action
is useful for example when locale is changed to translate facets to the new locale.
create({metadata, storeModule})Calls HTTP post on collection url to create a new record. Returns the created item. If storeModule is specified, the loaded record is fed to the storeModule (instance of RecordModule type). Returns json of the created record.
This call sets the reloadNeeded state so that the store is reloaded on the next
route change when vuex-preloader is used (in case the created record falls into
the current page).
Record module is responsible for loading, updating, deleting a single record.
The module is mapped at oarepoRecord
// plain old js vuex
{
computed: {
...mapState({
metadata: state => state.oarepoRecord.metadata,
links: state => state.oarepoRecord.links,
created: state => state.oarepoRecord.created,
updated: state => state.oarepoRecord.updated,
// original response.data
record: state => state.oarepoRecord.record,
})
}
methods: {
...mapActions([
'oarepoRecord.load',
])
load (collectionId, recordId) {
this['oarepoCollection.load']({collectionId, recordId})
}
}
}
// with with vuex-class-modules and vue-class-component
@Component({})
class MyComponent extends Vue {
get metadata() {
return this.$oarepo.record.metadata
}
load(collectionId, recordId) {
return this.$oarepo.record.load({collectionId, recordId})
}
}
stateOne of State.INVALID, State.LOADING, State.LOADED
collectionIdID of the currently loaded collection
recordIdID of the currently loaded record
metadataThe metadata section of the response
linksThe links section of the response
createdCreated timestamp
updatedUpdated timestamp
recordRaw, unparsed record
load({collectionId, recordId})Loads the record and returns it
reloadReloads the last loaded record
patch(json)Issues patch command on the repository. json is a json-patch payload
saveSaves (via HTTP POST) the current record and persists any modifications
import InvenioAPI from '@oarepo/invenio-api-vuex'
Vue.use(InvenioAPI, {
store,
apiURL: '/api',
defaultPageSize: 10,
i18n (x) { return x },
defaultFacetOptions: new FacetOptions({}),
facetOptions: {},
defaultRecordPreprocessors: new CallbackList(),
recordPreprocessors: {},
defaultListRecordPreprocessors: new CallbackList(),
listRecordPreprocessors: {},
collectionListMixins: [],
collectionMixins: [],
recordMixins: [],
})
defaultPageSizePage size to use when no ?size is given
i18nA function taking a string (key) and converting it to translated msg
defaultFacetOptions, facetOptionsFacet options to be used for facet extraction and processing. For a collection
with id collectionId facetOptions[collectionId] are tried and if undefined
defaultFacetOptions are used.
defaultRecordPreprocessors, recordPreprocessorsPreprocessors called when a record is fetched from repository. For a collection
with id collectionId recordPreprocessors[collectionId] are tried and if undefined
defaultRecordPreprocessors are used.
Preprocessor is a function with a signature preprocess(response.data, { record: RecordModule })
defaultListRecordPreprocessors, listRecordPreprocessorsPreprocessors called when a listing of records is fetched from repository.
For a collection
with id collectionId listRecordPreprocessors[collectionId] are tried and
if undefined defaultListRecordPreprocessors are used.
Preprocessor is a function with a signature
preprocess(record, { collection: CollectionModule })
Facet processing takes place in two phases.
During the first phase, for each node of aggregations tree a facet extractor
is called to extract facets.
During the second phase all the facets might be modified by facet preprocessors, for example to add human-readable labels to facet values.
The configuration of this process is contained in FacetOptions class.
A class containing options for handling collection facets:
class FacetOptions {
/*
* A list of facet extractors. See below for details
*/
facetExtractors = new CallbackList(bucketExtractor)
/*
* A list of facet preprocessors. See below for details
*/
facetPreprocessors = new CallbackList(facetTranslator)
translation = {
/*
Translate facet titles by default. Can be overriden via translatedTitles
*/
defaultTranslateTitles: TranslationOptions.NO_PREFIX,
/*
Translate facet values by default. Can be overriden via translatedValues
*/
defaultTranslateValues: TranslationOptions.NO_TRANSLATION,
/*
A dictionary from facet name to Union[TranslationOptions, false, str].
not present: use defaultTranslateTitles
NO_TRANSLATION: do not translate the name to title
NO_PREFIX: use facet name as translation key
any other string: use the given string as a translation key
*/
translateTitles: {},
/*
A dictionary from facet name to Union[TranslationOptions, false, str].
not present: use defaultTranslateValues
NO_TRANSLATION: do not translate the facet value's label
NO_PREFIX: use facet's label as translation key
FACET_NAME_PREFIX: use ${facet_name}.${facet.value.label} as translation key
any other string: use ${this_string}.${facet.value.label} as translation key
*/
translateValues: {}
}
/*
* Sets props above. If parent is not null, it is an instance of FacetOptions and its props
* are taken as default.
*/
constructor ({
parent,
facetExtractors, facetPreprocessors,
defaultTranslateTitles, defaultTranslateValues,
translateTitles, translateValues
}) {}
}
The extractor decides if the node represents a facet or not and returns its representation.
It is a function with signature extractor({ node, path }), node being the current
node in the json tree and path a reversed array of {code, element} (root comes last),
where code is the key under which the element is stored.
If the extractor decides that the node represents facet, it returns it in the form of:
return {
type: "facet type",
code: path[0].code,
element: node,
// any other elements, such as
facets: [
{
label: 'London',
value: 'london',
count: 30
},
]
}
If the extractor does not recognize the element as facet bearer, it returns undefined.
The default implementation contains a bucketExtractor. To add yours, create new FacetOptions:
new FacetOptions({
facetExtractors: [myFacetExtractor1, myFacetExtractor2]
})
// or
new FacetOptions({
facetExtractors: myFacetExtractor
})
Facet preprocessor is a function with signature
facetPreprocessor(facets, { facetOptions, i18n, collection }). It should transform
the facets array (with items returned by the extractors) and return the transformed array.
The default implementation converts facet codes into labels as described below.
To add your own preprocessors, create an instance of FacetOptions with the preprocessors:
new FacetOptions({
facetPreprocessors: [myFacetPreprocessor1, myFacetPreprocessor2]
})
// or
new FacetOptions({
facetPreprocessors: myFacetPreprocessor
})
This block configures the default facetTranslator. Using config.i18n(key),
the translator converts facet code and facet values into a human readable string.
The description below will use the following facet as returned from facet extractor:
facet = {
type: "buckets",
code: 'cities',
element: {/*...*/},
facets: [
{
value: 'london',
count: 30
},
]
}
Options:
defaultTranslateTitles, translateTitlestranslateTitles[facet.code] specifies how facet titles will be obtained.
If it is not defined, defaultTranslateTitles setting will be used.
Default is TranslationOptions.TRANSLATE.
It can be set to either TranslationOptions.NO_TRANSLATION, TranslationOptions.TRANSLATE or an arbitrary string.
If set to TranslationOptions.NO_TRANSLATION, the translated facet will look like:
facet = {
label: 'cities', // copied from code
// all other options
}
TranslationOptions.TRANSLATE:
facet = {
label: i18n('cities'),
// all other options
}
arbitrary string ('abc.'):
facet = {
label: i18n('abc.cities'),
// all other options
}
defaultTranslateValues, translateValuesWorks similarly as titles, but for facet value labels.
translateValues[facet.code] specifies how facet titles will be obtained.
If it is not defined, defaultTranslateValues setting will be used.
Default is TranslationOptions.NO_TRANSLATION.
It can be set to either TranslationOptions.NO_TRANSLATION, TranslationOptions.TRANSLATE, TranslationOptions.FACET_CODE_PREFIX or an arbitrary string.
If set to TranslationOptions.NO_TRANSLATION, the translated facet will look like:
facet = {
code: 'cities',
facets: [
{
value: 'london',
label: 'london', // copied from value
count: 30
}
],
// rest of facet
}
TranslationOptions.TRANSLATE:
facet = {
code: 'cities',
facets: [
{
value: 'london',
label: i18n('london'), // i18n of value
count: 30
}
],
// rest of facet
}
TranslationOptions.FACET_CODE_PREFIX:
facet = {
code: 'cities',
facets: [
{
value: 'london',
label: i18n('cities.london'), // i18n of facet.code + '.' + value
count: 30
}
],
// rest of facet
}
arbitrary string ('abc.'):
facet = {
code: 'cities',
facets: [
{
value: 'london',
label: i18n('abc.london'), // i18n of facet.code + '.' + value
count: 30
}
],
// rest of facet
}
The provided stores can be extended with custom mixin classes to add extra properties/mutations/actions. To do so, provide functions that return a new mixin class inherited from the provided superclass. This pattern is described at https://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/
An example:
import { Action, Mutation } from 'vuex-class-modules'
Vue.use(InvenioAPI, {
store,
apiURL: '/api',
collectionListMixins: [
(superclass) => class extends superclass {
num = 1
@Mutation
setNumber(num) {
this.num = num
}
@Action
async numAction() {
return new Promise((resolve) => {
setTimeout(() => {
this.num = 3
resolve()
}, 10)
})
}
}
],
})
Now, num is defined as a getter on $oarepo.collectionList and mutations/actions
are added to the store module.
FAQs
A set of vuex store modules and route utils to work with Invenio 3 REST API.
We found that @oarepo/invenio-api-vuex demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 4 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.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.
Security News
AGENTS.md is a fast-growing open format giving AI coding agents a shared, predictable way to understand project setup, style, and workflows.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.