From c0e7f53173d1ccad37cbe019b7924f8d89087ae9 Mon Sep 17 00:00:00 2001 From: Olga Bulat Date: Wed, 19 Jul 2023 20:30:29 +0300 Subject: [PATCH] Additional search views implementation plan --- ...ementation_plan_additional_search_views.md | 263 ++++++++++++++++++ 1 file changed, 263 insertions(+) create mode 100644 documentation/projects/proposals/additional_search_views/20230719-implementation_plan_additional_search_views.md diff --git a/documentation/projects/proposals/additional_search_views/20230719-implementation_plan_additional_search_views.md b/documentation/projects/proposals/additional_search_views/20230719-implementation_plan_additional_search_views.md new file mode 100644 index 00000000000..9e15c40fbb0 --- /dev/null +++ b/documentation/projects/proposals/additional_search_views/20230719-implementation_plan_additional_search_views.md @@ -0,0 +1,263 @@ +2023-07-20 Implementation Plan: Additional Search Views + +**Author**: @obulat + + + + +## Reviewers + + + +- [ ] TBD +- [ ] TBD + +## Project links + + + +- [Project Thread](https://github.com/WordPress/openverse/issues/410) +- [Project Proposal](https://docs.openverse.org/projects/proposals/additional_search_views/20230424-project_proposal_additional_search_views.html) + +## Overview + + + +This plan describes the changes that need to be added on the frontend: the new +components, pages and store. + +## Expected Outcomes + + + +Three collection pages are added to Openverse: + +- items with the selected tag +- items from the selected source (provider) +- items by the selected creator. The pages re-use the existing image grid and + audio collection views and can load more images or audio items on the Load + more button click. The single result pages are updated to add the links to + these pages, as seen in the Figma mockups: [link to Figma mockup] + +## Outlined Steps + + + +### Page changes + +#### Create a page for `tag` / `creator` /`source` collections. + +Nuxt allows creating nested dynamic routes like +`/pages/_collection/_mediaType/_term`. + +Here, the collection can be `tag`, `creator` or `source`. `mediaType` can be one +of the supported media types (currently, `image` and `audio`). `term` refers to +the actual value of the tag, creator or source name. + +This page should use the +[`validate` method](https://v2.nuxt.com/docs/components-glossary/validate/) to +make sure that the `collection`, `searchType` and `term` `params` are valid. + +``` +`validate({ params, $pinia }): { +const { collection, searchType, term } = params +``` + +This page should also update the state (`searchType`, `searchTerm` and +`searchBy` filter) in the `search` store and handle fetching using +`mediaStore`'s `fetchMedia` method in the `useFetch` hook. Since it is not +possible to change the path or query parameters from this page client-side, +fetching can be much simpler than on the current search page (that has to watch +for changes in the route and fetch if necessary). + +This page should have the common header (title, button - link to the source +external URL or the creator URL, and the summary of item counts in the +collection), and a nested component: the image grid or the audio collection. + +### New and updated components + +#### Extract the `VAudioCollection` component + +Currently, it is not possible to reuse the audio collection from the audio +search result page because it is a part of the `audio.vue` page. We should +extract the part that shows the loading skeleton, the column of `VAudioTrack` +rows and the Load more section. This component will be reused in the audio +search page and on the Additional search views. One thing that I'm not sure +about here is whether the analytics events should stay the same and be sent from +all pages - or if we should somehow differentiate the events coming from +different search views. + +#### Add a `VCollectionHeader` component + +Figma links: +[creator desktop](https://www.figma.com/file/niWnCgB7K0Y4e4mgxMrnRC/Additional-search-views?type=design&node-id=1200-56323&mode=design&t=pN0PPAzlKQEKT9tJ-4), +[creator mobile](https://www.figma.com/file/niWnCgB7K0Y4e4mgxMrnRC/Additional-search-views?type=design&node-id=1200-56362&mode=design&t=suLIyJHNmZrM0mPH-4), +[source desktop](https://www.figma.com/file/niWnCgB7K0Y4e4mgxMrnRC/Additional-search-views?type=design&node-id=1200-56381&mode=design&t=suLIyJHNmZrM0mPH-4), +[source mobile](https://www.figma.com/file/niWnCgB7K0Y4e4mgxMrnRC/Additional-search-views?type=design&node-id=1200-56421&mode=design&t=suLIyJHNmZrM0mPH-4), +[tag desktop](https://www.figma.com/file/niWnCgB7K0Y4e4mgxMrnRC/Additional-search-views?type=design&node-id=1216-58402&mode=design&t=suLIyJHNmZrM0mPH-4), +[tag mobile](https://www.figma.com/file/niWnCgB7K0Y4e4mgxMrnRC/Additional-search-views?type=design&node-id=1200-56457&mode=design&t=suLIyJHNmZrM0mPH-4) + +The header should have an icon (tag, creator or source), the name of the +tag/creator/source. For source and the creator, there should be an external link +button. + +The header should also display the number of results, "251 audio files with the +selected tag", "604 images provided by this source", "37 images by this creator +in Hirshhorn Museum and Sculpture Garden". + +#### Add VCreatorLink component + +The "by creator" line under the main item on the single result page should be +replaced with a `VCreatorLink` component - a wrapper over `VButton` with a link +to the localized "creator" collection page. + +#### Add VSourceLink component + +Both the source and the provider should be replaced with `VSourceLink` component +that links to the `source` page. This component is also a wrapper over `VButton` +component. + +#### Update VMediaTag component to be a `VButton` wrapping a `VLink` + +Each `VMediaTag` should be a `VButton` with `as="VLink"` and should link to the +localized page for the tag collection. Figma link: +https://www.figma.com/file/niWnCgB7K0Y4e4mgxMrnRC/Additional-search-views?type=design&node-id=1200-56515&mode=design&t=nCX20BtJYqMOFAQm-4 +[VMediaTag component](https://github.com/WordPress/openverse/blob/c7b76139d5a001ce43bde27805be5394e5732d1a/frontend/src/components/VMediaTag/VMediaTag.vue) +`{{tag}}`. +It should accept `href` as a prop. + +### Other interface changes + +#### Update the "by" area of the single result page + +The "by creator" line should be replaced with a section that is +horizontally-scrollable on mobile, and contains the `VCreatorLink` and +`VSourceLink` components. + +#### Update links in the "information" section + +Add external link icon to the provider link; add creator link with external link +icon The links to creator in the image and audio single result pages should have +an "external link" icon. +[image creator link](https://github.com/WordPress/openverse/blob/35f08e5710d59f6c10f0cf54103fcce151adfefe/frontend/src/pages/image/_id/index.vue#L62-L73) +and +[audio creator link](https://github.com/WordPress/openverse/blob/35f08e5710d59f6c10f0cf54103fcce151adfefe/frontend/src/components/VAudioTrack/layouts/VFullLayout.vue#L32-L41). +Audio creator link should also be updated to match the image creator link. It +should be a conditional component: `VLink` if the `creator_url` is truthy and +`span` if the `creator_url` is falsy. + +Currently, the `foreign_landing_url` is linked to the "source" in the image page +and "provider" in the audio page. The audio page should be updated to match the +image page: the `foreign_landing_url` link should be added to the "source", not +provider. +[Audio provider link](https://github.com/WordPress/openverse/blob/35f08e5710d59f6c10f0cf54103fcce151adfefe/frontend/src/components/VAudioDetails/VAudioDetails.vue#L61C1-L63), +[image source link](https://github.com/WordPress/openverse/blob/35f08e5710d59f6c10f0cf54103fcce151adfefe/frontend/src/components/VImageDetails/VImageDetails.vue#L26-L28) + +### Store changes + +#### Update the `searchBy` filter in the `search` store + +Currently, this filter is shaped as other filters: it is a list of objects with +`code`, `name` and `checked` properties. This is a possible value now: `{ +searchBy: { code: "creator", name: "filters.searchBy.creator", checked: true }}. + +Since this filter is mutually exclusive (you cannot search by both the creator +and the tag, for example), this shape is very difficult to update. + +It is better to set the `searchBy` filter to have one of the possible values: +`{ searchBy: }`. + +We should also create a new method, `setSearchBy`, in the `search` store, that +would allow directly set the `searchBy` filter value. + +### Analytics changes + +I am not sure what events we want to add, if any. Should we add `_CLICKED` +events for the new views, or would page views be sufficient? + +Should we add a new `SELECT_COLLECTION_ITEM` event similar to +`SELECT_SEARCH_RESULT`? + +The clicks on external creator link in the `VCollectionHeader` should be tracked +as `VISIT_CREATOR_LINK` events. We don't have a special event for visiting +source, should we add one, or should they be tracked as generic +`VISIT_EXTERNAL_LINK`? + +### Tests + +We should add visual-regression tests for the new views. To minimize flakiness +due to slow loading of the images, we should probably use the +`{ filter: brightness(0%); }` trick for the images on the page. + +The search store tests should be updated to reflect the changes to the filters. + +## Dependencies + +### Infrastructure + + + +These views potentially might cause more load on our infrastructure due to +increase in scraping activity. + +### Tools & packages + + + +No new tools or packages are necessary. + +### Other projects or work + + + +## Design + + + +Figma designs in the dev mode: +https://www.figma.com/file/niWnCgB7K0Y4e4mgxMrnRC/Additional-search-views?node-id=22%3A13656&mode=dev + +## Parallelizable streams + + + +The work on components (`VCreatorLink`, `VSourceLink`, `VMediaTag`), and on the +search store changes can be parallelized. + +We should create a separate branch for this work because adding the links to the +collection pages on the single result pages (`VCreatorLink`, `VSourceLink`, +`VMediaTag`) before the collection pages are ready is not possible. + +## Blockers + + + +The main blocker could be the maintainer capacity. If the "creator" API call is +not easy to construct (since we need to combine both the creator and the +provider), this might also be a blocker. + +## Accessibility + + + +We should make sure that the search titles are accessible, and the pages clearly +indicate the change of context. + +## Rollback + + + +If we work on a separate branch, it would be easy to rollback by reverting the +branch merge commit. + +## Risks + + + +The biggest risk I see is that this project might be seen as an "invitation" to +scraping. Hopefully, the work on providing the dataset would minimize such +risks. + +## Prior art + +