npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@item-enonic-types/lib-turbo-streams

v1.1.2

Published

Type definitions for lib-xp-turbo

Downloads

112

Readme

Enonic XP Turbo Library

Enonic XP Library for integrating with Turbo Streams.

Gradle

To install this library you may need to add some new dependencies to your app's build.gradle file.

repositories {
  maven { url 'https://jitpack.io' }
}

dependencies {
  include "com.enonic.xp:lib-portal:${xpVersion}"
  include "com.enonic.xp:lib-websocket:${xpVersion}"
  include 'no.item:lib-xp-turbo:1.1.0'
  webjar "org.webjars.npm:hotwired__turbo:8.0.5"
}

TypeScript

You can add the following changes to your tsconfig.json to get TypeScript-support.

{
  "compilerOptions": {
+   "baseUrl": "./",
+   "paths": {
+     "/lib/xp/*": ["./node_modules/@enonic-types/lib-*"],
+     "/lib/*": [ "./node_modules/@item-enonic-types/lib-*" ,"./src/main/resources/lib/*"],
+   }
  }
}

Setup

Page template

[!CAUTION] Including the turbo.es2017-esm.js file will affect the basic functionality of your page (like navigation). Read the Turbo documentation to make sure that this is something you want to do.

  1. Import the turbo script in your page html (has to be in <head>).
  2. Set the "turbo-streams" service to be the <turbo-stream-source> of the page. (Has to be in <body>).
<head>
  <!-- 1. Imported as a webjar (see above) -->
  <script type="module" src="[@assetUrl path='hotwired__turbo/8.0.5/dist/turbo.es2017-esm.js'/]"></script>
</head>
<body>
  <!-- 2. -->
  <turbo-stream-source src="[@serviceUrl service='turbo-streams' type='websocket'/]"></turbo-stream-source>
</body>

Usage

You can now directly manipulate the dom from serverside JavaScript over websocket, using following functions:

  • append({ target, content });
  • prepend({ target, content });
  • replace({ target, content });
  • update({ target, content });
  • remove({ target });
  • before({ target, content });
  • after({ target, content });
  • refresh({ requestId });

Example

var turboStreamsLib = require('/lib/turbo-streams');

// Append some markup to a target id in the dom
turboStreamsLib.append({
  target: 'my-alert-wrapper-id',
  content: '<div role="alert">Something went wrong</div>'
});

// Prepend some markup to a target id in the dom
turboStreamsLib.prepend({
  target: 'my-alert-wrapper-id',
  content: '<div role="alert">Something else went wrong</div>'
});

// Replace some markup at a target id in the dom
turboStreamsLib.replace({
  target: 'status-id',
  content: '<div id="status-id">Status has changed</div>'
});

// Update the contents inside at a target id in the dom
turboStreamsLib.update({
  target: 'status-id',
  content: 'Status has changed again!'
});

// Remove an element with a target id from the dom
turboStreamsLib.remove({
  target: 'status-id'
});

// Insert some markup before a target id in the dom
turboStreamsLib.before({
  target: 'my-alert-id',
  content: '<div role="alert">Something else went wrong</div>'
});

// Insert some markup after a target id in the dom
turboStreamsLib.after({
  target: 'my-alert-id',
  content: '<div role="alert">Something else went wrong</div>'
});

// Initiates a Page Refresh to render new content with morphing.
turboStreamsLib.after({
  requestId: 'my-refresh-id',
});

Selecting web sockets

Default setup

If you use the default setup – like specified above – you don't have to specify socketId or groupId at all.

If you used the page contribution from getTurboStreamPageContribution() a web socket connections was initialized against the "turbo-streams" service. The service registered the socket with a websocket group based on the users session id.

It is this group – based on the user's session id – that is the default receiver of messages from append, prepend, replace, update and remove.

Send to all users' browser at same time

If you want to send a message to every browser connected to the "turbo-streams" service. You can use the default group with the id specified in the constant DEFAULT_GROUP_ID:

turboStreamsLib.append({
  target: 'my-special-id',
  content: '<div role="alert">Hello</div>',
  groupId: turboStreamsLib.DEFAULT_GROUP_ID
});

Send to specific socket

If you know the socketId of a websocket (you get it from event.session.id in webSocketEvent()), you can use it as the channel for messages from this library.

turboStreamsLib.append({
  target: 'my-special-id',
  content: '<div role="alert">Hello</div>',
  socketId: mySocketId
});

Send to specific web socket group

If you want to send messages to a websocket group of your choice you can use groupId to specify it. To register new groups you need to create your own service that exposes your own socket, instead of using the built in service named "turbo-streams".

turboStreamsLib.append({
  target: 'my-special-id',
  content: '<div role="alert">Hello</div>',
  groupId: myGroupId
});

Turbo Streams over HTTP

It is also possible to return turbo streams over http with the Content-Type "text/vnd.turbo-stream.html; charset=utf-8".

This can for instance be returned by a form submission to perform multiple actions the web page's dom.

Use the acceptTurboStreams() to check if Turbo Streams is supported. Then use serialize() to transform an Array of { action, target, content } to a string with Turbo Stream actions.

var turboStreamsLib = require('/lib/turbo-streams');

exports.post = function(req) {
  // if "Accept" header includes mime type
  if (turboStreamsLib.acceptTurboStreams(req)) {
    return turboStreamsLib.createTurboStreamResponse([
      {
        action: 'append',
        target: 'my-alert-wrapper-id',
        content: '<div role="alert">Something went wrong</div>'
      },
      {
        action: 'replace',
        target: 'status-id',
        content: '<div>Status has changed</div>'
      }
    ]);
  } else {
    return {
      status: 200,
      body: "This page doesn't accept Turbo Streams"
    };
  }
}

Use the "turbo-streams" response processor – included in this library – to make the response body from a part become the whole payload returned to the browser.

You need to configure your site.xml with the following:

<?xml version="1.0" encoding="UTF-8"?>
<site>
+ <processors>
+   <response-processor name="turbo-streams" order="10" />
+ </processors>
</site>

[!NOTE] Behind the scenes, a header field "x-turbo" is used to pass the response body from the part to the response processor

Development

Changesets

Changesets is a tool that helps developers version the software, and create changelogs.

Please include Changesets in your PRs.

To install Changesets run the following command:

npm install -g @changesets/cli

Run the following command and you will be prompted to create a changelog message and tell it which level to bump the next version:

changeset

Building

To build he project run the following command:

./gradlew build

Deploy locally

Deploy locally for testing purposes:

./gradlew publishToMavenLocal

Deploy to Jitpack

Go to the Jitpack page for lib-xp-turbo to deploy from Github (after creating a new versioned release).