# Technical documentation ## Components ### ListingLists #### Description This component renders the view of the application, allows to choose any list & displays the data of the current list. Usage example: ``` listing-lists( :bookmark-url="https://www.example.com/e/1?m=1&slide=#slide1" :http="axios" :shared-url="https://www.example.com/list" :stored-list="[{}]" :open-list-id="1" :user-id="3" @uppdate-list="updateList" @delete-event="refreshEventsInLists" @navigate-to-bookmark="navigateToBookmark" ) ``` #### Props | Name | Type | Required | Description | | ------------ | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | bookmark-url | String | false | URL of current slide in the context of a XAPI module | | http | Function | true | Promise-based HTTP Client including logic to add credentials (axios is recommended). This will be used in `API.service.js` to perform requests | | shared-url | String | true | URL of the page to render the public list in the library component `listing-shared-list` | | stored-list | Array | false | List of objects corresponding to each list | | open-list-id | Number | false | Id of the list to be opened | | user-id | Number | true | Id of the current user | #### Events @update-list (Emits a flag when the item was successfully added) @delete-event (Emits a flag when any wish list or event added in any wish list was removed) @navigate-to-bookmark (Emits the saved note url when the chip button is clicked) #### HTTP Requests It uses ***GET*** request to fetch the lists of the current user. It uses ***GET*** request to fetch the notes of the current list. It uses ***POST*** request to create lists. It uses ***PATCH*** request to edit lists. It uses ***DELETE*** request to remove lists. ### ListingShared #### Description This component allows to render any public list as read only in a custom page. Usage example: ``` listing-shared(:http="axios" :slug="XXXXXXXXX") ``` #### Props | Name | Type | Required | Description | | ---- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | http | Function | true | Promise-based HTTP Client including logic to add credentials (axios is recommended). This will be used in `API.service.js` to perform requests | | slug | String | false | ID of the selected public list that is send in the parameters in a HTTP request to load a public list | #### Events (This component does not have any emit) #### HTTP Requests It uses ***GET*** request to fetch the items from a public list. ### ListingAddItemList #### Description This component allows to render a selector that allow to add the current event into a list. Usage example: ``` listing-add-item-list( :fetching-list="false" :http="axios" :refresh-events-in-lists="getRefreshEventsInLists" :list-item="course" :stored-list="[{}]" :user-id="3 @item-added="newItemAdded" @update-list="updateList" @fetching-list="fetchList" @refresh-lists="refreshEventsInLists" ) ``` #### Props | Name | Type | Required | Description | | ----------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | fetching-list | Boolean | false | Flag to control the `GET request to fetch the list`, if its set to **true**, then the request its omitted and load the results from prop `:stored-list` | | http | Function | true | Promise-based HTTP Client including logic to add credentials (axios is recommended). This will be used in `API.service.js` to perform requests | | refresh-events-in-lists | Boolean | false | Flag to notify the application to trigger the `GET request to fetch if the current event itd added in any list` | | list-item | Object | true | Object data of the current event. It must be mapped with the properties: "title", "image" & "url" | | stored-list | Array | false | Set the internal list to the value of this prop | | user-id | Number | true | Id of the current user | #### Events @item-added (Emits a flag when the item was successfully added) @update-list (Emits the response of the `GET list request`) @fetching-list (Emits a flag to handle the `GET list request` to don't send the same request multiple times) @refresh-lists (Emits a flag to notify the app to handle the `GET list request with url parameter` to fetch if the current event itd added in any list) #### HTTP Requests It uses ***GET*** request to fetch the items from a list. It uses ***GET*** request to fetch the lists. It uses ***GET*** request to fetch if the current event is already added in any list. It uses ***POST*** request to add an item to a lists. ### ListingAddItemListIconDesign #### Description This component allows to render a button that allow to add the current event into the **first** list. It extends from the component `ListingAddItemList` Usage example: ``` listing-add-item-list-icon-design( add-icon="mdi-heart-plus" already-added-icon="mdi-heart-multiple" :fetching-list="false" :http="axios" icon-color="#ff0000" :icon-size="30" :refresh-events-in-lists="getRefreshEventsInLists" :list-item="course" :stored-list="[{}]" :user-id="3 @item-added="newItemAdded" @update-list="updateList" @fetching-list="fetchList" @refresh-lists="refreshEventsInLists" ) ``` #### Props | Name | Type | Required | Description | | ----------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | add-icon | String | false | Icon to display while the current event its not stored in the wish list | | already-added-icon | String | false | Icon to display while the current event its stored in any wish list | | fetching-list | Boolean | false | Flag to control the `GET request to fetch the list`, if its set to **true**, then the request its omitted and load the results from prop `:stored-list` | | http | Function | true | Promise-based HTTP Client including logic to add credentials (axios is recommended). This will be used in `API.service.js` to perform requests | | icon-color | String | false | Color of the icons to add an event | | icon-size | Number | false | Size of the icons | | refresh-events-in-lists | Boolean | false | Flag to notify the application to trigger the `GET request to fetch if the current event itd added in any list` | | list-item | Object | true | Object data of the current event. It must be mapped with the properties: "title", "image" & "url" | | stored-list | Array | false | Set the internal list to the value of this prop | | user-id | Number | true | Id of the current user | #### Events @item-added (Emits a flag when the item was successfully added) @update-list (Emits the response of the `GET list request`) @fetching-list (Emits a flag to handle the `GET list request` to don't send the same request multiple times) @refresh-lists (Emits a flag to notify the app to handle the `GET list request with url parameter` to fetch if the current event itd added in any list) #### HTTP Requests It uses ***GET*** request to fetch the items from a list. It uses ***GET*** request to fetch the lists. It uses ***GET*** request to fetch the events from the **first** list. It uses ***GET*** request to fetch if the current event is already added in any list. It uses ***POST*** request to add an item to a lists. ### Other internal components | Name | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------- | | `AddNewListBtn` | Display a button to create new lists. Emits the newly created list as `@new-list`. | | `CreateNewListModal` | Display a modal to create new lists. Emits `@update:displayModal` & `@new-list` to `newListBtn` component. | | `OptionsBtn` | Display a button and a menu with some options and emits the selected option. | | `DeleteModal` | Display a modal to remove the current list or note. Emits `close` & `@delete` | | `EditModal` | Display a modal to edit the current list or a note. Emits `close` & `@edit` | | `ListWrapper` | Provide common variables & functions that will be inherited to `NotesList` or `WishList`. Emits `@edit-error` | | `NotesList` | Display the notes of the current selected list. | | `WishList` | Display the events of the current selected list. | ## Internationalization Nuxt I18n is used. Some files already translated are located in the directory `lib/i18n`. Those files can be directly imported in the base project using `i18n.mergeLocaleMessage`: ``` this.$i18n.mergeLocaleMessage(this.$i18n.locale, require('../../lib/i18n/' + this.$i18n.locale + '/views')) ``` ## Prerequisites This library uses the following dependencies: * [Pugjs](https://pugjs.org/api/getting-started.html) instead of plain HTML for templating * [Vuetifyjs](https://vuetifyjs.com/en/) As UI design framework based on Material * [NuxtJS](https://nuxtjs.org/) 2 (use in Vuejs or Nuxt 3 on your own risk) * [Lodash](https://lodash.com/) Library which provide functions for working with arrays, numbers, objects, strings * [MomentJs](https://momentjs.com/) Library to parse, validate, manipulate, and display date/time * [VueSlickSort](https://www.npmjs.com/package/vue-slicksort) Library to perform drag and drop of items in a list ## Development * Clone the repository `git clone https://gitlab.com/eduplex-api/nuxt-listing.git` in the root of any Nuxtjs app. * Import statically components manually when needed using `import { ListingLists } from '../../nuxt-listing/index'` * Import dynamically components manually using `ListingShared: () => import('../../nuxt-listing/shared')` * Build your project as usual