@ -15,35 +15,35 @@ The Padliography is a tool to keep track of our pads. It is built to interact wi
## Quick Start
When you enter the Padliography homepage, it loads by default the XPUB2 archive. Just above the pads list you can read from where the pads are being fetched, and change the source by inserting the title of the page in which tne archive you desire is.
The Padliography homepage loads by default the XPUB2 archive. Just above the pads list it is indicated from where the pads are being fetched, and it is possible to change source by inserting the title of the page in which the other archive is.
To create a brand new archive click on `Init a new padliography` and insert a title for the page and a short description to put in the wiki.
**Watch out:** This action will create a new blank page, so check that there is not already something with the same title in the wiki, or it will be overwritten. Thanks to the wiki's history it is possible to recover overwritten contents, so we are safe and the contents are not in total danger.
To create a brand new archive click on `Init a new padliography` and insert a title and a short description to put in the wiki.
**Watch out:** This action will create a new blank page, so check that there is not already something with the same title in the wiki, or it will be overwritten. Thanks to the wiki's history, it is possible to recover overwritten contents, so the contents are not in total danger.
Use the **Add a new pad** form to insert a pad in the archive. The required information are a title, the URL of the document, a short overview, a date and some categories. The categories are custom, and are usefull to organize pads in themes or context.
Use the **Add a new pad** form to insert a pad in the archive. The required information are a title, the URL of the document, a short description, a date and some categories. The categories are custom, and are useful to organize pads in themes or context.
The **Filter Categories** section loads all the categories from the current archive and use it to filter the list of pads.
The **Filter Categories** section loads all the categories from the current archive and uses it to filter the list of pads.
The list of pads is sortable. Just click on the headers to order the pad, click twice to invert the order.
The list of pads is sortable. Click on the headers to order the pad, click twice to invert the order.
At the moment this Padliography instance runs on the [Soupboat](https://hub.xpub.nl/soupboat/). If you are using it a lot, consider to install a new instance on a different environment, in order not to put a strain on the small Raspberry. It should be fine anyway.
At the moment this Padliography instance runs on the [Soupboat](https://hub.xpub.nl/soupboat/). If you are using it a lot or with a lot of pads, consider to install a new instance on a different environment, in order not to put a strain on the small Raspberry. It should be fine anyway.
## How does it work
To have an overview over the lifecycle of the Padliography let's start from the wiki.
The pads are stored in a page with a minimal template. They are organized in a table that has the CSS class `padliography`.
The pads are stored in a page with a minimal template, such as the title, a short description and a section named Padliography with the archive. Here they are organized in a table that has the CSS class `padliography`.
Through the [MediaWiki API](https://pzwiki.wdka.nl/mediadesign/Special:ApiSandbox) we can request the contents of this page from somewhere else. This somewhere is a small Raspberry Pi called Soupboat and installed on the 4th floor of the WdKA.
Through the [MediaWiki API](https://pzwiki.wdka.nl/mediadesign/Special:ApiSandbox) we can request the contents of this page from somewhere else. This somewhere else is a small Raspberry Pi called Soupboat and installed on the 4th floor of the WdKA.
The soupboat is a small server, and it runs a [Flask](https://flask.palletsprojects.com/en/2.2.x/) application that interact with the wiki using the [mwclient](https://mwclient.readthedocs.io/en/latest/index.html) python library.
The Soupboat is a small server, and it runs a [Flask](https://flask.palletsprojects.com/en/2.2.x/) application that interacts with the wiki using the [mwclient](https://mwclient.readthedocs.io/en/latest/index.html) python library.
When a user enter the homepage of the padliography, the Flask application returns a [Vue3](https://vuejs.org/) app and through that request to the wiki API for the list of pads.
When a user enters the homepage of the padliography, the Flask application returns a [Vue3](https://vuejs.org/) app and through that requests to the wiki API the list of pads.
The response from the MediaWiki API is parsed on the server using [BeautifulSoup](https://www.crummy.com/software/BeautifulSoup/), that try to find the `padliography` table with some CSS selectors and then to build a list of pads organized by the properties of the table's headers. The list of table is sent to the Vue app as a JSON message, and used to build a fancy sortable table and filtering system.
The response from the MediaWiki API is parsed on the server using [BeautifulSoup](https://www.crummy.com/software/BeautifulSoup/), that tries to find the `padliography` table with some CSS selectors and then builds a list of pads organized by the properties of the table's headers. The list of table is sent to the Vue app as JSON message, and used to compile a fancy sortable table and filtering system.
When a user interacts with the form to add a new pad the process is the same, but in the opposite direction: first the Vue app send the data to the Flask application that in turns tries to add it in the archive wiki page.
When a user interacts with the form to add a new pad the process is the same, but in the opposite direction: first the Vue app sends the data to the Flask application that in turns tries to add it in the archive wiki page.
## Development
@ -101,5 +101,5 @@ At this step you are up and running, the padliography should be able to fetch th
## License
This Padliography was distilled with the help and within the context of XPUB, 2022.
This Padliography was distilled with the help and within the context of XPUB, 2022.
Copyleft with a difference: This is a collective work, you are invited to copy, distribute, and modify it under the terms of the [CC4r](https://constantvzw.org/wefts/cc4r.en.html).
