Merge pull request #9 from rust-diplomat/custom-func-docs

Adding documentation for custom functions

src/SUMMARY.md

@@ -29,4 +29,5 @@
   - [Attributes](demo_gen/attributes.md)
   - [Configuring Markup](demo_gen/markup.md)
   - [Configuring the Default Renderer](demo_gen/renderer.md)
-  - [Making Your Own Renderer](demo_gen/custom_renderer.md)
+  - [Making Your Own Renderer](demo_gen/custom_renderer.md)
+  - [Making Custom Functions](demo_gen/custom_functions.md)

src/demo_gen/attributes.md

@@ -83,4 +83,8 @@ mod ffi {
 
 Which creates the following HTML output:
 
-!["AddResult.getAddStr" in large text. Below are two inputs: one labelled "x" that has a value of 10, and one labelled "y" that has a value of 2. Below is a submit button. There is output below the button, with the label "Output" and a value of 12.](images/demo_output_renamed.png)
+!["AddResult.getAddStr" in large text. Below are two inputs: one labelled "x" that has a value of 10, and one labelled "y" that has a value of 2. Below is a submit button. There is output below the button, with the label "Output" and a value of 12.](images/demo_output_renamed.png)
+
+### \#\[diplomat::demo(custom_func="...")\]
+
+See [Making Custom Functions](./custom_functions.md).

src/demo_gen/custom_functions.md

@@ -0,0 +1,78 @@
+# Making Custom Functions
+
+## What is a custom function?
+
+demo_gen tends towards automagical configuration. demo_gen will do its best to take Rust functions and convert them into JS output.
+
+But there arise situations where we want to create our own custom Javascript functions to demonstrate our library's capabilities to the user, then add them to demo_gen's output. This may be the case if you want to demonstrate functionality that is more involved than demo_gen's automagical work.
+
+### Example
+Let's look at the [quickstart](quickstart.md) repository for an example.
+
+We only have one function exposed: `get_add_str(left : u32, right: u32)`.
+
+What if we have variables `a`, `b`, and `c`, and we want to show the user the results of calling:
+
+`get_add_str(a, b)` and `get_add_str(b, c)`?
+
+We can do this without adding a new binding, through the use of a custom Javascript function.
+
+## \#\[diplomat::demo(custom_func="...")\]
+
+`#[diplomat::demo(custom_func="filename.mjs")]` can be added above any `struct` definition. demo_gen will search for files relative to `lib.rs`, and add the contents of `filename.mjs` to its output.
+
+Then demo_gen will import the default export of `filename.mjs`, and append it to the list of [RenderInfo](https://github.com/rust-diplomat/diplomat/blob/main/docs/demo_gen.md#step-two-constructing-renderinfo) termini.
+
+### Example
+So, first we create a file called `adder_custom.mjs` in the same folder as `adder_bindings/src/lib.rs`:
+
+```js
+// adder_bindings/src/adder_custom.mjs
+import { lib } from "./index.mjs";
+export default {
+    "AddThreeVariables": {
+        func: (a, b, c) => { return lib.AddResult.getAddStr(a, b) + " and " + lib.AddResult.getAddStr(b, c); },
+        funcName: "Add a + b, b + c",
+        parameters: [
+            {
+                name: "a",
+                type: "number"
+            },
+            {
+                name: "b",
+                type: "number"
+            },
+            {
+                name: "c",
+                type: "number"
+            }
+        ]
+    }
+}
+```
+
+Then we make sure to link `adder_custom.mjs` in `lib.rs`:
+
+```rs
+// adder_bindings/src/lib.rs
+#[diplomat::bridge]
+mod ffi {
+    use std::fmt::Write;
+
+	#[diplomat::opaque]
+	#[diplomat::rust_link(basic_adder, Mod)]
+    #[diplomat::demo(custom_func="adder_custom.mjs")]
+	pub struct AddResult;
+
+	impl AddResult {
+		pub fn get_add_str(left : u32, right : u32, write: &mut DiplomatWrite) {
+			write.write_str(&format!("{}", basic_adder::add(left, right))).unwrap();
+			write.flush();
+		}
+	}
+}
+```
+
+And our exported object is then added to `RenderInfo`s list of render termini, and is evaluated by the renderer accordingly!
+
+If you [regenerate the bindings and start the web server](https://rust-diplomat.github.io/book/demo_gen/quickstart.html#getting-started), you should see `Add a + b, b + c` in the list of functions.

src/demo_gen/custom_renderer.md

@@ -6,4 +6,4 @@ Inside of `index.mjs`, demo_gen outputs an object called `RenderInfo` that point
 
 This is meant to slot in to almost any Javascript solution with ease, but if there's an issue with `RenderInfo`s setup that is not quite compatible with your solution, please [open an issue](https://github.com/rust-diplomat/diplomat/issues/new?labels=B-demo_gen).
 
-The exact structure of `RenderInfo` is available in the demo_gen [design docs](https://github.com/rust-diplomat/diplomat/blob/main/docs/design_doc.md#step-two-constructing-renderinfo).
+The exact structure of `RenderInfo` is available in the demo_gen [design docs](https://github.com/rust-diplomat/diplomat/blob/main/docs/demo_gen.md#step-two-constructing-renderinfo).