Skip to content

Home

Jump to bottom
Judson Lester edited this page Dec 14, 2023 · 3 revisions

[This wiki is under development. Information here may be moved to other pages or markdown files within the text.

Key Technologies

About CKAN

CKAN is an open-source data-management system, and it is the heart of Access the Data. The core functionality of the site is handled by CKAN, and the current design is added as an extension.

The CKAN documentation is well-maintained and includes information at all levels of use, including users, admins, and maintainers. At the moment, developers will mostly need to pay attention to the extending guide and the theming guide, which are closely related.

When extending the base CKAN application, it's sometimes necessary to refer to the original CKAN code. For example, to extend an HTML template, you'll need to know the name of the template and the names of blocks used in it. We are currently extending CKAN 2.10.1, which is available on GitHub.

Local Development

The main README is from the CKAN Docker project that this repo was based on. It may eventually be updated, but it includes good information for getting the app running locally in docker. See the section on Development Mode:

To build the images:

docker compose -f docker-compose.dev.yml build

To start the containers:

docker compose -f docker-compose.dev.yml up

Live Deployment

For details about how Access the Data is deployed, see Operations

Contributing code

The main branch of the repository is main. [ATD did not require a development branch during the MVP phase, but it will become necessary once a deployed instance of the project exists.]

When making changes to the code, create a branch off of main and create a pull request to merge the changes into main. [To come: Procedures for approving a PR.]

Repo Organization

AtD is a CKAN extension, and all of the code modifying the app is located in src/ckanext-hack4laatd/. Other directories (ckan and postgres) manage the deployment of the app. The ckanext-hack4laatd directory was set up using the CKAN extension tool, and most of the current development has been in the nested hack4laatd directory.

hack4laatd

Within the main extension directory, the points of interest are:

  • assets/style.css. During MVP, styles were added to this single file for speed.
  • templates. Templates to override and extend the templates provided by CKAN.

CSS Styles

During MVP CSS styles were managed in a single file, which was quick to iterate. Future phases of development may want to adopt a preprocessor (see Assets in CKAN's docs). CKAN is bundled with Bootstrap 5, and templates attempt to maintain the same conventions in classes.

Site Organization

The routes and templates of the site are defined in the underlying CKAN code. Routes and controllers appear in the views folder and the templates are in the templates folder. They are generally organized with Flask Blueprints listed below.

Home

The Home blueprint holds endpoints at the base of the app. These are the only endpoints that currently have design.

  • / The main landing page of the site.
  • /about The about page of the site.
  • /volunteer This is not an endpoint that exists in the app yet but there is design for it, and CKAN will need to be extended to include it.

Dataset

The main blueprint for viewing and searching datasets.

  • /dataset Displays totals for the dataset collection
  • /dataset/new Form for creating a new dataset
  • /dataset/<id> Viewing a specific dataset
  • /dataset/edit/<id> A form for editing the information about a dataset
  • /dataset/resources/<id> A form for adding and managing resources for a dataset (e.g., CSV files).
  • /dataset/delete/<id> Confirmation form before deleting a dataset.
  • /dataset/followers/<id> Users following changes to a dataset.
  • /dataset/groups/<id> Groups a dataset is part of.

Dashboard

A blueprint for views that relate to a logged-in user.

  • /dashboard/datasets
  • /dashboard/groups
  • /dashboard/organizations

Admin

Similar to dashboard, but only for admin users.

  • /admin Managing admin users.
  • /admin/config Sitewide options, such as icons and some text descriptions.
  • /admin/trash Options for purging deleted datasets.

Organization / Group

Organizations are entities that are authorized to create and manage datasets. Groups are collections of curated datasets that can be created by any registered user. An organization might be something like the City of Los Angeles or UCLA. A group might be a collection of datasets related to weather.

Groups and Organizations share the same blueprint structure (that is, you can replace organization with group for all of the endpoints listed here to get a working endpoint relating to groups).

  • /organization Summary of all organizations.
  • /organization/new Form to create an organization.
  • /organization/<id> Information on a single organization
  • /organization/edit/<id> Form to edit an organization
  • /organization/about/<id> Detailed about information for an organization (less information about its datasets, extensive information about who the org is).
  • /organization/members/<id> View and edit members of an organization
  • /organization/member_new/<id> Add or invite a new member of an organization.
  • /organization/edit/<id> Form to edit an organization
  • /organization/bulk_process/<id> Manage datasets of an organization in bulk.
  • /organization/delete/<id> Confirmation form before deleting an organization.

User

Blueprint for user management. Many of these endpoints relate to the logged-in user (you).

  • /user Summary of registered users.
  • /user/<id> View a user's (public) profile.
  • /user/edit Form to edit your user profile.
  • /user/edit/<id> Form to edit another user profile as admin.
  • /user/register Register a new user.
  • /user/login Login page.
  • /user/logged_out_redirect Landing page after logging out.
  • /user/delete/<id> Delete a user as admin.
  • /user/reset Form to reset a password.
  • /user/followers/<id> Users following another user.
  • /user/<id>/api-tokens Manage your api tokens.
Clone this wiki locally