diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 1762df4..645a190 100644 --- a/src/SUMMARY.md +++ b/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) \ No newline at end of file + - [Making Your Own Renderer](demo_gen/custom_renderer.md) + - [Making Custom Functions](demo_gen/custom_functions.md) \ No newline at end of file diff --git a/src/demo_gen/attributes.md b/src/demo_gen/attributes.md index c8beeba..dee6f32 100644 --- a/src/demo_gen/attributes.md +++ b/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) \ No newline at end of file +!["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). \ No newline at end of file diff --git a/src/demo_gen/custom_functions.md b/src/demo_gen/custom_functions.md new file mode 100644 index 0000000..c1d43ba --- /dev/null +++ b/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. \ No newline at end of file diff --git a/src/demo_gen/custom_renderer.md b/src/demo_gen/custom_renderer.md index f5e6a13..e8fcebb 100644 --- a/src/demo_gen/custom_renderer.md +++ b/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). \ No newline at end of file +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). \ No newline at end of file