Skip to content

Commit fe87a17

Browse files
SerafimArtsSerafimArts
committed
Add API docs and reorganize config/events pages
1 parent 2c699cf commit fe87a17

22 files changed

Lines changed: 1878 additions & 1148 deletions

‎Writerside/boson.tree‎

Lines changed: 35 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -8,42 +8,50 @@
88
<toc-element topic="introduction.md"
99
toc-title="Introduction" />
1010
<toc-element topic="installation.md" />
11-
<toc-element toc-title="Development" />
12-
<toc-element toc-title="Debugging" />
13-
<toc-element toc-title="Roadmap" />
11+
<toc-element toc-title="Development"
12+
hidden="true" />
13+
<toc-element toc-title="Debugging"
14+
hidden="true" />
15+
<toc-element toc-title="Roadmap"
16+
hidden="true" />
1417
<toc-element topic="release-notes.md" />
1518
</toc-element>
1619
<toc-element toc-title="The Basics">
17-
<toc-element toc-title="Lifecycle" hidden="true" />
20+
<toc-element toc-title="Lifecycle"
21+
hidden="true" />
1822
<toc-element topic="configuration.md" />
19-
<toc-element topic="application.md" />
20-
<toc-element topic="window.md" />
23+
<toc-element topic="application.md">
24+
<toc-element topic="application-configuration.md"
25+
toc-title="Configuration" />
26+
<toc-element topic="application-events.md"
27+
toc-title="Events" />
28+
</toc-element>
29+
<toc-element topic="window.md">
30+
<toc-element topic="window-configuration.md"
31+
toc-title="Configuration" />
32+
<toc-element topic="window-events.md"
33+
toc-title="Events" />
34+
</toc-element>
2135
<toc-element topic="webview.md">
22-
<toc-element toc-title="Scripts API" />
23-
<toc-element toc-title="Functions API" />
24-
<toc-element toc-title="Requests API" />
36+
<toc-element topic="webview-configuration.md"
37+
toc-title="Configuration" />
38+
<toc-element topic="webview-events.md"
39+
toc-title="Events" />
40+
<toc-element topic="schemes-api.md" />
41+
<toc-element topic="scripts-api.md" />
42+
<toc-element topic="functions-api.md" />
43+
<toc-element topic="requests-api.md" />
2544
</toc-element>
2645
<toc-element topic="events.md" />
2746
</toc-element>
2847
<toc-element toc-title="Integrations">
29-
<toc-element toc-title="Symfony" />
30-
<toc-element toc-title="Laravel" />
31-
<toc-element toc-title="Slim" />
32-
<toc-element toc-title="Other PSR-7 frameworks" />
33-
</toc-element>
34-
<toc-element toc-title="Tutorial">
35-
<toc-element toc-title="Prerequisites" />
36-
<toc-element toc-title="Building" />
37-
<toc-element toc-title="Adding Features" />
38-
<toc-element toc-title="Compilation" />
39-
<toc-element toc-title="Publishing" />
40-
<toc-element toc-title="Updating" />
41-
</toc-element>
42-
<toc-element toc-title="Examples">
43-
<toc-element toc-title="Simple Application" />
44-
<toc-element toc-title="Dark Mode" />
45-
<toc-element toc-title="Custom Window" />
46-
<!-- TODO -->
48+
<toc-element topic="static-files.md" />
49+
<toc-element topic="symfony-adapter.md"
50+
toc-title="Symfony HTTP" />
51+
<toc-element topic="laravel-adapter.md"
52+
toc-title="Laravel HTTP" />
53+
<toc-element topic="psr7-adapter.md"
54+
toc-title="Other PSR-7 frameworks" />
4755
</toc-element>
4856
<toc-element topic="contribution.md" />
4957
<toc-element topic="license.md" />

‎Writerside/cfg/static/custom.css‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Writerside/labels.list‎

Lines changed: 47 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,59 @@
22
<!DOCTYPE labels SYSTEM "https://resources.jetbrains.com/writerside/1.0/labels-list.dtd">
33
<labels xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
44
xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/labels.xsd">
5-
<primary-label id="experimental" name="Experimental" short-name="Experimental" color="tangerine">
5+
<primary-label id="experimental" name="Experimental" short-name="Experimental" color="red">
66
This is a non-stable functionality which is highly likely
7-
to be changed or removed in the future.
7+
to be changed or removed in the future
88
</primary-label>
99

10-
<primary-label id="events" name="Context Events" short-name="E" color="tangerine">
11-
List of context events and intentions provided by the given context.
10+
<primary-label id="events" name="Events" short-name="E" color="tangerine">
11+
List of context events and intentions provided by the given context
1212
</primary-label>
1313

14-
<secondary-label id="wip" name="WIP" color="red">Work in progress</secondary-label>
15-
<secondary-label id="beta" name="β" color="tangerine">Beta</secondary-label>
14+
<primary-label id="configuration" name="Configuration" short-name="C" color="strawberry">
15+
List of configuration rules applied before the application is launched
16+
</primary-label>
1617

