diff --git a/docs/intro.md b/docs/intro.md deleted file mode 100644 index ff54ae88..00000000 --- a/docs/intro.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Examples / Guides - -## Creating a basic UI Library - -This guide will not show you how to create a window and handle it's events, it will only show you how to make a simple function that attaches a text to the webview. - ---- - -The WebView API provides us with a method that lets us run Javascript code, directly from Luau. -we will use that to create UI elements like this: - -```lua title="src/init.luau" -webview:evaluate_noresult([[ -let el = document.createElement("h1") -el.innerHTML = "Hello, Lune!" -document.body.appendChild(el) -]]) -``` - -This code is basically running a javascript code through the webview, which creates a "Hello, Lune!" header and attaches it to the UI. - ---- - -We should make our code a little more safe by waiting for an answer from the webview, like this: - -```lua title="src/init.luau" -type Status = { - success: boolean, -} - -local status: Status = webview:evaluate([[ -let response = ( - () => { - try { - let el = document.createElement("h1") - el.innerHTML = "Hello, Lune!" - document.body.appendChild(el) - return { success: true } - } catch { - return { success: false } - } - } -)() - -response -]]) - -if status.success == false then - print("Failed to create web element") -end -``` - -webview:evaluate(...) returns the last statement in the provided javascript code as a Luau value, so in our javascript code we can return a table that tells us if the element has been created or not. - -This javascript code might look a _bit_ confusing, it basically creates a function and calls it directly -The function runs a try catch block trying to create an element, if it succeeds it returns { success: true }, otherwise { success: false } - ---- - -Debugging a string is the worst thing that can happen to a developer, so let's put our javascript code in it's own file - -```js title="src/javascript/hello.js" -let response = (() => { - try { - let el = document.createElement("h1"); - el.innerHTML = "Hello, Lune!"; - document.body.appendChild(el); - return { success: true }; - } catch { - return { success: false }; - } -})(); - -response; -``` - -```lua title="src/init.luau" -local fs = require("@luneweb/fs") -local code = fs.readFile("src/javascript/hello.js") - -type Status = { - success: boolean, -} - -local status: Status = webview:evaluate(code) - -if status.success == false then - print("Failed to create web element") -end -``` - ---- - -Ok, now let's make it a bit more customizable! - -```lua title="src/init.luau" -local regex = require("@luneweb/regex") -local code = fs.readFile("src/javascript/hello.js") -code = regex.new("Hello, Lune!"):replaceAll(code, "Hello, World!") -``` - -Here we used the regex library to replace "Hello, Lune!" with "Hello, World!" - ---- - -We can now wrap this all up into a function - -```lua title="lib/init.luau" -type Status = { - success: boolean, -} - -local function label(text: string): Status - local fs = require("@luneweb/fs") - local regex = require("@luneweb/regex") - local code = fs.readFile("src/javascript/hello.js") - code = regex.new("Hello, Lune!"):replaceAll(code, text) - - webview:evaluate(code) -end - -local status = label("Hello, World!") - -if status.success == false then - print("Failed to create web element") -end -``` diff --git a/moonwave.toml b/moonwave.toml new file mode 100644 index 00000000..8122b9d4 --- /dev/null +++ b/moonwave.toml @@ -0,0 +1,3 @@ +[[navbar.items]] +label = "Examples" +to = "examples" \ No newline at end of file diff --git a/pages/examples.md b/pages/examples.md new file mode 100644 index 00000000..374020c7 --- /dev/null +++ b/pages/examples.md @@ -0,0 +1,81 @@ + + +# Examples + +## Creating a basic UI component + +```js title="src/javascript/hello.js" +/* + we'll try to not create any variables in the main scope + because when wry evaluates a javascript code into the webview + it keeps the variables for the whole session + + for example, if we do `let a = 100` twice + the second one will fail because `a` is already declared. +*/ + +(() => { + /* + the reason for creating a function here is because we want + the try and catch block to return either { success: true } or { success: false } for us + so in luau code we know if creating the element was successful or not + */ + try { + let el = document.createElement("h1"); + el.innerHTML = "Hello, Lune!"; + document.body.appendChild(el); + return { success: true }; + } catch { + return { success: false }; + } + + /* + if we want luau to get { success: boolean } + we'll need the returned value to be the last statement in the code + so we call the function directly at the last part of the code + */ +})(); +``` + +```lua title="lib/init.luau" +--[[ + we'll be using the fs library to read the javascript code + and use the regex library to replace "Hello, Lune!" with whatever string we want +]] +local fs = require("@luneweb/fs") +local regex = require("@luneweb/regex") + +--[[ + since our javascript code returns { success: boolean } + and the webview library turns javascript values into luau values automatically + we can create a type for it so we can get typechecking in our code +]] +type Status = { + success: boolean, +} + +local function label(text: string): Status + --[[ + we'll use fs.readFile to get the javascript as a luau string + and then we'll use regex to replace "Hello, Lune!" + with the provided string in the function paramters + ]] + local code = fs.readFile("src/javascript/hello.js") + code = regex.new("Hello, Lune!"):replaceAll(code, text) + + --[[ + we'll evaluate the javascript code and return it's result + ]] + return webview:evaluate(code) +end + +local status = label("Hello, World!") + +--[[ + since our javascript code returns { success: boolean } + we can check the result and print out a warning if .success was false +]] +if status.success == false then + warn("Failed to create label") +end +``` diff --git a/pages/index.md b/pages/index.md index 431ac848..0ce8718b 100644 --- a/pages/index.md +++ b/pages/index.md @@ -17,7 +17,7 @@ ## Caution -None of the examples in this documentation are tested, if a method/function or property in a example doesn't exist, you can take advantage of autocomplete or the API documentation to look for the right one. +None of the examples in the API section are tested, if a method/function or property in a example doesn't exist, you can take advantage of autocomplete or the API documentation to look for the right one. ---