Build your web app on top of Osada
Osada is an MIT Licensed “ActivityPub server based on the conversational interaction style. Includes groups, access control, events, and files/media management. Contains a Zot6 reference implementation and provides a bridge between the fediverse and nomadic networks.” (from the Osada project page)
Building a web app on top of Osada greatly speeds up your development. You get all the described features instantly. Osada also features multiple languages, a templating engine, and more. It’s hella easy.
We will build a basic “stock market” app, which requires that the user is authenticated. Our example is currently running at https://10.8.0.149.li/stocks
Before beginning the exercise, you need to download and install Osada.
Get it from the author’s git repository: https://framagit.org/macgirvin/osada
STEP ONE
We will create the files necessary to install our app into Osada, and generate our icon in the menu.
The icon should be 80px square png with transparency.
Below the osada install path, create a directory “addon” and below that, “stocks”
# mkdir -p addon/stocks
inside the stocks directory we start with three files: stocks.apd, stocks.png and stocks.php
stocks.apd is a text file with three lines that tells Osada our app icon, name and menu link (url).
url: $baseurl/stocks
name: Stocks
photo: $baseurl/addon/stocks/stocks.png
You can download an example here: https://10.8.0.149.li/addon/stocks/stocks.apd
stocks.png:
and stocks.php:
This file defines the menu item for our app. It also tells Osada how to install and remove our app. Our main app code will be in “Mod_Stocks.php” (However, we could use any unique file name).
Note: The comments area, which includes “Name, Description, Version”, etc. is used to display information about the app in the Osada admin panel. (screenshot below)
the stocks_app_menu function is the code used in generating the menu item for the app.
Now will create our App file. Initially, just a basic framework. Later, we can add the code.
Create a new file “Mod_Stocks.php”, inside the addon/stocks path.
The contents of this file should be:
init() function is called at the beginning of execution, get() handles routed http GET requests, and post() handles POST requests. (like if you are going to have the user submit form data)
The “$o” variable is the output, which is fed into the template system.
STEP TWO
Now we can “install” our app into the Osada admin panel, by navigating to “Admin” and “Addons”.
check the box next to “Stocks App” and it will become available to add to our menu. (The hamburger menu on the upper right, click that and you will see the App options at the bottom)
Click “Available Apps” on the left menu (it defaults to “Installed”), then you can Install the Stocks app.
After it is installed, you have two options: you can click the “Star” icon to add it to the hamburger menu, and you can click the thumbtack icon to add the Stocks App icon to the navigation bar at the top of the screen.
After installing our App, we can return to this admin panel to “Update”.
STEP THREE
Here’s what our app does so far:
To check that our App user is authenticated, we add the following code:
An authenticated user will have a local_channel() value greater than zero.
Use the t() function to handle translations. The notice() function shows a warning message. goaway() kills execution at that point, taking the user to the url specified. (this would be the register or login screen, in this case)
Now we can fill in our stock application, in the get() function of our Stocks class.
Storing and Retrieving User Data
An example web app which stores and retrieves user data is a basic currency exchange calculator. We will use the storage facility in Osada to store which currencies are selected in the drop-down list. When the user returns to the site, it will remember which options were selected.
We begin with out basic app framework and fill in the “get()” and “post()” functions. post() happens when the user submits the form.
We shall perform our exchange calculations and take care of housekeeping in the do_xchg() function
the “$r1” and “$r2” parameters are the selected currencies. If they are blank we use defaults.
The Osada get_pconfig() function queries the user storage facility for a value. The first parameter of get_pconfig() is the user Id, the second is the storage group and the third is the variable name. We shall use user id “0” to store site-wide data. (In this example the site-wide data is the currency exchange rates). Since the exchange rate data is not cheap, we will query the site once per 24 hours. We’ll use the pconfig value “lastupdate” to keep track of the last time we fetched the data. If we have not fetched the data, or if there was an error, lastupdate is zero, which will force a re-download.
We shall also store the exchange rate data in user id “0” space. The system can handle data of size: Medium Text, which is more than enough space for our exchange rate data.
The user-selected currencies will be stored in selected_currency_r1 and selected_currency_r2. In a GET request we will use the stored information, if available. That way the system will “remember” what the user selected the last time they visited the page.
Then we will validate and store the r1 and r2 currencies for use later. If the user supplied invalid data it wipes the records and sends the user back to the home page.
We use the Osada function local_channel() to get the user id.
To download the complete Currency exchange app, you can use the following link:
https://10.8.0.149.li/xchg.tar.gz
(you will need a key from fixer.io — the limited use free account should work fine)
If you have any questions or need help, feel free to contact me by email at 986@10.8.0.149.li
