Skip to content

Commit

Permalink
Added docs about auto unregister rpc.
Browse files Browse the repository at this point in the history
  • Loading branch information
@5cript
5cript committed Sep 20, 2023
1 parent f4c14a1 commit 0e28fa8
Show file tree
Hide file tree
Showing 4 changed files with 192 additions and 186 deletions.
214 changes: 107 additions & 107 deletions docs/bundling/general.md
View file
Original file line number Diff line number Diff line change
@@ -1,107 +1,107 @@
# Bundling in Nui

Nui uses [parcel](https://parceljs.org/) under the hood to bundle everything together.
The regular cases try to inline everything and place them in a single index.html, sometimes this approach is not
possible or desireable.

## Status Quo in the Template

The template provides the followin index.html file.
In this index.html file, sources and styles are inlined by parcel by
using the import statements instead of adding every file by using script tags.

```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Nui</title>

<!-- highlight-start -->
<!-- You have to import like this to achieve inlining of the style -->
<style>
@import "./styles/main.css";
</style>
<!-- highlight-end -->

<!-- highlight-start -->
<!-- You have to import like this to achieve inlining of the script -->
<script type="module" defer>
import "./source/index.js";
import "../bin/index.js";
</script>
<!-- highlight-end -->
</head>
<body>
</body>
```

This will produce as single index.html located at `*/build/module-TARGETNAME/bin/index.html`
which is then automtically accessible from the backend source by including it:

```cpp
// highlight-start
// This file is generated by nui.
#include <index.hpp>
// highlight-end

int main() {
using namespace Nui;

Window window{"Window Title", true /* may open debug window */};

// highlight-start
// index function to be used here:
window.setHtml(index());
// highlight-end
}
```

## Inline

### Image assets
Images can be inlined in the CSS using:
```css
.foo {
background: url(data-url:./background.png);
}
```

### Typescript/Javascript Code
Just import regularly from your source files:
```javascript
import _ from "lodash";
```
Or from index.html:
```html
<script type="module" defer>
import "./source/bla.js";
</script>
```

## External
Sometimes you dont want to bundle because resources would become to big for a big bundled index blob.

### Images
Currently 2 different ways of file mappings enabled via `Window::setVirtualHostNameToFolderMapping` are needed.
setVirtualHostNameToFolderMapping maps a host name under the assets:// scheme (https: on windows) to a folder.
This may change in the future, when schema mappings are implemented for windows, unifying to the linux way of
referencing files:
```css
.remove-button-win{
background-image: url("https://assets/red_cross.svg");
}
.remove-button-nix {
background-image: url("assets://assets/red_cross.svg");
}
```

### Typescript/Javascript Code
Import using the url prefix to avoid inlining:
```javascript
import EditorWorker from 'url:monaco-editor/esm/vs/editor/editor.worker.js';
```
TODO: get more into detail.


# Bundling in Nui

Nui uses [parcel](https://parceljs.org/) under the hood to bundle everything together.
The regular cases try to inline everything and place them in a single index.html, sometimes this approach is not
possible or desireable.

## Status Quo in the Template

The template provides the followin index.html file.
In this index.html file, sources and styles are inlined by parcel by
using the import statements instead of adding every file by using script tags.

```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Nui</title>

<!-- highlight-start -->
<!-- You have to import like this to achieve inlining of the style -->
<style>
@import "./styles/main.css";
</style>
<!-- highlight-end -->

<!-- highlight-start -->
<!-- You have to import like this to achieve inlining of the script -->
<script type="module" defer>
import "./source/index.js";
import "../bin/index.js";
</script>
<!-- highlight-end -->
</head>
<body>
</body>
```

This will produce as single index.html located at `*/build/module-TARGETNAME/bin/index.html`
which is then automtically accessible from the backend source by including it:

```cpp
// highlight-start
// This file is generated by nui.
#include <index.hpp>
// highlight-end

int main() {
using namespace Nui;

Window window{"Window Title", true /* may open debug window */};

// highlight-start
// index function to be used here:
window.setHtml(index());
// highlight-end
}
```

## Inline

### Image assets
Images can be inlined in the CSS using:
```css
.foo {
background: url(data-url:./background.png);
}
```

### Typescript/Javascript Code
Just import regularly from your source files:
```javascript
import _ from "lodash";
```
Or from index.html:
```html
<script type="module" defer>
import "./source/bla.js";
</script>
```

## External
Sometimes you dont want to bundle because resources would become to big for a big bundled index blob.

### Images
Currently 2 different ways of file mappings enabled via `Window::setVirtualHostNameToFolderMapping` are needed.
setVirtualHostNameToFolderMapping maps a host name under the assets:// scheme (https: on windows) to a folder.
This may change in the future, when schema mappings are implemented for windows, unifying to the linux way of
referencing files:
```css
.remove-button-win{
background-image: url("https://assets/red_cross.svg");
}
.remove-button-nix {
background-image: url("assets://assets/red_cross.svg");
}
```

### Typescript/Javascript Code
Import using the url prefix to avoid inlining:
```javascript
import EditorWorker from 'url:monaco-editor/esm/vs/editor/editor.worker.js';
```
TODO: get more into detail.


46 changes: 23 additions & 23 deletions docs/reference/text.md
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,24 @@
# Text Nodes
Sometimes it is necessary to have text nodes alongised regular html element children.
One of these examples is implicit label association:

```html
<label><input type=checkbox>Check This Out!</label>
```

In Nui this can look like this:
```cpp
using Nui::Elements::label;

label{}(
input{
type = "checkbox"
},
// highlight-start
// Do not forget the () at the end. Even though text nodes cannot have children,
// the parantheses are not optional for technical reasons.
text{"Check This Out!"}()
// highlight-end
)
```
# Text Nodes
Sometimes it is necessary to have text nodes alongised regular html element children.
One of these examples is implicit label association:

```html
<label><input type=checkbox>Check This Out!</label>
```

In Nui this can look like this:
```cpp
using Nui::Elements::label;

label{}(
input{
type = "checkbox"
},
// highlight-start
// Do not forget the () at the end. Even though text nodes cannot have children,
// the parantheses are not optional for technical reasons.
text{"Check This Out!"}()
// highlight-end
)
```
Text content can also be dynamic using Nui::Observed<std::string>.
112 changes: 56 additions & 56 deletions docs/third_party/bootstrap.md
View file
Original file line number Diff line number Diff line change
@@ -1,57 +1,57 @@
# Integrating Bootstrap

## Install and Import Bootstrap

The following assumes the nui-template structure.

1. Install bootstrap

`npm i --save bootstrap @popperjs/core`

2. Import Bootstrap:

static/index.html:
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Nui</title>

<!-- Import like this to achieve inlining -->
<style>
@import "./styles/main.scss";
</style>

<!-- Import like this to achieve inlining -->
<script type="module" defer>
// HERE
import * as bootstrap from "../node_modules/bootstrap/dist/js/bootstrap.bundle.min.js";
import "../bin/index.js";
</script>
</head>
<body>
</body>
```

static/styles/main.scss:
```scss
/* variables here */

@import "../../node_modules/bootstrap/scss/bootstrap.scss";
```

## Defining Custom Attributes For Bootstrap

You can define non standard attributes like this:
```cpp
#include <nui/frontend/attributes/impl/attribute.hpp>

constexpr auto dataBsTarget = Nui::Attributes::AttributeFactory("data-bs-target");

// =>
div{
dataBsTarget = "#something"
}()
# Integrating Bootstrap

## Install and Import Bootstrap

The following assumes the nui-template structure.

1. Install bootstrap

`npm i --save bootstrap @popperjs/core`

2. Import Bootstrap:

static/index.html:
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Nui</title>

<!-- Import like this to achieve inlining -->
<style>
@import "./styles/main.scss";
</style>

<!-- Import like this to achieve inlining -->
<script type="module" defer>
// HERE
import * as bootstrap from "../node_modules/bootstrap/dist/js/bootstrap.bundle.min.js";
import "../bin/index.js";
</script>
</head>
<body>
</body>
```

static/styles/main.scss:
```scss
/* variables here */

@import "../../node_modules/bootstrap/scss/bootstrap.scss";
```

## Defining Custom Attributes For Bootstrap

You can define non standard attributes like this:
```cpp
#include <nui/frontend/attributes/impl/attribute.hpp>

constexpr auto dataBsTarget = Nui::Attributes::AttributeFactory("data-bs-target");

// =>
div{
dataBsTarget = "#something"
}()
```
6 changes: 6 additions & 0 deletions docs/tutorials/rpc.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,12 @@ void foo()
// ...
});

// Useful RAII unregister (also available in backend):
{
auto unregisterWhenThisFallsOutOfScope =
Nui::RpcClient::autoRegisterFunction("asdf", [](){});
} // asdf no longer exists here.

// Removing callable:
Nui::RpcClient::unregisterFunction("someCallable");
}
Expand Down

0 comments on commit 0e28fa8

Please sign in to comment.