Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix typos in websocket-extension.md #1437

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Fix typos in websocket-extension.md #1437

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f565269
fix a bazillion typos LOL
kenricashe Jun 15, 2024
db20d4b
Update recipes index and README
actions-user Jun 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/recipes/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -258,7 +258,7 @@ Lucee supports the following virtual file systems: ram, file, s3, http, https, z

## [WebSocket Extension](/docs/recipes/websocket-extension.md)

How to install, congigure and create WebSockets
How to install, configure and create WebSockets
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you don't have to change the readme, that is created by github action on commit


## [XML Fast And Easy, using SAX - Listener Functions](/docs/recipes/xml-fast-and-easy.md)

Expand Down
2 changes: 1 addition & 1 deletion docs/recipes/index.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -883,7 +883,7 @@
"file": "websocket-extension.md",
"title": "WebSocket Extension",
"path": "/docs/recipes/websocket-extension.md",
"hash": "1238504767ae21551d1f1e00870b271b",
"hash": "2b955c949e9e1febc10b6ef51ec8c5a0",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you don't have to change the index, that is created by github action on commit

"keywords": [
"Lucee",
"Extension"
Expand Down
59 changes: 31 additions & 28 deletions docs/recipes/websocket-extension.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"categories": [
"websocket"
],
"description": "How to install, congigure and create WebSockets",
"description": "How to install, configure and create WebSockets",
"keywords": [
"Lucee",
"Extension"
Expand All @@ -22,15 +22,15 @@ WebSocket Listeners are created with a CFML Component - one per channel.

There are multiple ways to install the docker extension.

### Lucee Administor
### Lucee Administrator

The Extension can be installed via Lucee Administor
The extension can be installed via Lucee Administrator:

![Lucee Admin: Extensions - Application](https://raw.githubusercontent.com/lucee/lucee-docs/master/docs/_images/extension/websocket/lucee-admin-extension.png)

### Manuell Installation
### Manual Installation

Download the LEX file from [https://download.lucee.org/](https://download.lucee.org/) and save to `/lucee/lucee-server/deploy/` (takes up to a minute for Lucee to pick up and install)
Download the LEX file from [https://download.lucee.org/](https://download.lucee.org/) and save to `/lucee/lucee-server/deploy/` (takes up to a minute for Lucee to pick up and install).

![Lucee Download LEX File](https://raw.githubusercontent.com/lucee/lucee-docs/master/docs/_images/extension/websocket/websocket-lex.png)

Expand All @@ -49,7 +49,7 @@ environment:
- LUCEE_EXTENSIONS=07082C66-510A-4F0B-B5E63814E2FDF7BE;version=1.0.0.4-BETA
```

Or simply define it in the .CFConfig.json file (Lucee 6 only)
Or simply define it in the .CFConfig.json file (Lucee 6 only):
```json
{
"extensions": [
Expand All @@ -61,13 +61,13 @@ Or simply define it in the .CFConfig.json file (Lucee 6 only)
]
}
```
See [this](https://github.com/lucee/lucee-docs/tree/master/examples/docker/with-extension) example for more details about setting up Extension in .CFConfig.json.
See [this](https://github.com/lucee/lucee-docs/tree/master/examples/docker/with-extension) example for more details about setting up extension in .CFConfig.json.

## Configuration

By default, Lucee Server will look in `{lucee-config}/websockets/` for WebSocket Components.

Lucee Server will create a config file if one does not exists at `{lucee-config}websocket.json` with the following defaults
Lucee Server will create a config file if one does not exist at `{lucee-config}websocket.json` with the following defaults:

*{lucee-config}: /lucee/lucee-server/context*

Expand All @@ -79,7 +79,7 @@ Lucee Server will create a config file if one does not exists at `{lucee-config}
}
```

The WebSocket Extension comes with a helper function `websocketInfo()` that well show the current configurations settings. More on other details later ...
The WebSocket extension comes with a helper function `websocketInfo()` that will show the current configurations settings. More on other details later ...

![websocketInfo()](https://raw.githubusercontent.com/lucee/lucee-docs/master/docs/_images/extension/websocket/websocketInfo.png)
<em>TODO: update with new version</em>
Expand All @@ -106,9 +106,9 @@ component hint="used to test websocket client" {
}
```

### Javascript Client
### JavaScript Client

Given that the Component was saved as `{lucee-config}/websockets/test.cfc`, here is native Javascript to open and use a connection to your Lucee WebSocket:
Given that the Component was saved as `{lucee-config}/websockets/test.cfc`, here is native JavaScript to open and use a connection to your Lucee WebSocket:

```javascript
socket = new WebSocket("ws://127.0.0.1:80/ws/test");
Expand All @@ -130,10 +130,11 @@ socket.send("Hello, Lucee Extension!");
socketclose();
```

### Broadcast Message to all Clients
A broadcast is a message send to all connected clients
### Broadcast Message to All Clients

To be able to do this, we need to know who is connected. The first time a connection is made, `onFirstOpen(wsclients)` is fired. `wsclients` is a Java class with the following methods
A broadcast is a message sent to all connected clients.

To be able to do this, we need to know who is connected. The first time a connection is made, `onFirstOpen(wsclients)` is fired. `wsclients` is a Java class with the following methods:

```java
size():number // the number of clients connected
Expand All @@ -142,24 +143,25 @@ getClients():Client[] // return array of all clients currently connecte
close():void // closes all clients
```

SO we can save that for furture use
So we can save that for future use:

```lucee
public static function onFirstOpen(wsclients) {
static.wsclients = arguments.wsclients;
}
```

For example
For example:

```lucee
function onOpen(wsclient) {
static.wsclients.broadcast("There are now ##static.wsclients.size()## connections");
}
```

### Send Message to one Client
### Send Message to One Client

When a connection is instantiated, `onOpen(wsclient)` is fired. `wsclient` is a Java class with the following methods
When a connection is instantiated, `onOpen(wsclient)` is fired. `wsclient` is a Java class with the following methods:

```java
client.broadcast(message):void // send message to all connected clients
Expand All @@ -177,15 +179,15 @@ function onOpen(wsclient) {
}
```

You can also send a message from `onOpen()` by returning a string
You can also send a message from `onOpen()` by returning a string:

```lucee
function onOpen(wsclient) {
return "Welcome to the test websocket channel";
}
```

You can add your own function to the WebSocket Componet
You can add your own function to the WebSocket component:

```lucee
public void function sendMessage(
Expand All @@ -200,15 +202,16 @@ function onOpen(wsclient) {
```

## Using Lucee WebSocket to PUSH data to Client
With webSocets being a bidirectional communication channel, your Lucee Server no longer limited to responding to a *request*, it can now *push* data to the client.

This means the user no longer has to refresh a page to see if data is updated, or have a Javascript looping function that is continuosly calling a ReST API to get lasted data.
With WebSockets being a bidirectional communication channel, your Lucee Server is no longer limited to responding to a *request*, it can now *push* data to the client.

This means the user no longer has to refresh a page to see if data is updated, or have a JavaScript looping function that is continuously calling a REST API to get latest data.

When your application has data ready for the user, have the WebSocket push the data to the cient!
When your application has data ready for the user, have the WebSocket push the data to the client!

### Make use of Static Function

Add a thread to start a background process, and have it continuously looping for as long as there are clients connected
Add a thread to start a background process, and have it continuously looping for as long as there are clients connected:

```lucee
public static function onFirstOpen(wsclients) {
Expand All @@ -223,13 +226,13 @@ public static function onFirstOpen(wsclients) {
}
```

Function `getDataFromSomewhere()` is respoible for obtaining the data that needs to be sent to the client. RedisQueue is an example of where data can be stored. Your Lucee application can Push data to a Redis Queue, and `getDataFromSomewhere()` can Pop one record at a time.
Function `getDataFromSomewhere()` is responsible for obtaining the data that needs to be sent to the client. RedisQueue is an example of where data can be stored. Your Lucee application can Push data to a Redis Queue, and `getDataFromSomewhere()` can Pop one record at a time.

### Using websocketInfo() to Send Message to Client

`websocketInfo()` also has an array of instances - one for each client call to a WebSocket Component. So looping through the array, gives you access to the Component, and then you can call any of it'sfunction
`websocketInfo()` also has an array of instances, one for each client call to a WebSocket Component. So, looping through the array gives you access to the component, and then you can call any of its functions.

For Example ( *excuding role management functions* )
For example (*excluding role management functions*):

```lucee
component hint="Test WebSocket" {
Expand Down Expand Up @@ -265,6 +268,6 @@ for ( var wsI in wsInstances) {
}
}
```
[Task Event Gateway](event-gateways-overview.md) is a good candidate for this script
[Task Event Gateway](event-gateways-overview.md) is a good candidate for this script.

*TODO: link to recipe page*
Loading