Skip to content

Latest commit

 

History

History
executable file
·
253 lines (178 loc) · 6.69 KB

README.md

File metadata and controls

executable file
·
253 lines (178 loc) · 6.69 KB
Raw

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:

  • Using yarn

    yarn add alps-react

  • Using npm

    npm intall alps-react

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="//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="//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

  • Run Storybook: Will run a local storybook server with hot reload in http://localhost:9009

    yarn storybook

  • Build Storybook: will bundle the storybook as static assets in /storybook-static

    yarn build-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

  • Docker

  • docker-compose

    • docker-compose is included with Docker on default installation for both Mac OS and Windows version
    • docker-compose for linux: Please see your distributions package management system

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

  • Run Storybook: Will run a local storybook server with hot reload in http://localhost:9009

    dcli --service-ports yarn storybook

  • Build Storybook: will bundle the storybook as static assets in /storybook-static

    dcli yarn build-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