feature/templating-support (#132)

Added package extensions for Mustache.jl and OteraEngine.jl to provide better support for templating * add Dates compat section * removed Manifest.toml and added links to docs in both templating extensions * Added from_file keyword arg to both mustache() and otera() templating functions * Unified the api between extensions, data is passed without keywords as the first argument
OxygenFramework · Dec 14, 2023 · 59a5092 · 59a5092
1 parent 77a19dd
commit 59a5092
Show file tree

Hide file tree

Showing 18 changed files with 711 additions and 384 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,4 @@
 .vscode
 .DS_Store
+Manifest.toml
+test/Manifest.toml
diff --git a/Manifest.toml b/Manifest.toml
diff --git a/Project.toml b/Project.toml
@@ -1,19 +1,23 @@
 name = "Oxygen"
 uuid = "df9a0d86-3283-4920-82dc-4555fc0d1d8b"
 authors = ["Nathan Ortega <[email protected]>"]
-version = "1.2"
+version = "1.2.0"
 
 [deps]
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3"
 JSON3 = "0f8b85d8-7281-11e9-16c2-39a750bddbf1"
 MIMEs = "6c6e2e6c-3030-632d-7369-2d6c69616d65"
 RelocatableFolders = "05181044-ff0b-4ac5-8273-598c1e38db00"
+Requires = "ae029012-a4dd-5104-9daa-d747884805df"
 Sockets = "6462fe0b-24de-5631-8697-dd941f90decc"
 
 [compat]
+Dates = "^1"
 HTTP = "^1"
 JSON3 = "^1.9"
 MIMEs = "^0.1.4"
 RelocatableFolders = "^1"
+Requires = "^1"
+Sockets = "^1"
 julia = "^1.6"
diff --git a/README.md b/README.md
@@ -30,6 +30,7 @@ Breathe easy knowing you can quickly spin up a web server with abstractions you'
 - Built-in Cron Scheduling (on endpoints & functions)
 - Middleware chaining (at the application, router, and route levels)
 - Static & Dynamic file hosting
+- Templating Support
 - Route tagging
 - Repeat tasks
 
@@ -363,6 +364,105 @@ end
 serve()
 ```
 
+
+## Templating
+
+Rather than building an internal engine for templating or adding additional dependencies, Oxygen 
+provides two package extensions and helper functions to support `Mustache.jl` and `OteraEngine.jl` templates.
+
+Oxygen provides a simple wrapper api around both packages that makes it easy to render templates from strings,
+templates, and files. This api returns a `render` function which takes accepts input arguments to fill out the
+template.
+
+In all scenarios, the rendered template is formatted inside a single HTTP.Response object ready to get served by the api.
+By default, the mime types are auto-detected either by looking at the content of the template or the extension name on the file.
+If you know the mime type you can pass it directly through the `mime_type` keyword argument to skip the detection process.
+
+### Mustache Templating
+Please take a look at the [Mustache.jl](https://jverzani.github.io/Mustache.jl/dev/) documentation to learn the full capabilities of the package
+
+Example 1: Rendering a Mustache Template from a File
+
+```julia
+using Oxygen
+
+# Load the Mustache template from a file and create a render function
+render = mustache("./templates/greeting.txt", from_file=false)
+
+@get "/mustache/file" function()
+    data = Dict("name" => "Chris")
+    return render(data)  # This will return an HTML.Response with the rendered template
+end
+```
+
+Example 2: Specifying MIME Type for a plain string Mustache Template
+```julia
+using Oxygen
+
+# Define a Mustache template (both plain strings and mustache templates are supported)
+template_str = "Hello, {{name}}!"
+
+# Create a render function, specifying the MIME type as text/plain
+render = mustache(template_str, mime_type="text/plain") # mime_type keyword arg is optional 
+
+@get "/plain/text" function()
+    data = Dict("name" => "Chris")
+    return render(data)  # This will return a plain text response with the rendered template
+end
+```
+
+### Otera Templating
+Please take a look at the [OteraEngine.jl](https://mommawatasu.github.io/OteraEngine.jl/dev/tutorial/#API) documentation to learn the full capabilities of the package
+
+Example 1: Rendering an Otera Template with Logic and Loops
+
+```julia
+using Oxygen
+
+# Define an Otera template
+template_str = """
+<html>
+    <head><title>{{ title }}</title></head>
+    <body>
+        {% for name in names %}
+        Hello {{ name }}<br>
+        {% end %}
+    </body>
+</html>
+"""
+
+# Create a render function for the Otera template
+render = otera(template_str)
+
+@get "/otera/loop" function()
+    data = Dict("title" => "Greetings", "names" => ["Alice", "Bob", "Chris"])
+    return render(data)  # This will return an HTML.Response with the rendered template
+end
+```
+
+In this example, an Otera template is defined with a for-loop that iterates over a list of names, greeting each name.
+
+Example 2: Running Julia Code in Otera Template
+```julia
+using Oxygen
+
+# Define an Otera template with embedded Julia code
+template_str = """
+The square of {{ number }} is {< number^2 >}.
+"""
+
+# Create a render function for the Otera template
+render = otera(template_str)
+
+@get "/otera/square" function()
+    data = Dict("number" => 5)
+    return render(data)  # This will return an HTML.Response with the rendered template
+end
+
+```
+
+In this example, an Otera template is defined with embedded Julia code that calculates the square of a given number. 
+
 ## Mounting Static Files
 
 You can mount static files using this handy function which recursively searches a folder for files and mounts everything. All files are 

diff --git a/src/Oxygen.jl b/src/Oxygen.jl
@@ -15,4 +15,8 @@ export @get, @post, @put, @patch, @delete, @route, @cron,
         configdocs, mergeschema, setschema, getschema, router,
         enabledocs, disabledocs, isdocsenabled, starttasks, stoptasks,
         resetstate, startcronjobs, stopcronjobs
+
+# Load any optional extensions
+include("extensions/load.jl");
+
 end
diff --git a/src/extensions/load.jl b/src/extensions/load.jl
@@ -0,0 +1,19 @@
+using Requires
+
+function __init__()
+
+
+    ################################################################
+    #                       Templating Extensions                     #
+    ################################################################
+
+    @require Mustache="ffc61752-8dc7-55ee-8c37-f3e9cdd09e70" begin
+        include("templating/mustache.jl"); using .MustacheTemplating
+        export mustache
+    end
+
+    @require OteraEngine="b2d7f28f-acd6-4007-8b26-bc27716e5513" begin
+        include("templating/oteraengine.jl"); using .OteraEngineTemplating
+        export otera
+    end
+end