Coder Social home page Coder Social logo

pressbooks-book-directory-fe's Introduction

Pressbooks

Contributors: Pressbooks [email protected] Tags: ebooks, publishing, webbooks Requires at least: 6.6.1 Tested up to: 6.6.1

Stable tag: 6.19.2

Requires PHP: 8.1 License: GPL v3.0 or later License URI: https://github.com/pressbooks/pressbooks/blob/production/LICENSE.md

Pressbooks is an open source book publishing tool built on a WordPress multisite platform.

Description

Packagist Current Release Packagist PHP from Packagist

Packagist Code Coverage Translate Pressbooks

Pressbooks is an open source book publishing tool built on a WordPress multisite platform. Pressbooks outputs books in multiple formats, including PDF, EPUB, web, and a variety of XML flavours, using a theming/templating system, driven by CSS. Pressbooks is free software, released under the GPL v3.0 or later license.

Our webbooks and EPUB/PDF exports are all driven by HTML + CSS. XML outputs have no styling.

Requirements

Pressbooks works with PHP 8.1 and WordPress 6.6.1. Lower versions are not supported.

Installing the Plugin

Pressbooks is not for use on an existing blog. Instead it should be used with a fresh, multisite WordPress installation.

To install Pressbooks on your site, download the latest release and follow our installation instructions.

You may want to try Pressbooks.com before deciding whether or not you wish to host and maintain your own instance of Pressbooks. We can also host and maintain an instance of Pressbooks for you.

Contributor guidelines

Developers who are interested in contributing to our project should consult our "Contributing" guidelines and the developer guides published on our documentation website.

Disclaimers

The Pressbooks plugin is supplied "as is" and all use is at your own risk.

Changelog

Please see the CHANGELOG file for more information.

pressbooks-book-directory-fe's People

Contributors

arzola avatar cagp-dev-mtl avatar dependabot[bot] avatar fdalcin avatar ho-man-chan avatar nicotaglienti avatar ricardopressbooks avatar richard015ar avatar steelwagstaff avatar

Watchers

avatar avatar avatar avatar avatar avatar avatar

Forkers

nicotaglienti

pressbooks-book-directory-fe's Issues

Increase E2E testing for directory

Create tests for

  1. applying filters
  2. applying individual filter clear buttons
  3. applying clear all filters
  4. applying books per page setting
  5. manually changing page w/ pagination
  6. book card metadata & icons match what has been searched

Enable voice search for main search field

Users should be able to search by voice in browsers where this is supported. Voice search should be enabled for the main book search field and should appear in line with the text entry field (just to the right of where the magnifying lens icon is now). We can use the ais-voice search widget: https://www.algolia.com/doc/api-reference/widgets/voice-search/vue/

https://vue-instantsearch.netlify.app/stories/?selectedKind=ais-voice-search&selectedStory=default&full=0&addons=1&stories=1&panelRight=1&addonPanel=storybooks%2Fstorybook-addon-knobs

https://video.algolia.com/watch/HPCsiJXctALqctn7W4Vbha

Allow visitors/users to create 'collections'

Pressbooks staff and members of our community want to save and present 'collections' of curated content from within the directory; e.g. 'Our favorite nursing textbooks' or 'Italian language learning' or 'textbook revisions made for Australian institutions', etc.

Back-end:

  • Design a storage model for users/books, etc.
  • Set up location for storing user accounts, lists

Functionality:

  • The directory should allow users to login and create an account (with OAuth?).
  • The directory should allow logged in users to select one or more books from the directory listing and save them to a list.
  • Users should be able to make multiple lists
  • Users should be able to edit lists (add books, remove books singly or in bulk)
  • Users should be able to make lists private or public.
  • Users should be able to share lists (they should have addressable URLs)
  • Users should be able to collaborate with other users on a list.

Build landing page + facets/filters/search to spec

See: #10
Two views: desktop & mobile

The landing page should present a full listing of all books in the directory with some introductory text:

Welcome to Pressbooks Directory [h1]

