diff --git a/README.md b/README.md index 18318fb..d3ab0d6 100644 --- a/README.md +++ b/README.md @@ -2,42 +2,30 @@ Crafter.CppDOM is a C++ library that exposes the browser DOM api's to C++ WebAssembly. -# HtmlElement vs HtmlElementView +# HtmlElementPtr, HtmlElementView, HtmlElement -The library provides two main classes for working with HTML elements: +The library provides three main classes for working with HTML elements, all representing a diffrent ownership model: + +## HtmlElementPtr +`HtmlElementView` is the base class that provides read and write access to HTML element properties and methods, but does **not** own **anything**. Its the same as a C++ * and will not peform any cleanups. ## HtmlElementView -`HtmlElementView` is a base class that provides read and write access to HTML element properties and methods, but does **not** own the underlying DOM element. It's designed to be used when you want to interact with existing elements in the DOM without managing their lifecycle. - -Key characteristics: -- Provides access to element properties and methods like `SetInnerHTML`, `SetStyle`, `AddClass`, etc. -- Supports event handling through various `Add*Listener` methods -- Does not delete the underlying DOM element when destroyed -- Used when you're working with elements that already exist in the DOM +`HtmlElementView` is a derived class from `HtmlElementPtr` that adds ownership over the event handlers. Upon destructing it will unregister the eventhandlers. ## HtmlElement -`HtmlElement` is a derived class from `HtmlElementView` that adds ownership semantics. It creates a new DOM element when instantiated and properly manages its lifecycle. - -Key characteristics: -- Inherits all functionality from `HtmlElementView` -- Creates and owns a new DOM element when constructed -- Automatically deletes the DOM element when the `HtmlElement` object is destroyed -- Used when you want to create new elements programmatically +`HtmlElement` is a derived class from `HtmlElementView` that adds ownership over the element istelf. Upon destructing it will unregister the eventhandlers and destroy the element in the DOM. # How to use -Please view the examples folder, this is a snippit from the HelloElement example: +Extensive examples can be found in the examples folder, but this is the simplest example: ```cpp import Crafter.CppDOM; -using namespace Crafter::CppDOM; +using namespace Crafter; int main(){ - HtmlElementView body("body"); - body.SetInnerHTML("Hello World!"); + HtmlElementPtr body("body", "Hello World!"); } ``` -You can also view the wiki for more detailed information. - It is highly recommended to use this with [Crafter.Build](https://forgejo.catcrafts.net/Catcrafts/Crafter.Build), but it is not strictly required if the same way of injecting the env is followed. The following instructions will be for Crafter.Build. ## Quickstart @@ -51,11 +39,10 @@ Create a basic project file, that describes your web project. "name": "executable", "implementations": ["main"], "target": "wasm32-wasi", - "debug" : true, "dependencies": [ { "path":"https://forgejo.catcrafts.net/Catcrafts/Crafter.CppDOM.git", - "configuration":"lib-debug" + "configuration":"lib" } ], } @@ -63,102 +50,8 @@ Create a basic project file, that describes your web project. } ``` -Save and close the file, create a ``main.cpp`` -```cpp -import Crafter.CppDOM; -using namespace Crafter::CppDOM; - -int main(){ - HtmlElementView body("body"); - body.SetInnerHTML("Hello World!"); -} -``` +Save and close the file, create a ``main.cpp`` and copy the C++ code we wrote above into it. Save and close, then run ``crafter-build build executable && caddy file-server --listen :8080 --root bin/executable``. if you have caddy installed, if not use your favorite static file server instead. Now you can open the browser at ``http://localhost:8080`` and ``Hello World!`` will appear in the browser. -This sample can also be viewed in the [HelloElement example](https://forgejo.catcrafts.net/Catcrafts/Crafter.CppDOM/src/branch/master/examples) - -# Fetch Functionality - -The library now includes support for making HTTP requests using the `fetch` function: - -```cpp -import Crafter.CppDOM; -using namespace Crafter::CppDOMBindings; - -int main(){ - // Make a POST request with body data - std::string result = Fetch("https://httpbin.org/post", "{\"test\": \"data\"}"); - - // Or make a request without body data - std::string result = Fetch("https://httpbin.org/get"); - - // Handle the response - if (!result.empty()) { - // Process the response - HtmlElementView body("body"); - body.SetInnerHTML("Response: " + result); - } -} -``` - -This feature allows you to make HTTP requests directly from C++ code running in WebAssembly, which can be useful for communicating with APIs or backend services. - -# Location Pathname Access - -The library now provides access to the current page's pathname through the `GetPathNameString()` function: - -```cpp -import Crafter.CppDOM; -using namespace Crafter::CppDOMBindings; - -int main(){ - // Get the current page's pathname - std::string path = GetPathNameString(); - - // Use the path - HtmlElementView body("body"); - body.SetInnerHTML("Current path: " + path); -} -``` - -# PopState Event Handling - -The library supports handling the `popstate` event for navigation history changes: - -```cpp -import Crafter.CppDOM; -using namespace Crafter::CppDOMBindings; - -int main(){ - // Add a listener for popstate events - auto popStateId = AddPopStateListener([]() { - // This will be called when the user navigates back/forward - std::string path = GetPathNameString(); - HtmlElementView body("body"); - body.SetInnerHTML("Navigated to: " + path); - }); - - // Later, remove the listener if needed - // RemovePopStateListener(popStateId); -} -``` - -# History PushState Functionality - -The library provides access to the `history.pushState` API for manipulating browser history: - -```cpp -import Crafter.CppDOM; -using namespace Crafter::CppDOMBindings; - -int main(){ - // Push a new state to the browser history - PushState("{\"page\": \"about\"}", "About Page", "/about"); - - // This will modify the browser URL without reloading the page - // and can be combined with popstate event handling -} -``` - -These features allow you to build single-page applications with proper URL handling and navigation state management. \ No newline at end of file +This sample can also be viewed in the [HelloElement example](https://forgejo.catcrafts.net/Catcrafts/Crafter.CppDOM/src/branch/master/examples/HelloElement) \ No newline at end of file