Catcrafts/Crafter.CppDOM
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

REAMDE change

Browse source
This commit is contained in:
Jorijn van der Graaf 2025-11-15 15:29:09 +01:00
commit 623ebb1b11
1 changed files with 13 additions and 120 deletions
Download patch file Download diff file Expand all files Collapse all files

133
README.md
View file

@ -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.
This sample can also be viewed in the [HelloElement example](https://forgejo.catcrafts.net/Catcrafts/Crafter.CppDOM/src/branch/master/examples/HelloElement)