18+
<!-- event types -->
1719
<secondary-label id="event" name="Event" color="tangerine">Event Feature</secondary-label>
1820
<secondary-label id="intention" name="Intention" color="purple">Intention Feature</secondary-label>
21+
22+
<!-- config definition -->
23+
<secondary-label id="config-only" name="Config" color="red">
24+
The value is set only in the settings and CANNOT be changed in runtime
25+
</secondary-label>
26+
<secondary-label id="config-and-runtime" name="Config + Runtime" color="blue">
27+
The value may set in the settings, but CAN be changed at runtime
28+
</secondary-label>
29+
30+
<!-- property definition -->
31+
<secondary-label id="write-only" name="Write Only" color="strawberry">
32+
The property is write-only
33+
</secondary-label>
34+
<secondary-label id="read-only" name="Read Only" color="strawberry">
35+
The property is read-only
36+
</secondary-label>
37+
38+
<!-- limitations -->
39+
<secondary-label id="linux-limitations" name="⚠ Linux/GTK4" color="red">
40+
Contain list of Linux/GTK4 platform limitations
41+
</secondary-label>
42+
<secondary-label id="windows-limitations" name="⚠ Windows/WebView2" color="red">
43+
Contain list of Windows/WebView2 platform limitations
44+
</secondary-label>
45+
<secondary-label id="macos-limitations" name="⚠ MacOS/WebKit" color="red">
46+
Contain list of MacOS/WebKit platform limitation
47+
</secondary-label>
48+
<secondary-label id="security-limitations" name="⚠ Security Required" color="red">
49+
A Secure Context is required to use this functionality
50+
</secondary-label>
51+
52+
<!-- other -->
53+
<secondary-label id="insecure" name="⚠ Insecure" color="red">
54+
Using this functionality imposes list of restrictions
55+
on the available Client API
56+
</secondary-label>
57+
<secondary-label id="blocking" name="⚠ Blocking" color="red">
58+
Blocks the PHP execution flow until the task is completed
59+
</secondary-label>
1960
</labels>

‎Writerside/topics/application.md‎

Lines changed: 40 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,19 @@
22

33
<show-structure for="chapter" depth="2"/>
44

5-
The `Application` is the central component of the Boson and is responsible for
6-
managing the application lifecycle. It provides a single entry point for
7-
creating and managing web applications using WebView.
5+
The `Boson\Application` is the central
6+
component of the Boson and is responsible for managing the application
7+
lifecycle. It provides a single entry point for creating and managing web
8+
applications using WebView.
89

910
The application is responsible for:
1011

