diff --git a/.github/workflows/portal-test.yml b/.github/workflows/examples-dataset-frictionless.yml similarity index 54% rename from .github/workflows/portal-test.yml rename to .github/workflows/examples-dataset-frictionless.yml index 435ed5e0..f7f3815e 100644 --- a/.github/workflows/portal-test.yml +++ b/.github/workflows/examples-dataset-frictionless.yml @@ -1,4 +1,4 @@ -name: portal +name: dataset-frictionless on: push: branches: [ main ] @@ -11,7 +11,11 @@ jobs: steps: - uses: actions/checkout@v2 - name: Install modules - run: yarn + run: | + cd examples/dataset-frictionless + yarn - name: Run tests - run: yarn test + run: | + cd examples/dataset-frictionless + yarn test -u diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 00000000..89c4c568 --- /dev/null +++ b/DESIGN.md @@ -0,0 +1,15 @@ +# Design Notes + +Portal.js is a React and NextJS based framework for building dataset/resources pages and catalogs. It consists of: + +* React components for data portal functionality e.g. data tables, graphs, dataset pages etc +* Tooling to load data (based on Frictionless) +* Template sites you can reuse using `create-next-app` + * Single dataset micro-site + * Github backed catalog + * CKAN backed catalog + * ... +* Local development environment +* Deployment integration with DataHub.io + +In summary, technically PortalJS is: NextJS + data specific react components + data loading glue (mostly using frictionless-js). diff --git a/README.md b/README.md index ebcd606d..15b6d591 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,43 @@

πŸŒ€ Portal.JS
-A gateway to your data +The javascript framework for
+data portals

