search

adventistchurch / alps-react

This React theme is an implementation of the Adventist Living Pattern System (ALPS) designed to support the work of the Seventh-day Adventist Church.
http://alps-react.adventist.io
Other
10 stars 6 forks source link

readme

alps-react

[WIP] A React implementation of ALPS

ALPS-React Storybook

Translations:

For more info and reference, check ALPS Documentation:

Usage

Add alps-react as a dependency:

Then import and use its components in your code:

import {
  AlpsContextProvider,
  Body,
  Button,
  Blockquote,
  Div,
  MediaBlock,
} from 'alps-react'

function MyApp(props) {
  return (
    // The AlpsContextProvider and Body components are required as parents other ALPS-React components (normally in your App root)
    <AlpsContextProvider>
      <Body primaryColor="bluejay" hasGrid>
        <Div spacing="double" padding>
          <Button text="Welcome to ALPS-React" />

          <MediaBlock
            type="inline"
            title="Sunt id vel ipsum at ut praesentium aut."
            description="Repellat libero qui magni at ut sapiente facere nam veritatis."
            kicker="Cumque omnis velit."
            category="Church"
            date={new Date()}
            image={{
              srcSet: {
                default: '//picsum.photos/480/270?image=248',
                500: '//picsum.photos/720/405?image=248',
                900: '//picsum.photos/960/540?image=248',
              },
              alt: 'Placeholder image',
            }}
            reversed={true}
            cta="Read more"
            url="#/link/to/article"
          />

          <Blockquote text="Asperiores quisquam perferendis dolor in amet." />
        </Div>
      </Body>
    </AlpsContextProvider>
  )
}

NOTE: This is just a simple example on how the API loooks. Event when you can use the components as you will, the recomended way is to use some of the Templates components and provide them with configurations and data/subcomponents.

Assets: ALPS Styles and fonts

You should also include in your HTML <head> ALPS stylesheets and fonts from their official CDN:

<!-- FONT -->
<link
  rel="stylesheet"
  type="text/css"
  href="https://github.com/adventistchurch/alps-react/blob/master//fonts.googleapis.com/css?family=Noto+Sans:400,400i,700,700i|Noto+Serif:400,400i,700,700i&display=swap"
  media="all"
/>

<!-- ALPS CSS -->
<link
  rel="stylesheet"
  type="text/css"
  href="https://github.com/adventistchurch/alps-react/blob/master//cdn.adventist.org/alps/3/3.7.9/css/main-bluejay.css"
  media="all"
/>

Note: Replace bluejay with the ALPS theme color you are planing to use (check primaryColors array in src/atoms/global/colors.js for all available options)

If you need to add this programatically, the externalAssets variable is exposed by alps-react:

import { Helmet } from "react-helmet"

import { getExternalAssets, AlpsContextProvider, Body } from 'alps-react'

const externalAssets = getExternalAssets({ theme: 'bluejay' })

function MyApp () {
    return (
      <React.Fragment>
        <Helmet>
          <title>My App</title>
          <link rel="canonical" href="http://myapp.com" />

          {externalAssets.css.map(href => (
            <link rel="stylesheet" type="text/css" href={href} media="all" />
          ))}
        </Helmet>

        <AlpsContextProvider>
          <Body primaryColor="bluejay" hasGrid>
            {/* ALPS-React components go here */}
          </Body>
        </AlpsContextProvider>
      </React.Fragment>
    )
  }
}

After adding the Font and CSS assets you should see something like this:

Example output

Assets: Images

NOTE: this is only required if you use some components that use image assets, like atoms/map/GoogleMap.

Copy the contents of /public/assets/images to the location where you stores the asssets in you project (its usually /public).

Also you need to configure the publicAssetsPath in <AlpsContextProvider />. For example, if you copied all assets to /public/assets:

<AlpsContextProvider publicAssetsPath="/assets">
  <Body primaryColor="bluejay" hasGrid>
    {/* ALPS-React components go here */}
  </Body>
</AlpsContextProvider>

(Note that in this example, the path / points to /public, so /assets points to /public/assets)

Development

Requirements

Install Dependencies

yarn

Load Storybook

Build for production

To build a production version, run:

yarn build

This library is built using Rollup.js

Development with Docker

If you want to develop the project using Docker, follow the below instructions.

Requirements

Advice about docker-compose

We are using Node through Docker. In order to use tools like Yarn through Docker, we must pass our commands to the Docker container. This is a really long command:

docker-compose -f docker-compose.cli.yml run --rm <command>

Because of this, it is recommended to create an alias for docker-compose -f docker-compose.cli.yml run --rm and call it dcli (Docker CLI).

Install Dependencies

dcli yarn install

Load Storybook

Build for production

To build a production version, run:

dcli yarn build

Copyright

© 2019 General Conference of the Seventh-day Adventist Church https://adventist.org | https://adventist.io

Developed by Stimme der Hoffnung e.V in Germany