11-
- Lifecycle management (
12-
<a href="application.md#creating-an-application">startup</a>,
13-
<a href="application.md#stop-application">shutdown</a>)
14-
- <a href="window.md">Window</a> creation and management
15-
- <a href="webview.md">WebView</a> integration for web content display
16-
- <a href="application.md#application-events">Application</a>, webview and window event handling
12+
- Lifecycle management ([startup](application.md#creating),
13+
[shutdown](application.md#stopping), etc).
14+
- [Window](window.md) creation and management.
15+
- [WebView](webview.md) integration for web content display.
16+
- [Application](application-events.md), [WebView](webview-events.md) and
17+
[Window](webview-events.md) event handling.
1718

1819
...and more
1920

@@ -23,53 +24,53 @@ two "layers":
2324
- Facades over methods and properties of descendants for quick access to the
2425
main internal components of the core.
2526

27+
## Creating
2628

27-
## Creating an Application
29+
To create an application, simply create a new `Boson\Application` object.
30+
This will be sufficient for the vast majority of cases.
2831

29-
To create an application, simply create a new <code>Boson\Application</code>
30-
object. This will be sufficient for the vast majority of cases.
31-
32-
<code-block lang="PHP">
32+
```php
3333
$app = new Boson\Application();
34-
</code-block>
34+
```
3535

3636
The application constructor also contains several optional arguments that you
3737
can pass explicitly if you wish.
3838

39-
The first optional argument is responsible for the <code>Boson\ApplicationCreateInfo</code>
39+
The first optional argument is responsible for the `Boson\ApplicationCreateInfo`
4040
application settings and allows you to fine-tune the application's operation.
4141

4242
<tip>
4343
More details about the application configuration are written on the
44-
<a href="configuration.md#application">corresponding documentation pages</a>.
44+
<a href="application-configuration.md">corresponding documentation pages</a>.
4545
</tip>
4646

47-
<code-block lang="PHP">
47+
```php
4848
$config = new Boson\ApplicationCreateInfo(
4949
// application configuration options
5050
);
5151

5252
$app = new Boson\Application(info: $config);
53-
</code-block>
53+
```
5454

5555
The remaining optional parameters are responsible for passing external
5656
dependencies.
5757

5858
For example, the second argument takes an optional reference to an external
59-
<code>Psr\EventDispatcher\EventDispatcherInterface</code> event dispatcher
59+
`Psr\EventDispatcher\EventDispatcherInterface` event dispatcher
6060
to which all events within the application can be delegated.
6161

62-
<code-block lang="PHP">
62+
```php
6363
$dispatcher = new Any\Vendor\PsrEventDispatcher();
6464

6565
$app = new Boson\Application(dispatcher: $dispatcher);
66-
</code-block>
66+
```
6767

6868
After creating the application, you will have access to the API to work with
6969
it, and after the necessary actions, the application will automatically start,
70-
<a href="configuration.md#autorun">unless otherwise specified</a>.
70+
<a href="application-configuration.md#autorun">unless otherwise specified</a>.
7171

72-
## Launching an Application
72+
## Launching
73+
<secondary-label ref="blocking"/>
7374

7475
The application can be started manually using the <code>run()</code> method.
7576

@@ -95,7 +96,7 @@ echo 'Application WAS stopped'; // The code will be executed ONLY
9596
</warning>
9697

9798

98-
## Stop Application
99+
## Stopping
99100

100101
The application can be stopped at any time using the `quit()` method:
101102

@@ -109,11 +110,9 @@ event subscription
109110
<code-block lang="PHP">
110111
$app = new Boson\Application();
111112

112-
$app->events->addEventListener(SomeEvent::class,
113-
function() use ($app): void {
114-
$app->quit();
115-
}
116-
);
113+
$app->on(function (SomeEvent $e) use ($app): void {
114+
$app->quit();
115+
});
117116

118117
$app->run();
119118
</code-block>
@@ -134,17 +133,22 @@ if ($app->isRunning === false) {
134133
</code-block>
135134

136135

137-
## Application Identifier
136+
## Identifier
137+
<secondary-label ref="read-only"/>
138138

139-
The <code>Boson\ApplicationId</code> is a unique identifier for each application
139+
The `Boson\ApplicationId` is a unique identifier for each application
140140
instance. The identifier is needed to compare different applications
141141
for their equivalence.
142142

143-
<warning>
144-
The <code>ApplicationId</code> property is read-only and cannot be changed.
145-
</warning>
143+
To get application identifier use the `Application::$id` property.
144+
145+
```php
146+
$app = new Boson\Application();
146147

147-
The <code>ApplicationId</code> identifier is a value object and contains methods
148+
echo 'ID: ' . $app->id;
149+
```
150+
151+
An identifier is a value object and contains methods
148152
for comparison and conversion to scalars.
149153

150154
<code-block lang="PHP">
@@ -153,83 +157,3 @@ if ($app1->id->equals($app2->id)) {
153157
}
154158
</code-block>
155159

156-
157-
## Application Events
158-
<primary-label ref="events"/>
159-
160-
The application will automatically emit the following events (and intentions)
161-
during its lifecycle.
162-
163-
To subscribe to events, you can use direct access to the
164-
<a href="events.md#event-listener">event listener</a>, using
165-
`Application::$events` property.
166-
167-
```php
168-
$app->events->addEventListener(Event::class, function(Event $e) {
169-
var_dump($e);
170-
});
171-
```
172-
173-
The application instance also supports a more convenient and simple way of
174-
registering events using the `on()` method.
175-
176-
```php
177-
$app->on(function(Event $event): void {
178-
var_dump($event);
179-
});
180-
```
181-
182-
<note>
183-
More information about events can be found in the <a href="events.md">events
184-
documentation</a>.
185-
</note>
186-
187-
188-
189-
### Starting Intention
190-
<secondary-label ref="intention"/>
191-
192-
An `Boson\Event\ApplicationStarting` intention to start the application.
193-
194-
```php
195-
class ApplicationStarting<Application>
196-
```
197-
198-
<tip>
199-
If it is cancelled, the application will not be launched.
200-
</tip>
201-
202-
### Started Event
203-
<secondary-label ref="event"/>
204-
205-
An `Boson\Event\ApplicationStarted` event fired after the application has been
206-
launched and the `Boson\Event\ApplicationStarting` intention has not been
207-
cancelled.
208-
209-
```php
210-
class ApplicationStarted<Application>
211-
```
212-
213-
### Stopping Intention
214-
<secondary-label ref="intention"/>
215-
216-
An `Boson\Event\ApplicationStopping` intention to stop the application.
217-
218-
```php
219-
class ApplicationStopping<Application>
220-
```
221-
222-
<tip>
223-
If it is cancelled, the application will not be stopped.
224-
</tip>
225-
226-
### Stopped Event
227-
<secondary-label ref="event"/>
228-
229-
An `Boson\Event\ApplicationStopped` event fired after the application has been
230-
stopped and the `Boson\Event\ApplicationStopping` intention has not been
231-
cancelled.
232-
233-
```php
234-
class ApplicationStopped<Application>
235-
```

0 commit comments

Comments
 (0)