timea-solid / SolidHelloWorlds

A list of introductory Solid projects with different stacks.

Welcome to Solid Hello Worlds!

• The App is running in PRODUCTION on my Solid Pod for now: https://timea.solidcommunity.net/HelloWorld

• The App is running in DEVELOPMENT on GitHub pages - which is updated with every push to the master branch.

• The user manual is under docs.

• Tutorial for Solid Hello Worlds.

• The App is part of the Linked Data-driven frontends blog post series from SolidOS team.

Note: This project is built on prototype libraries. And it serves multiple goals.

Table of contents

• Purpose of App
• About the code
• Data Model
  • Solid Hello Worlds Thesaurus
  • Solid Hello Worlds Ontology
• How to run the code locally
  • Improvements and ideas
  • Known TODOs
• How to deploy the code
  • Run on a Pod
  • Run as a distributed system
• Attribution

Purpose of App

This demo serves multiple goals.

1. A collection of beginner-friendly Solid code examples. The Solid Community survey identified this as one of the biggest needs in the Solid Community.
2. A reply to a conversation over at the Solid forum.
3. Create a Solid Web App with low code by defining the Web App UI in RDF (no need to know any frontend framework).
4. Showcase how the 'Single point of truth' can be achieved and used with Solid.

About the code

This Web App makes use of HTML, Simple CSS, RDF, and basic JavaScript. The heavy lifting (rendering the UI from RDF) is taken care of libraries one can simply reuse such as Comunica, Mashlib, and solid-ui-components, see attributions for links.

• Initially, the application was intended to be a one-page web application. It all starts at index.html. However, because I make use of different libs, I added additional pages but kept them in separate folders in the structure in order to follow how to use the libs best.

• Details:

  • facetedSearchPage is the simplest example: it theoretically ONLY needs an HTML and an RDF file (and CSS if you want to make it shinier) and the solid-ui (or mashlib) and solid-ui-components libs. This part of the app makes use of Jeff's solid-ui-components lib which has elements for menus, like accordions. appsDisplay.ttl is the RDF form which the frontend is generated from, and it is of course mapped to the data model (Knowledge Graph and Ontology) used in the data we want displayed (which is also in RDF, stored on a Pod).
  • editDataPage is based on same principles: you have an RDF file, helloWorldForm.ttl, a form, based on which the frontend is rendered. Again it is based on the data model (ontology) the raw data is using. Here we make use of the original solid-ui forms lib developed by Sir Tim Berners-Lee. This lib allows us to EDIT the data in place.
  • adminPage uses Solid Login to give access to some admin activities such as checking snapshots of our data.
  • *Note adminPage does not work when app is deployed on a Pod due to mashlib. If deployed on another platform it should work.

Data Model

The Solid Hello Worlds data model is a Knowledge Graph which consists of:

• a Solid Hello Worlds Thesaurus
• a Solid Hello Worlds Ontology

Solid Hello Worlds Thesaurus

• The raw data, saved in the repo only to serve as an example, example-helloWorld.ttl is a Thesaurus about Solid code examples (aka. Solid Hello Worlds). This data can be on any Pod.
• The Solid Hello Worlds Thesaurus, example-helloWorld.ttl, is described with the help of SKOS and an own created ontology.

The Solid Hello Worlds Thesaurus is based on SKOS and contains skos:concepts that describe:

• Solid code examples (Examples)
• Code stacks divided in:
  • Code Stack, Solid library, and Semantic Web library (see thesaurus image).
• Technical use cases

The Solid Hello Worlds Thesaurus structure drives the facets/the accordion menu on the search (main page). When I say the structure drives the menu it technically means a SPARQL query executed on the Solid Hello Worlds Thesaurus appsDisplay.ttl automatically fills the search options for each accordion.

The Solid Hello Worlds Thesaurus looks like this:

Solid Hello Worlds Thesaurus

Solid Hello Worlds Ontology

The ontology extends the SKOS scheme with predicates that help further describe or connect/descriove the skos:concepts. The ontology looks like:

Solid Hello Worlds Ontology

How to run the code locally

1. Git clone repo.
2. OPTIONAL: Change the links to the data model and forms over in the config.js. Defaults are the Knowledge Graph (KG) and form of the project.
3. OPTIONAL: Change the link to the appsDisplay.ttl over in the index.html
4. OPTIONAL: Change the link to your Knowledge Graph (KG) in the appsDisplay.ttl L20 and L42
5. Run with npm run start or npx vite.

NOTE Unfortunately solid-ui only works with absolute URLs reason why the development KG and forms are the ones deployed on my Pod.

Improvements and ideas

• There are problems with the usage of GROUP_CONCAT which gives XMLSchema#string in SPARQL queries. However, the SPARQL queries and the thesaurus structure were changed to overcome this need.
• If you have improvement ideas or find bugs please open a Git Issue.
• Feel free to commit PRs.

Known TODOs

• see Git Issues

How to deploy the code

Read about my experiements with deployments of the app.

Run on a Pod

1. Create a folder on your Pod and make it public.
2. Deploy the data from this project to the Pod in the same exact structure. Be sure to have data, src, lib, static, index.html, and their contents on your Pod.
3. Change the links to the data model and forms over in the config.js. Defaults are the Knowledge Graph (KG) and form of the project which will not work.
4. Change the link to the appsDisplay.ttl over in the index.html
5. Change the link to your KG in the appsDisplay.ttl L20 and L42
6. Navigate to the Pod folder name you created for your project and you should see the index.html rendered.

Example: my running demo is simply on my Pod, in a HelloWorld folder over at https://timea.solidcommunity.net/HelloWorld/components/. I made sure the HelloWorld folder has public access.

NOTE make sure to use minified versions of the libs (solid-ui, mashlib especially) otherwise the app loads quite slowly.

NOTE the adminPage is not working on a Pod deployment due to mashlib.

NOTE Unfortunately solid-ui only works with absolute URLs reason why the development Knowledge Graph (KG) and forms are the ones deployed on my Pod.

Run as a distributed system

1. Create a folder on a Pod and make it public.
2. Rename the KG example-helloWorld.ttl to helloWorld.ttl and deploy in the new folder.
3. Create a folder on a Pod for your forms, can be the same folder or separate folders for each form. Make sure they are publicly readable.
4. Deploy the appsDisplay.ttl form and the helloWorldForm.ttl form to the new folder/s. Keep the names.
5. Change the links to the data model and forms over in the config.js. Defaults are the KG and form of the project which will not work.
6. Change the link to the appsDisplay.ttl over in the index.html
7. Change the link to your KG in the appsDisplay.ttl L20 and L42
8. Navigate to your project on your platform and you should see the index.html rendered.

NOTE make sure to use minified versions of the libs (solid-ui, mashlib especially) otherwise the app loads quite slowly.

NOTE the adminPage is not working on a Pod deployment due to mashlib.

NOTE Unfortunately solid-ui only works with absolute URLs reason why in the config.js we need full URLs.

Example: my running demo is deployed, in this case, on two of my Pods. The main code is over in the HelloWorld folder on https://timea.solidcommunity.net/SolidHelloWorldDistributed/. The data and forms are on another Pod over at https://solidweb.me/timeacss/public/SolidHelloWorlds/. I made sure the SolidHelloWorlds folder has public access because this is where the single point of truth (the Knowledge Graph (KG)) is.

Attribution

• Jeff Zucker's solid-ui-components
• Simple CSS
• Comunica - a knowledge graph querying framework for JavaScript
• Mashlib - Solid compatible library for application-level functionality
• Solid-ui forms - User interface widgets and utility for Solid