Skip to content

Latest commit

 

History

History
133 lines (104 loc) · 5.25 KB

README.md

File metadata and controls

133 lines (104 loc) · 5.25 KB
Raw

ASU News

ASU Web Standards-based implementation of news component.

This component is the React implementation of the old News component(https://github.com/ASU-CLAS/asu-react-news-list) but reusing a lot of the components already developed in components-core and component-carousel, taking in cosideration good practises, scalability and performance.

The job of this component is listing all the news fetched to the api url provided by the user. It also display a customizable, optional header with a title and a button.

Architecture details

This component was thought to share architectural aspects with the component-events component, this is why we created a component in components-core(FeedAnatomy) that has the role of fetching the data to the provided url, transform it using the provided transformer function and filter it using the provided filtering function. This component also creates a context that provides access to the data in all the child components. This is achieved using the BaseComponent, that is a high order component(to read more about high order components). With this approach we can pass whaterver body we want to render, with the desire url to fetch and the customs tranformer and filtering functions. The initialization of this component is the same as all the packages, so it can keep uniqueness between all of them. For this, we use two methods:

  • createElement: this is provided by React. It creates a new React element. Click to read more about createElement and react without jsx.
  • render: this is provided by ReactDOM library. It is used to render the react element in the DOM. Click to read more about render. The way it works is: when the initializer function is called, this creates the element with the props provided and the react component.Then it is rendered on the DOM.

Component views

The new News Component has 3 type of view as the old one:

  • Carousel view
  • Grid Card view
  • List Card view

Props and settings

The props of the components are being typed with the use of JSDocs. With this API we can make use of direferent block tags to define prop types. Read more about @typedef and @param block tags. The componet can customize by setting the following props

/**
 *  @typedef {{
 *    color?: "white" | "dark"
 *    text?: string
 * }} FeedHeader
 *
 *  @typedef {{
 *    color?: "gold" | "maroon" | "gray" | "dark"
 *    text?: string
 *    url?: string
 * }} FeedCtaButton
 *
 *  @typedef {{
 *    color?: "gold" | "maroon" | "gray" | "dark"
 *    text?: string
 *    size?: "default" | "small" | "medium" | "large"
 * }} FeedCardButton
 *
 * @typedef {{
 *  url?: string
 *  filters?: string
 * }} DataSource
 *
 * @typedef {{
 *  header?: FeedHeader
 *  ctaButton: FeedCtaButton
 *  cardButton?: FeedCardButton
 *  dataSource: DataSource
 *  maxItems?: number
 * }} FeedType
 */

Component props documentation

You can find a full list of props into the docs/README.props.md

CLI Commands

# add component-footer
yarn add @asu/component-news

# run storybook
yarn storybook

# build for production with minification
yarn build

# run tests
yarn test

How to install

  1. Either make sure you are part of the ASU github organization and follow the instructions here,or, if you already are, you can clone this repo and run yarn install and yarn build to build the package locally.

  2. yarn add @asu/component-news

Use as a JS module in React app

Default import

    import { News } from '@asu/component-news'

Import for use in HTML page

You can find an example of how to set News props here

Example

{
  header: {
    color: "dark",
    text: "News carousel"
},
  ctaButton: {
    color: "gold",
    url: "https://news.asu.edu",
    text: "Click to see more news",
  },
  dataSource: {
    url: "/api/mocks/feeds-json",
    filters: "validFilter,more words filter,filter_with_underscore"
  },
  maxItems: 10,
  }

The prop filters needs a special mention. It is meant to be a string which contains all desired filters separated by a comma ,

Fields where the filter will be applied

const filterFields = ["newsUnits", "interests", "audiences", "eventTypes"];

Any one dataSource filter value will be checked against every field in the feed source which are listed in the file src/core/constants/filter-fields.js and a value match on any field will result in the news item being included in the output.

Future improvements

All the requirements for this component were covered, so there is no need of any further enhancements at the moment this is being written.