This site presents a searchable, filterable directory of [###] books published across [##] Pressbooks networks (see full list [link]). To use the directory, you can search the full text of all metadata, apply one or more filters, or browse the book cards below.

[The initial display should include some filters -- only display books with more than 1000 words, and books that are in the network catalog. The 'in network catalog filter should be removable.)

FIND A BOOK: [search bar -- text says ‘search all book metadata’]

Filters:

Filter headings: font-family: Karla; text-transform: uppercase; font-size: 1.25rem; Color: #b01109;
Filter options: display with default CSS for now, but display numerical values after option in parenthesis, i.e. English (715); Spanish (115), etc.

The following filters should be provided to the left of the book directory cards. Multiple filters should be able to be applied simultaneously. When applied, users should see the individual query rules, and be able to remove them individually.

  1. Network [multiselect}
  2. language [multi-select]
  3. Subject [multi-select]
    • Add check boxes
    • Should be similar to what happens with Book List currently
  4. Based On
    • Based on another book
    • Original
    • Any
  5. Words [> or < number input by the user]
    • Add clear button
  6. Storage size (MB)
    • Filter should control values in MB, not KB
    • Add clear button
  7. Publisher [multi-select]
    • Add check boxes

Headings:
H2: Karla, sans-serif font, size: 2.25rem, weight: 600 (bold), text-transform: uppercase. Color: rgb(176, 17, 9); Margin-bottom: 3rem; line-height: 1.5
H3: Karla, sans-serif font, size: 1.5rem, weight: 600 (bold), text-transform: uppercase. Color: rgb(176, 17, 9). Margin bottom: 1.5rem; line-height: 1.5
P: Spectral, serif font. Size: 1.125rem, weight: 400. Color: rgb (34, 34, 34); line-height: 1.5; margin-top: 1.5em; margin-bottom: 1rem
Background colors: rgb(238, 238, 238) and rgb(250, 250, 250)
Accent color: #015D75

Add AxeLinter to front end repo

  • Schedule consult with Ned to learn more.
  • Configure Accesslint or AxeLinter to run on each new PR for this repo. Document what we learn and make recommendation for continued use in this and other org repos.

Explore the use of Axe Linter (https://www.deque.com/blog/introducing-axe-linter/), Deque's Axe devtools (https://www.deque.com/axe/devtools/) and Accesslint (https://accesslint.com/) with frontend directory project. What did we learn? Should we use any of these tools more extensively to improve the quality & a11y of our code?

Accesslint is in use in PB-book, Aldine, LTI 1.3.

Deque’s https://www.deque.com/axe/devtools/ or https://www.deque.com/blog/introducing-axe-linter/. “axe-core can be integrated into your build process (there are ways to slip it into Continuous Integration tools and official helpers like react-axe for testing React projects). The aXe WCAG ruleset is also baked into Chrome’s built-in Lighthouse devtools panel”

Add additional sort by options to control display order of book cards

We can set default displays https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/, need to research replica indices to allow user customization: https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/in-depth/replicas/

We should allow the viewer to choose some additional options for sorting the display of results using the ais-sort-by widget: https://www.algolia.com/doc/api-reference/widgets/sort-by/vue/. Available sort by options should include

  1. Alphabetical A-Z (default)
  2. Last updated date (descending)
  3. Word count (descending)

Replace 'about' copy & write 'how to use' documentation

  • Replace "This directory provides an index of 9069 public books published across 81 Pressbooks networks. Find books of interest by searching, applying filters, or simply browsing the book cards below. [How to use the site.]" with usable copy (Leigh to help)

  • Write documentation (and demo video) for how to use the directory and its features (Amy to help).

  • Link to documentation from directory main page

Cloned / Original icon in bookcard doesn't display correctly

Some cloned books display the "Original" icon in bookcard. Take a look at 'A Guide to Making Open Textbooks with Students' to find several examples.

In addition, the 'Based On Another Book' filter is not working as expected. When a user selects this option, the filter chip says 'Original'
Screenshot from 2020-07-15 13-29-18

Add support for routing URLs for specific filters/queries

Users should be able to share the results of a specific search/filter query with themselves or others. We should also be able to display 'recommended searches' or 'featured queries' on the landing page of the site.

To do this, I think we need to add support for 'routing URLs'. See: https://www.algolia.com/doc/guides/building-search-ui/going-further/routing-urls/js/

  • Attempt to implement for one example from each type of filter [include/exclude, numeric, etc.]
  • E2E tests

Incorporate E2E testing before staging deploy

Proposed approach: add another stage to the current deployment pipeline. Deployment pipeline for Front End should look like this:

  1. Build test
  2. Deploy test (use S3 to build temporary/static web site for testing)
  3. Run E2E tests
  4. If pass, deploy staging. If fail, notify in bots channel.
  5. Add staging keys for browserstack

Produce spec/wireframes for visual customization/CSS/layout for filters/search

Produce spec/wireframes for additional front-end visual customization/CSS/layout for filters and search. Spec should include

  1. Logos, header, footer, explanatory text
  2. Overall theme: color + typefaces + sizes
  3. Behavior for buttons/logos/search
  4. Wireframe -- visual + link
  5. Written definition of functionality (what should happen when actions are taken, behavior)
  6. Two views: desktop + mobile (i.e. 1 breakpoint)

UX/UI Feedback & refinement

  • Share initial front end build with selected users (Hugh, Sarah, Rebus experts) and ask for UX/UI input
  • Refine spec and make decisions for improvement

Produce spec/wireframes for visual customization/CSS/layout of cards

Produce spec/wireframes for additional front-end visual customization/CSS/layout for book cards. Spec should include

  1. Wireframe -- visual + link (includes colors, typefaces)
  2. Written definition of functionality (what should happen when actions are taken, behavior)
  3. Truncation and conditional display rules
  4. Two sizes (normal desktop + mobile responsive view)

Add last revised / updated date to book metadata and book card

Users will often want to know when a book has last been edited/updated when deciding whether they'd like to adopt/adapt it. We should store this information in the directory database and display it on the book card, between word count and storage size. We should also consider adding a facet/filter for this value.

  • Add last revised/'last edited' ($blog_info->last_updated) date to book API
  • Grab with fetcher
  • Display on book card
  • Add facet/filter letting users apply date range
  • E2E testing

Develop front end requirements

Steel to work with Leigh to decide what we want to display 'above the fold' on landing page to showcase books, etc. and produce specification for this.
Specify default filters (remove books with Test in title, with word count < 1000, etc.)
Specify desired CSS improvements

Add support for hyphenation within book cards

Turn on hyphenation for book cards. To do this:

  1. Declare the language for each individual card (based on the metadata language declared by the book, preferably).
  2. Set hyphens: auto in CSS for title and other metadata fields

See https://medium.com/clear-left-thinking/all-you-need-to-know-about-hyphenation-in-css-2baee2d89179
See: https://caniuse.com/#search=hyphens
See: https://developer.mozilla.org/en-US/docs/Web/CSS/hyphens

We can also use what we learn from this to potentially improve hyphenation practices in all our PDF exports?

Add support for boolean, string literal, and specific-filter searching

  • Enable the use of boolean operators in search queries (i.e. AND, OR, NOT)?

  • Enable the use of string literals in searching (i.e. "Steel Wagstaff")

  • Enable the user of operators to restrict/limit search within specific fields (i.e. "Chemistry" within the Title field or "Steel Wagstaff" within Author or Ohio State within "Publisher"; i.e. Title:Chemistry or Author:"Steel Wagstaff")

  • Describe how to use booleans and string literals in search so it can be documented in our guide

See: https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/in-depth/combining-boolean-operators/ and https://www.algolia.com/doc/api-reference/search-api-parameters/

[Research] Can we allow users to exclude filter terms?

Can users exclude filter terms (by clicking a small 'NOT' option to the right of term). When terms are excluded, the value becomes strikethrough.

Sample functionality described here: https://knowledge.exlibrisgroup.com/Summon/Product_Documentation/Searching_in_The_Summon_Service/Search_Results/Summon%3A_Search-Result_Facets_and_Refinements#Expanding_Your_Options_to_Include_or_Exclude_Facet_Values

Research 'user/list/collections' prerequisites

Research task to lay ground work for functionality described in #19.

Outcome:

  • Architecture design document
  • Recommendation for login method [1 specific solution]
  • Recommendation for data model [1 specific solution]
  • Recommendation for database storage [1 specific solution]

General principle: make use of AWS tools

Enable E2E testing for deployment pipeline

Goal: set up our test suites to run following each merge to dev that must pass before deploy to production

  • Set up [email protected] user in BrowserStack
  • Create env variables, access key, user in AWS pipeline
  • Add NPM commands to trigger tests in pipeline
  • Make deploy conditional upon pass

Add Sentry to PB Directory

We can use Sentry with our sponsored account even though this is a private repo:

What do I get in a sponsored account?
Sponsored accounts get 500k sponsored events per month on a Teams plan. Soon, you'll have the ability to upgrade at a discounted rate if you want to use more Sentry (we're working on this).
Is there an event cap? What if I need more?
Under a sponsored plan you get 500k sponsored events per month. If you need more than that, we will work with you to get you on the best plan for your volume.

Oscar to review, Oscar & Ricardo to test

Create 'featured books/searches' above the fold

  • Featured Books Just below the directory description and above the book cards, we should present 4 or 5 featured books. These books should be representative of the many EDU features Pressbooks supports. Some examples of these books include a book that includes a wide variety of H5P activities, a book with a variety of audio/visual elements, a book with lots of accessible math notation. Featured Books should be represented on the front end by the book cover. The book cover should be clickable and lead to the book itself.
  • Featured Searches The featured books should also correspond to or be an example of a popular and impressive searches. These searches should be linked to the message “Find more books like this” that should appear below the book cover.

Candidates:
https://open.oregonstate.education/aandp
https://wisc.pb.unizin.org/portuguese
https://otn.pressbooks.pub/fundamentalsofbusiness
https://pressbooks.online.ucf.edu/osuniversityphysics (no H5P but lots of mathjax)

Search queries (to be refined):

  • Subject: Psychology
  • Subject: Education
  • Nursing (metadata) because subject search surfaces less results. I also add a 10,000 word min

Set up a vue.js app in AWS

Set up this repo as a vue.js app in AWS using staging.pressbooks.directory (staging) and pressbooks.directory (prod). https://developer.okta.com/blog/2018/07/03/deploy-vue-app-aws

TODO:

  • Prepare DNS records for pressbooks.directory (and staging subdomain)
  • Set up deployment pipeline for AWS app (front end) for staging & production [manual deploy]
  • Populate development & staging indices in Algolia & rename production index
  • Set env staging variable to the appropriate index in the ci/cd platform of book fetcher and book directory front end
  • Produce documentation on how to deploy app locally
  • Document the process and methods used

Add clear options for numeric facets

Currently there is no 'clear' button for facets which filter by number or count (words, h5p activities, storage size) as there are for other facets. Users would like to be able to clear inputs for these fields with a single button.

We need to add a new method for clearing the filter chips and the numeric input.

Build exclude option for filter choices

Allow users to check a checkmark to filter FOR a value, and an X to exclude a value. If a checkmark is present, all excludes should be cleared. If multiple exclude choices are present, they should be combined w/ separate 'NOT' cards based on Ricardo's demo design. When an include filter is selected for a group, all exclude filters should be cleared.

  • Create a common component with "exclude filter feature", replacing checkbox by button icons.
  • When a exclude filter is applied, all filter are applied with OR condition.
  • Store exclude filters applied using Vuex
  • Modify CurrentFilters component (chips) in order to hide all filters applied with OR condition and show something line "NOT" for the excluded filter as a chip.
  • Apply all use cases and combinations.
  • Apply E2E tests

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.