Crafter.CppDOM/README.md

# About

Crafter.CppDOM is a C++ library that exposes the browser DOM api's to C++ WebAssembly.

# HtmlElement vs HtmlElementView

The library provides two main classes for working with HTML elements:

## 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

## 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

# How to use
Please view the examples folder, this is a snippit from the HelloElement example:

```cpp
import Crafter.CppDOM;
using namespace Crafter::CppDOM;

int main(){
    HtmlElementView body("body");
    body.SetInnerHTML("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
create a ``project.json`` in an empty folder, open it in your preferred text editor.
Create a basic project file, that describes your web project.
```JSON
{
    "name": "main",
    "configurations": [
        {
            "name": "executable",
            "implementations": ["main"],
            "target": "wasm32-wasi",
            "debug" : true,
            "dependencies": [
                {
                    "path":"https://forgejo.catcrafts.net/Catcrafts/Crafter.CppDOM.git",
                    "configuration":"lib-debug"
                }
            ],
        }
    ]
}
```

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, 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.