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

[docs/examples][m] - new ckan example/blog/docs

Browse Source
This commit is contained in:
Luccas Mateus de Medeiros Gomes 2023-05-25 08:23:05 -03:00
parent 7849873582
commit b1845dd2c9
2 changed files with 137 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
site/content/docs/examples/example-ckan-ssg.md Normal file
View File

@ -0,0 +1,75 @@
---
title: "Example: Data catalog with data on CKAN"
authors: ['Luccas Mateus']
date: 2023-04-20
filetype: blog
---
The ckan-example added to PortalJS 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.
## Demo
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)
## How to use this example as a template
- Create a new app with `create-next-app`:
```
npx create-next-app <app-name> --example https://github.com/datopian/portaljs/tree/main/examples/ckan-example
cd <app-name>
```
- This project uses CKAN as a backend, so you need to point the project to the CKAN Url desired, you can do so by setting up the `DMS` env variable in your terminal or adding a `.env` file with the following content:
```
DMS=<ckan url>
```
- Run the app using:
```
npm run dev
```
Congratulations, you now have something similar to this running on `http://localhost:3000`
![](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)
## Deployment
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fdatopian%2Fportaljs%2Ftree%2Fmain%2Fexamples%2Fckan-example&env=DMS&envDescription=URL%20For%20the%20CKAN%20Backend%20Ex%3A%20https%3A%2F%2Fdemo.dev.datopian.com)
By clicking on this button, you will be redirected to a page which will allow you to clone the content into your own github/gitlab/bitbucket account and automatically deploy everything.
## Extra commands
You can also build the project for production with
```
npm run build
```
And run using the production build like so:
```
npm run start
```
## Links
- [Repo](https://github.com/datopian/portaljs/tree/main/examples/ckan-example)
- [Live Demo](https://ckan-example.portaljs.org)

80
site/content/docs/examples/example-ckan.md
View File

@ -1,57 +1,64 @@
---
title: "Example: Data catalog with data on CKAN"
authors: ['Luccas Mateus']
date: 2023-04-20
date: 2023-05-24
filetype: blog
---
The ckan-example added to PortalJS 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.
The PortalJS CKAN example intendeds to provide users with an easy way to bootstrap a data catalog and share data stories backed by a CKAN back end, simply by setting a simple environment variable pointing to a CKAN instance.
## Demo
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)
![](https://hackmd.io/_uploads/S1CsQ9jr2.png)
#### Individual dataset page
![](https://i.imgur.com/RRoIlGf.png)
![](https://hackmd.io/_uploads/ryZRXcorn.png)
## How to use this example as a template
- Create a new app with `create-next-app`:
### Create a new app with `create-next-app`:
Navigate to the directory in which you want to create the project folder and run the following command:
```
npx create-next-app <app-name> --example https://github.com/datopian/portaljs/tree/main/examples/ckan-example
npx create-next-app <app-name> --example https://github.com/datopian/portaljs/tree/main/examples/ckan
cd <app-name>
```
- This project uses CKAN as a backend, so you need to point the project to the CKAN Url desired, you can do so by setting up the `DMS` env variable in your terminal or adding a `.env` file with the following content:
### Point to the CKAN instance
This project uses CKAN as a backend, so you need to point it to the desired CKAN instance URL. You can do so by setting up the `DMS` environment variable in your terminal or creating an `.env` file with the following content:
```
DMS=<ckan url>
```
- Run the app using:
### Run the app
To run the app in development mode, execute the following command on a terminal:
```
npm run dev
```
Congratulations, you now have something similar to this running on `http://localhost:3000`
![](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)
Congratulations, you now have something similar to this running on `http://localhost:3000`:
![](https://hackmd.io/_uploads/S1CsQ9jr2.png)
If you navigate to any of the dataset pages by clicking on the dataset title you will see something similar to this:
![](https://hackmd.io/_uploads/ryZRXcorn.png)
## Deployment
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fdatopian%2Fportaljs%2Ftree%2Fmain%2Fexamples%2Fckan-example&env=DMS&envDescription=URL%20For%20the%20CKAN%20Backend%20Ex%3A%20https%3A%2F%2Fdemo.dev.datopian.com)
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fdatopian%2Fportaljs%2Ftree%2Fmain%2Fexamples%2Fckan&env=DMS&envDescription=URL%20For%20the%20CKAN%20Backend%20Ex%3A%20https%3A%2F%2Fdemo.dev.datopian.com)
By clicking on this button, you will be redirected to a page which will allow you to clone the content into your own github/gitlab/bitbucket account and automatically deploy everything.
By clicking on this button, you will be redirected to a page which allows you to clone the base project into your own GitHub/GitLab/BitBucket account and automatically deploy it.
## Extra commands
@ -67,9 +74,46 @@ And run using the production build like so:
npm run start
```
## Extra steps
Feel free to customize your portal, a few suggestions would be.
- Connecting to a different CKAN backend and seeing how it looks
- Using the CKAN Object to build a `orgs` or `groups` page listing all the groups and orgs
- A showcase page for a specific group or org
- You could even use some of our [components](https://storybook.portaljs.org/) e.g: You could get the datastore contents for a resource using the `ckan.datastoreSearch(resourceId: string)` function and then display that as a line chart or vega chart.
## CKAN API
Thanks to TypeScript, you can get a list of all the API methods in `@portaljs/ckan` and their respective input/output values from the autocomplete functionality on your own editor. Here is a list with all of them for quick retrieval:
- `getDatasetsList()` - Gets a list of all the datasets in the portal
- `getDatasetsListWithDetails(options: DatasetListQueryOptions)` - Gets a list of all the datasets including their respective resources
- `packageSearch(
options: PackageSearchOptions
)` - Calls `package_search`
- `getDatasetDetails(datasetName: string)` - Calls `package_show`
- `getDatasetDetails(datasetName: string)` - Calls `package_activity_list` and automatically fills in the user information
- `getUser(userId: string)` - Calls `user_show`
- `getGroupList()` - Gets all the groups in the backend
- `getGroupsWithDetails()` - Gets all the groups in the backend with details
- `getGroupDetails(groupName: string)` - Gets all the details from a single group
- `getGroupActivityStream(groupName: string)` - Get a group activity list and automatically fills in the user information
- `getOrgList()` - Gets all the orgs in the backend
- `getOrgsWithDetails(accrossPages?: boolean)` - Calls `organization_list?all_fields=True`. If you set `accrossPages` to `true`, it will repeatedly call the API until all groups are returned.
- `getOrgDetails(orgName: string)` - Gets all the details from a single org
- `getOrgActivityStream(orgName: string)` - Gets a org activity list and automatically fills in the user information
- `getAllTags()` - Gets all tags in system with details
- `getResourcesWithAliasList()` - Gets all the resources in the datastore that have an alias assigned to them
- `datastoreSearch(resourceId: string)` - Calls datastoreSearch
- `getResourceMetadata(resourceId: string)` - Calls `resource_show`
- `getResourceMetadata(resourceId: string)` - Calls `datastore_info` on a resource
- `getFacetFields(field: string)` - Gets the possible values eg: getFacetFields("tags") will get you all the tags that are currently assigned to a dataset + how many datasets have that particular tag.
## Links
- [Repo](https://github.com/datopian/portaljs/tree/main/examples/ckan-example)
- [Live Demo](https://ckan-example.portaljs.org)
- [Repo](https://github.com/datopian/portaljs/tree/main/examples/ckan)
- [Live Demo](http://ckan.portaljs.org/)