knight/datahub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[#777,#745,docs,blog][l]: review /doc, add blogs, add examples blog posts

Browse Source
This commit is contained in:
deme
2023-04-20 15:44:16 -03:00
parent 9cf6ccc884
commit 4d7a0f7e38
20 changed files with 282 additions and 133 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
site/content/assets/examples/frictionless-dataset-demo.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.6 MiB

27
site/content/blog/example-ckan.md Normal file
View File

@@ -0,0 +1,27 @@
---
title: "Example: data catalog with data coming from CKAN"
authors: ['Luccas Mateus']
date: 2023-04-20
---
Portal.js is an open source project that aims to simplify the creation of web-based data portals, making it easy for users to create and share data-driven applications.
The ckan-example added to Portal.js is intended to provide users with an easy way to set up a data catalog that can be used to display and share data stores behind a CKAN Backend. With this example, users can quickly set up a web-based portal that allows them to showcase their data and make it accessible to others, all this being done just by adding a simple env variable pointing to a CKAN Deployment.
To get a feel of the project, users can check the [live deployment](https://ckan-example.portaljs.org).
Below are some screenshots:
### Front page
![](https://i.imgur.com/NlTAIAg.png)
### Individual dataset page
![](https://i.imgur.com/RRoIlGf.png)
## Links
- [Documentation](/docs/example-ckan)
- [Repo](https://github.com/datopian/portaljs/tree/main/examples/ckan-example)
- [Live Demo](https://ckan-example.portaljs.org)

28
site/content/blog/example-data-catalog.md Normal file
View File

@@ -0,0 +1,28 @@
---
title: "Example: simple data catalog"
authors: ['Luccas Mateus']
date: 2023-04-20
---
Portal.js is an open source project that aims to simplify the creation of web-based data portals, making it easy for users to create and share data-driven applications.
The simple-example added to Portal.js is intended to provide users with an easy way to set up a data catalog that can be used to display and share data stores stored in GitHub repositories. With this example, users can quickly set up a web-based portal that allows them to showcase their data and make it accessible to others, all this being done thru the configuration of a simple `datasets.json` file.
To get a feel of the project, users can check the [live deployment](https://example.portaljs.org).
Below are some screenshots:
### Front page
![](https://i.imgur.com/wMk3pGf.png)
### Individual dataset page
![](https://i.imgur.com/UipBNEY.png)
## Links
- [Documentation](/docs/example-data-catalog)
- [Repo](https://github.com/datopian/portaljs/tree/main/examples/simple-example)
- [Live Demo](https://example.portaljs.org)

1
site/content/config.js
View File

@@ -19,6 +19,7 @@ const config = {
{ name: "Docs", href: "/docs" },
{ name: "Components", href: "/docs/components" },
{ name: "Learn", href: "/learn" },
{ name: "Blog", href: "/blog" },
// { name: "Gallery", href: "/gallery" },
// { name: "Data Literate", href: "/data-literate" },
// { name: "DL Demo", href: "/data-literate/demo" },

132
site/content/docs.md
View File

@@ -1,132 +0,0 @@
# 🌀 Portal.JS: The JavaScript framework for data portals
🌀 `portal.js` is a framework for rapidly building rich data portal frontends using a modern frontend approach. `portal.js` can be used to present a single dataset or build a full-scale data catalog/portal.
`portal.js` is built in Javascript and React on top of the popular [Next.js](https://nextjs.com/) framework. `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](https://ckan.org/).
## Features
- 🗺️ 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.
### For developers
- 🏗 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
## Installation and setup
Before installation, ensure your system satisfies the following requirements:
- Node.js 10.13 or later
- Nextjs 10.0.3
- MacOS, Windows (including WSL), and Linux are supported
> Note: We also recommend instead of npm using `yarn` instead of `npm`.
>
Portal.js is built with React on top of Nextjs framework, so for a quick setup, you can bootstrap a Nextjs app and install portal.js as demonstrated in the code below:
```bash=
## Create a react app
npx create-next-app
# or
yarn create next-app
```
After the installation is complete, follow the instructions to start the development server. Try editing pages/index.js and see the result on your browser.
> For more information on how to use create-next-app, you can review the [create-next-app](https://nextjs.org/docs/api-reference/create-next-app) documentation.
Once you have Nextjs created, you can install portal.js:
```bash=
yarn add https://github.com/datopian/portal.js.git
```
You're now ready to use portal.js in your next app. To test portal.js, open your `index.js` file in the pages folder. By default you should have some autogenerated code in the `index.js` file:
Which outputs a page with the following content:
![](https://i.imgur.com/GVh0P6p.png)
Now, we are going to do some clean up and add a table component. In the `index.js` file, import a [Table]() component from portal as shown below:
```javascript
import Head from 'next/head'
import { Table } from 'portal' //import Table component
import styles from '../styles/Home.module.css'
export default function Home() {
const columns = [
{ field: 'id', headerName: 'ID' },
{ field: 'firstName', headerName: 'First name' },
{ field: 'lastName', headerName: 'Last name' },
{ field: 'age', headerName: 'Age' }
];
const rows = [
{ id: 1, lastName: 'Snow', firstName: 'Jon', age: 35 },
{ id: 2, lastName: 'Lannister', firstName: 'Cersei', age: 42 },
{ id: 3, lastName: 'Lannister', firstName: 'Jaime', age: 45 },
{ id: 4, lastName: 'Stark', firstName: 'Arya', age: 16 },
{ id: 7, lastName: 'Clifford', firstName: 'Ferrara', age: 44 },
{ id: 8, lastName: 'Frances', firstName: 'Rossini', age: 36 },
{ id: 9, lastName: 'Roxie', firstName: 'Harvey', age: 65 },
];
return (
<div className={styles.container}>
<Head>
<title>Create Portal App</title>
<link rel="icon" href="/favicon.ico" />
</Head>
<h1 className={styles.title}>
Welcome to <a href="https://nextjs.org">Portal.JS</a>
</h1>
{/* Use table component */}
<Table data={rows} columns={columns} />
</div>
)
}
```
Now, your page should look like the following:
![](https://i.imgur.com/n0vSjY4.png)
> **Note**: You can learn more about individual portal components, as well as their prop types in the [components reference](/docs/components).
## Next Steps
You can check out the following examples built with Portal.js.
* [A portal for a single Frictionless dataset](/learn/ckan)
* [A portal with a CKAN backend](/learn/single-frictionless-dataset)
> The [`examples` directory](https://github.com/datopian/portal.js/tree/main/examples) is regularly updated with different portal examples.
You can also look at the full list of the available components that are provided by Portal.JS in [Components](/docs/components).
## Reference Information
* [Full list of the available components that are provided by Portal.JS](/docs/components)
* [Reference](/docs/references)
## Getting Help
If you have questions about anything related to Portal.js, you're always welcome to ask our community on [GitHub Discussions](https://github.com/datopian/portal.js/discussions).

26
site/content/docs/example-ckan.md Normal file
View File

@@ -0,0 +1,26 @@
---
title: "Example: data catalog with data coming from CKAN"
authors: ['Luccas Mateus']
date: 2023-04-20
---
**See the repo:** https://github.com/datopian/portaljs/tree/main/examples/ckan-example
This is a repo intended to serve as an example of a data catalog that get its data from a CKAN Instance.
- Creating a new file inside o `examples` with `create-next-app` like so:
```
npx create-next-app <app-name> --example https://github.com/datopian/portaljs/tree/main/ --example-path examples/ckan-example
```
- Inside `<app-name>` go to the `project.json` file and replace all instances of `ckan-example` with `<app-name>`
- Set the `DMS` env variable to the Url of the CKAN Instance Ex: `export DMS=https://demo.dev.datopian.com`
- Run the app using:
```
nx serve <app-name>
```
Congratulations, you now have something similar to this running on `http://localhost:4200`
![](https://media.discordapp.net/attachments/1069718983604977754/1098252297726865408/image.png?width=853&height=461)
If yo go to any one of those pages by clicking on `More info` you will see something similar to this
![](https://media.discordapp.net/attachments/1069718983604977754/1098252298074988595/image.png?width=853&height=461)

27
site/content/docs/example-data-catalog.md Normal file
View File

@@ -0,0 +1,27 @@
---
title: "Example: simple data catalog"
authors: ['Luccas Mateus']
date: 2023-04-20
---
**See the repo:** https://github.com/datopian/portaljs/tree/main/examples/simple-example
This is a repo intended to serve as a simple example of a data catalog that get its data from a series of github repos, you can init an example just like this one by.
- Creating a new file inside of `examples` with `create-next-app` like so:
```
npx create-next-app <app-name> --example https://github.com/datopian/portaljs/tree/main/ --example-path examples/simple-example
```
- Inside `<app-name>` go to the `project.json` file and replace all instances of `simple-example` with `<app-name>`
- Edit the file `datasets.json` to your liking, some examples can be found inside this [repo](https://github.com/datasets)
- Run the app using:
```
nx serve <app-name>
```
Congratulations, you now have something similar to this running on `http://localhost:4200`
![](https://i.imgur.com/JrDLycF.png)
If yo go to any one of those pages by clicking on `More info` you will see something similar to this
![](https://i.imgur.com/cpKMS80.png)

48
site/content/docs/example-frictionless-dataset.md.bkp Normal file
View File

@@ -0,0 +1,48 @@
---
title: "Example: showcase for a single Frictionless dataset"
authors: ['Luccas Mateus']
date: 2023-04-20
filetype: blog
---
**See the repo:** https://github.com/datopian/portaljs/tree/main/examples/dataset-frictionless
This example creates a portal/showcase for 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/
## How to use
```bash
npx create-next-app -e https://github.com/datopian/portal.js/tree/main/examples/dataset-frictionless
# choose a name for your portal when prompted e.g. your-portal or go with default my-app
# then run it
cd your-portal
yarn #install packages
yarn dev #start app in dev mode
```
You should see the demo portal running with the example dataset provided:
<img src="/assets/examples/frictionless-dataset-demo.gif" />
### Use your own dataset
You can try it out with other [Frictionless datasets](https://datahub.io/search).
In the directory of your portal do:
```bash
export PORTAL_DATASET_PATH=/path/to/my/dataset
```
Then restart the dev server:
```
yarn dev
```
Check the portal page and it should have updated e.g. like:
![](https://i.imgur.com/KSEtNF1.png)

45
site/content/docs/index.md Normal file
View File

@@ -0,0 +1,45 @@
# 🌀 Portal.JS: The JavaScript framework for data portals
🌀 Portal.JS is a framework for rapidly building rich data portal frontends using a modern frontend approach. Portal.JS can be used to present a single dataset or build a full-scale data catalog/portal.
Built in JavaScript and React on top of the popular [Next.js](https://nextjs.com/) framework. Portal.JS 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](https://ckan.org/).
## Features
- 🗺️ 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, Next.js).
- 🔋 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 Next.js and Apollo.
### For developers
- 🏗 Build with modern, familiar frontend tech such as JavaScript and React.
- 🚀 Next.js framework: so everything in Next.js for free: Server Side Rendering, Static Site Generation, huge number of examples and integrations, etc.
- Server Side Rendering (SSR) => Unlimited number of pages, SEO and more whilst still using React.
- Static Site Generation (SSG) => Ultra-simple deployment, great performance, great lighthouse scores and more (good for small sites)
## Tutorials and guides
### Examples
You can check out the following examples built with Portal.js.
* [Data catalog with data coming from CKAN](/docs/example-ckan)
* [Simple data catalog](/docs/example-data-catalog)
> The [`examples` directory](https://github.com/datopian/portal.js/tree/main/examples) is regularly updated with different portal examples.
## Reference Information
* [Full list of the available components that are provided by Portal.JS](/docs/components)
* [Reference](/docs/references)
## Getting Help
If you have questions about anything related to Portal.js, you're always welcome to ask our community on [GitHub Discussions](https://github.com/datopian/portal.js/discussions) or on our [Discord server](https://discord.gg/An7Bu5x8).

5
site/content/people/anuveyatsu.md Normal file
View File

@@ -0,0 +1,5 @@
---
id: anuveyatsu
name: Anuar Ustayev
avatar: https://avatars.githubusercontent.com/anuveyatsu
---

5
site/content/people/joao-demenech.md Normal file
View File

@@ -0,0 +1,5 @@
---
id: joaodemenech
name: João Demenech
avatar: https://avatars.githubusercontent.com/demenech
---

5
site/content/people/luccas-mateus.md Normal file
View File

@@ -0,0 +1,5 @@
---
id: luccasmateus
name: Luccas Mateus
avatar: https://avatars.githubusercontent.com/luccasmmg
---

5
site/content/people/mikanebu.md Normal file
View File

@@ -0,0 +1,5 @@
---
id: mikanebu
name: Meiran Zhiyenbayev
avatar: https://avatars.githubusercontent.com/mikanebu
---

5
site/content/people/popovayoana.md Normal file
View File

@@ -0,0 +1,5 @@
---
id: popovayoana
name: Yoana Popova
avatar: https://avatars.githubusercontent.com/popovayoana
---

5
site/content/people/rufus-pollock.md Normal file
View File

@@ -0,0 +1,5 @@
---
id: rufuspollock
name: Rufus Pollock
avatar: https://avatars.githubusercontent.com/rufuspollock
---