add network data as a recipe

docs/pages/06-recipes.md

@@ -8,27 +8,32 @@
 - [String Functions](#string-functions)
 - [Get Files from a Dir](#get-files-from-a-directory)
 - [Reading Writing Files](#reading--writing-files)
+- [Getting network Data](#getting-network-data)
 - [Templates](#templates)
 
 Methods and ways to be able to do basic tasks while working with alvu
 
 ## Watching for changes
 
-I use [entr](https://github.com/eradman/entr) as a file notifier which can run arbitrary commands on file changes, which can be done like so to have alvu monitor for files
+I use [entr](https://github.com/eradman/entr) as a file notifier which can run
+arbitrary commands on file changes, which can be done like so to have alvu
+monitor for files
 
 ```sh
 ls docs/**/* | entr -cr alvu --path='./docs'
 ```
 
-> **Note**: since v0.2.9, alvu comes with it's own file watcher and live-reload but is limited to the `public` and `pages` directory and it is still recommended to use `entr` if you wish to handle watching custom paths 
+> **Note**: since v0.2.9, alvu comes with it's own file watcher and live-reload
+> but is limited to the `public` and `pages` directory and it is still
+> recommended to use `entr` if you wish to handle watching custom paths
 
-This will list all files in the `docs` folder (root of an alvu project) and then run the alvu command while specifying the base path to be `./docs`
+This will list all files in the `docs` folder (root of an alvu project) and then
+run the alvu command while specifying the base path to be `./docs`
 
 ## Importing other lua files
 
-You'll need to work with lua files that are in a sibling directory
-in the project and you can do so by adding them to the scripts
-`package.path` like so
+You'll need to work with lua files that are in a sibling directory in the
+project and you can do so by adding them to the scripts `package.path` like so
 
 ```lua
 -- specify that you wish to taken in any `.lua` file in the `lib` folder
@@ -40,7 +45,8 @@ local lib = require("lib.utils")
 
 ## String Interpolation
 
-There's no way to directly do string interpolation in lua but is almost always needed so here's how you can implement a small helper for it
+There's no way to directly do string interpolation in lua but is almost always
+needed so here's how you can implement a small helper for it
 
 ```lua
 local function interpolate(s, tab)
@@ -53,7 +59,8 @@ interpolate("this is an ${message} string", { message = "interpolated" })
 
 ## String Functions
 
-A helper library is injected into all alvu hook files which can be required into the script to help with basic string manipulation and querying
+A helper library is injected into all alvu hook files which can be required into
+the script to help with basic string manipulation and querying
 
 ```lua
 local strings = require("strings")
@@ -63,14 +70,18 @@ then
 end
 ```
 
-You can read more about these from the [gopher-lua-libs](https://github.com/vadv/gopher-lua-libs/tree/master/strings) repo.
+You can read more about these from the
+[gopher-lua-libs](https://github.com/vadv/gopher-lua-libs/tree/master/strings)
+repo.
 
 ## Get files from a directory
 
-If working with blogs and nested data you might wanna get files in a directory and you can use the following function
+If working with blogs and nested data you might wanna get files in a directory
+and you can use the following function
 
-There's 2 methods, you can either use the `alvu` helper library or you can add the `scandir` function shown below to
-your `libs` folder if you wish to maintain control over the file reading functionality
+There's 2 methods, you can either use the `alvu` helper library or you can add
+the `scandir` function shown below to your `libs` folder if you wish to maintain
+control over the file reading functionality
 
 - Using `alvu` helpers
 
@@ -99,8 +110,9 @@ end
 
 ## Reading / Writing files
 
-This can be done with native lua functions but here's a snippet of
-the `onFinish` hook from [reaper.is](https://github.com/barelyhuman/reaper.is)' RSS Feed hook
+This can be done with native lua functions but here's a snippet of the
+`onFinish` hook from [reaper.is](https://github.com/barelyhuman/reaper.is)' RSS
+Feed hook
 
 ```lua
 function OnFinish()
@@ -134,16 +146,105 @@ function OnFinish()
 end
 ```
 
+## Getting Network Data
+
+Getting data at build time for dynamic data is a very common usecase and this is
+something that alvu supports.
+
+The network data needs to be fetched from a hook, let's take a simple example.
+
+I need to get downloads for a certain set of packages that've been published to
+the NPM Registry.
+
+```lua
+-- require the needed packages. 
+-- both http and json are injected packages by alvu and 
+-- dont need any dependencies from lua to be added
+local http = require("http")
+local json = require("json")
+
+-- we only want this hook to run for the file 
+-- packages.md
+ForFile = "packages.md"
+
+local npm_url = "https://api.npmjs.org/downloads/point/last-month/"
+
+-- tiny utility function that takes in 
+-- a pkg_name and returns the number of downloads from 
+-- the request. 
+-- we use the `json` utility to parse the text response
+-- into a json
+local function get_downloads_for_pkg(pkg_name)
+    local response,error_message = http.get(npm_url..pkg_name)
+    local body_json = json.decode(response.body)
+    return body_json.downloads
+end
+
+local packages = {
+    "@barelyhuman/tocolor",
+    "@barelyhuman/pipe",
+    "@barelyhuman/preact-island-plugins",
+    "@barelyreaper/themer",
+    "jotai-form"
+}
+
+function Writer(source_data)
+    local source = json.decode(source_data)
+
+    -- create a table with the download count for each package,
+    -- mentioned in the `packages` variable
+    local downloads_table = {}
+
+    for k,pkg_name in ipairs(packages) do
+        local download_count = get_downloads_for_pkg(pkg_name)
+        table.insert(downloads_table,{
+            title = pkg_name,
+            downloads = download_count
+        })
+    end
+
+    -- Pass down the data to file that's being rendered, in this case `packages.md` 
+    return json.encode({
+		data = {
+			packages = downloads_table,
+		},
+	})
+end
+```
+
+Once you have the hook ready, you can now add in the file this is for.
+`pages/packages.md`
+
+Which would look, something like this.
+
+```md
+# Packages
+
+| name                     | downloads(last 30 days) |
+| ------------------------ | ----------------------- |
+| {{range .Data.packages}} |                         |
+| {{.title}}               | {{.downloads}}          |
+| {{end}}                  |                         |
+```
+
+Here the `range .Data.packages` loops through the elements that were returned
+from the hook on the `data` parameter, and you can now point to the variables
+you need to get the required data into the template.
+
 ## Templates
 
-The most preferred way of using alvu is to avoid having to construct
-hooks and use existing example repositories as the source, this gives us the advantage of not having to spend time writing similar static site generation logic while keeping it easy to extend.
+The most preferred way of using alvu is to avoid having to construct hooks and
+use existing example repositories as the source, this gives us the advantage of
+not having to spend time writing similar static site generation logic while
+keeping it easy to extend.
 
 ### Official Templates
 
-[alvu-foam-template](https://github.com/barelyhuman/alvu-foam-template) - Foam plugin template for writing a wiki styled website
+[alvu-foam-template](https://github.com/barelyhuman/alvu-foam-template) - Foam
+plugin template for writing a wiki styled website
 
 ### Community Templates
 
-Feel free to add in your templates here via PR's on the [source repo](http://github.com/barelyhuman/alvu) or
-mailing [me](mailto:ahoy@barelyhuman.dev)
+Feel free to add in your templates here via PR's on the
+[source repo](http://github.com/barelyhuman/alvu) or mailing
+[me](mailto:ahoy@barelyhuman.dev)