-πŸŒ€ `Portal` is the data presentation framework. `Portal` can be used to showcase a single dataset or build a full-scale data catalog/portal. `Portal` is built in Javascript and React on top of the popular Next.js framework. +πŸŒ€ `portal` is a framework for rapidly building rich data portal frontends using a modern frontend approach. -## Status +`portal` can be used to present a single dataset or build a full-scale data catalog/portal. `portal` is built in Javascript and React on top of the popular [Next.js][] framework. -`Portal` is currently focused on presenting a single (Frictionless) dataset for viewing and exploration. +`Portal` assumes a "decoupled" approach where the frontend is a separate service from the backend and interacts with backend(s) via an API. It can be used with any backend and has out of the box support for [CKAN][]. -## Install +[ckan]: https://ckan.org/ +[next.js]: https://nextjs.com/ -Git clone then: +## Features -``` -yarn install -``` +- πŸ—ΊοΈ Unified sites: present data and content in one seamless site, pulling datasets from a DMS (e.g. CKAN) and content from a CMS (e.g. wordpress) with a common internal API. +- πŸ‘©β€πŸ’» Developer friendly: built with familiar frontend tech Javascript, React etc +- πŸ”‹ Batteries included: Full set of portal components out of the box e.g. catalog search, dataset showcase, blog etc. +- 🎨 Easy to theme and customize: installable themes, use standard CSS and React+CSS tooling. Add new routes quickly. +- 🧱 Extensible: quickly extend and develop/import your own React components +- πŸ“ Well documented: full set of documentation plus the documentation of NextJS and Apollo. -## Usage +### For developers -In this directory: +- πŸ— Build with modern, familiar frontend tech such as Javascript and React. +- πŸš€ NextJS framework: so everything in NextJS for free React, SSR, static site generation, huge number of examples and integrations etc. + - SSR => unlimited number of pages, SEO etc whilst still using React. + - Static Site Generation (SSG) (good for small sites) => ultra-simple deployment, great performance and lighthouse scores etc +- πŸ“‹ Typescript support -```bash -export PORTAL_DATASET_PATH=/path/to/my/dataset -yarn dev -``` +## Getting Started -And you will get a nice dataset page at `http://localhost:3000` +### Setup -![](https://i.imgur.com/KSEtNF1.png) +Install a recent version of Node. You'll need Node 10.13 or later. +### Create a Portal app -## Design Notes - -Portal.js is a React and NextJS based framework for building dataset/resources pages and catalogs. It consists of: - -* React components for data portal functionality e.g. data tables, graphs, dataset pages etc -* Tooling to load data (based on Frictionless) -* Template sites you can reuse using `create-next-app` - * Single dataset micro-site - * Github backed catalog - * CKAN backed catalog - * ... -* Local development environment -* Deployment integration with DataHub.io - -In summary, technically PortalJS is: NextJS + data specific react components + data loading glue (mostly using frictionless-js). +To create a Portal app start with on the examples in the `[examples directory](./examples). diff --git a/.babelrc b/examples/dataset-frictionless/.babelrc similarity index 100% rename from .babelrc rename to examples/dataset-frictionless/.babelrc diff --git a/examples/dataset-frictionless/README.md b/examples/dataset-frictionless/README.md new file mode 100644 index 00000000..3ee3c848 --- /dev/null +++ b/examples/dataset-frictionless/README.md @@ -0,0 +1,24 @@ +This examples if for presenting a single dataset. The dataset should be a [Frictionless dataset (data package)][fd] i.e. there should be a `datapackage.json`. + +[fd]: https://frictionlessdata.io/data-packages/ + +## Install + +Git clone this directory then: + +``` +yarn install +``` + +## Usage + +In this directory: + +```bash +export PORTAL_DATASET_PATH=/path/to/my/dataset +yarn dev +``` + +And you will get a nice dataset page at `http://localhost:3000` + +![](https://i.imgur.com/KSEtNF1.png) diff --git a/components/Chart.js b/examples/dataset-frictionless/components/Chart.js similarity index 100% rename from components/Chart.js rename to examples/dataset-frictionless/components/Chart.js diff --git a/components/Table.js b/examples/dataset-frictionless/components/Table.js similarity index 100% rename from components/Table.js rename to examples/dataset-frictionless/components/Table.js diff --git a/fixtures/datasetsDoubleView/README.md b/examples/dataset-frictionless/fixtures/datasetsDoubleView/README.md similarity index 100% rename from fixtures/datasetsDoubleView/README.md rename to examples/dataset-frictionless/fixtures/datasetsDoubleView/README.md diff --git a/fixtures/datasetsDoubleView/datapackage.json b/examples/dataset-frictionless/fixtures/datasetsDoubleView/datapackage.json similarity index 100% rename from fixtures/datasetsDoubleView/datapackage.json rename to examples/dataset-frictionless/fixtures/datasetsDoubleView/datapackage.json diff --git a/fixtures/datasetsDoubleView/vix-daily.csv b/examples/dataset-frictionless/fixtures/datasetsDoubleView/vix-daily.csv similarity index 100% rename from fixtures/datasetsDoubleView/vix-daily.csv rename to examples/dataset-frictionless/fixtures/datasetsDoubleView/vix-daily.csv diff --git a/fixtures/datasetsPlotlyView/README.md b/examples/dataset-frictionless/fixtures/datasetsPlotlyView/README.md similarity index 100% rename from fixtures/datasetsPlotlyView/README.md rename to examples/dataset-frictionless/fixtures/datasetsPlotlyView/README.md diff --git a/fixtures/datasetsPlotlyView/datapackage.json b/examples/dataset-frictionless/fixtures/datasetsPlotlyView/datapackage.json similarity index 100% rename from fixtures/datasetsPlotlyView/datapackage.json rename to examples/dataset-frictionless/fixtures/datasetsPlotlyView/datapackage.json diff --git a/fixtures/datasetsPlotlyView/vix-daily.csv b/examples/dataset-frictionless/fixtures/datasetsPlotlyView/vix-daily.csv similarity index 100% rename from fixtures/datasetsPlotlyView/vix-daily.csv rename to examples/dataset-frictionless/fixtures/datasetsPlotlyView/vix-daily.csv diff --git a/fixtures/datasetsVegaView/README.md b/examples/dataset-frictionless/fixtures/datasetsVegaView/README.md similarity index 100% rename from fixtures/datasetsVegaView/README.md rename to examples/dataset-frictionless/fixtures/datasetsVegaView/README.md diff --git a/fixtures/datasetsVegaView/datapackage.json b/examples/dataset-frictionless/fixtures/datasetsVegaView/datapackage.json similarity index 100% rename from fixtures/datasetsVegaView/datapackage.json rename to examples/dataset-frictionless/fixtures/datasetsVegaView/datapackage.json diff --git a/fixtures/datasetsVegaView/vix-daily.csv b/examples/dataset-frictionless/fixtures/datasetsVegaView/vix-daily.csv similarity index 100% rename from fixtures/datasetsVegaView/vix-daily.csv rename to examples/dataset-frictionless/fixtures/datasetsVegaView/vix-daily.csv diff --git a/jest.config.js b/examples/dataset-frictionless/jest.config.js similarity index 100% rename from jest.config.js rename to examples/dataset-frictionless/jest.config.js diff --git a/lib/dataset.js b/examples/dataset-frictionless/lib/dataset.js similarity index 100% rename from lib/dataset.js rename to examples/dataset-frictionless/lib/dataset.js diff --git a/lib/utils.js b/examples/dataset-frictionless/lib/utils.js similarity index 100% rename from lib/utils.js rename to examples/dataset-frictionless/lib/utils.js diff --git a/package.json b/examples/dataset-frictionless/package.json similarity index 100% rename from package.json rename to examples/dataset-frictionless/package.json diff --git a/pages/_app.js b/examples/dataset-frictionless/pages/_app.js similarity index 100% rename from pages/_app.js rename to examples/dataset-frictionless/pages/_app.js diff --git a/pages/index.js b/examples/dataset-frictionless/pages/index.js similarity index 100% rename from pages/index.js rename to examples/dataset-frictionless/pages/index.js diff --git a/postcss.config.js b/examples/dataset-frictionless/postcss.config.js similarity index 100% rename from postcss.config.js rename to examples/dataset-frictionless/postcss.config.js diff --git a/public/favicon.ico b/examples/dataset-frictionless/public/favicon.ico similarity index 100% rename from public/favicon.ico rename to examples/dataset-frictionless/public/favicon.ico diff --git a/styles/globals.css b/examples/dataset-frictionless/styles/globals.css similarity index 100% rename from styles/globals.css rename to examples/dataset-frictionless/styles/globals.css diff --git a/styles/tailwind.css b/examples/dataset-frictionless/styles/tailwind.css similarity index 100% rename from styles/tailwind.css rename to examples/dataset-frictionless/styles/tailwind.css diff --git a/tailwind.config.js b/examples/dataset-frictionless/tailwind.config.js similarity index 100% rename from tailwind.config.js rename to examples/dataset-frictionless/tailwind.config.js diff --git a/tests/components/Chart.test.js b/examples/dataset-frictionless/tests/components/Chart.test.js similarity index 100% rename from tests/components/Chart.test.js rename to examples/dataset-frictionless/tests/components/Chart.test.js diff --git a/tests/components/Table.test.js b/examples/dataset-frictionless/tests/components/Table.test.js similarity index 100% rename from tests/components/Table.test.js rename to examples/dataset-frictionless/tests/components/Table.test.js diff --git a/tests/lib/dataset.test.js b/examples/dataset-frictionless/tests/lib/dataset.test.js similarity index 100% rename from tests/lib/dataset.test.js rename to examples/dataset-frictionless/tests/lib/dataset.test.js diff --git a/tests/lib/utils.test.js b/examples/dataset-frictionless/tests/lib/utils.test.js similarity index 100% rename from tests/lib/utils.test.js rename to examples/dataset-frictionless/tests/lib/utils.test.js diff --git a/tests/pages/index.test.js b/examples/dataset-frictionless/tests/pages/index.test.js similarity index 100% rename from tests/pages/index.test.js rename to examples/dataset-frictionless/tests/pages/index.test.js diff --git a/tests/setupTests.js b/examples/dataset-frictionless/tests/setupTests.js similarity index 100% rename from tests/setupTests.js rename to examples/dataset-frictionless/tests/setupTests.js diff --git a/yarn.lock b/examples/dataset-frictionless/yarn.lock similarity index 100% rename from yarn.lock rename to examples/dataset-frictionless/yarn.lock