@sctlib/matrix-room-element v0.0.999

web components to list (and send) events in a matrix chat room (npm).

usage

<script type="module" src="https://cdn.jsdelivr.net/npm/@sctlib/matrix-room-element"></script>
<matrix-room-element profile-id="#sctlib-yoga-images:matrix.org">

By default, a "public matrix room", will only show the room's sate (title, alias, topic...).

If you want to show the events of the room, add the show-context="true" attribute, on the matrix-room-element.

examples

• see example in ./index.html
• see implementation on profile pages https://libli.org/#sctlib-yoga-images:matrix.org (view source code)

installation/import

The project is distributed within this git repository, and is also published as a NPM package (see .gitlab-ci.yml file).

from a CDN (that imports from NPM)

1. First import the script in javascript (module) file.

import('https://cdn.jsdelivr.net/npm/@sctlib/matrix-room-element)

or in an html file (don't forget type="module" on the script tag):

<script type="module">
	import mre from "https://cdn.jsdelivr.net/npm/@sctlib/matrix-room-element";
	mre.defineComponents();
	console.info("mre", mre);
</script>

2. Reference the <matrix-room-element> in your HTML file

<matrix-room-element profile-id="#libli-news:matrix.org"
	><matrix-room-element
/></matrix-room-element>

3. Use the DOM elements to style the component(s) with CSS

Check the css files in this project for some examples (later will come styles by themes/room/event types etc.)

with NPM

With npm: npm i --save @sctlib/matrix-room-element.

import mre from "@sctlib/matrix-room-element/index.js";
mre.defineComponents();

Then you can use the Custom elements in your HTML.

Elements

All elements can accept attributes that define its behavior.

All calls to Matrix APIs need a user to be authenticated. If no user is authenticated a "guest user" is automatically created for the user.

For missing attributes and documents, check the files in ./js, for each component. It should be consice and clear enough to get an idea of what each component can do

<matrix-room-element>

Displays the content of a matrix room.

profile-id (required) string=''

The id or alias of a matrix room, prefixed with #, and it should also include the server part :server.tld of the room.

event-id string=''

A matrix ID of an event.

Specifying an event-id, will only display this event in the room.

It is not necessary to specify show-context, to only show one event. Adding show-context will render the "load before" (in time) and "load after" (in time), buttons, at the top/bottom of the element's event list.

origin string=''

The origin is the base URL (as in new URL('https://example.org')), used to create links to content on the matrix element

Example: https://example.org/#room_alias:domain.tld/event_id

show-event-info boolean=false

Should each event show some information, such as the date of the event.

show-event-sender boolean=false

Should each event show information about the sender (user_id)

show-event-actions boolean=false

Should each event show some actions, such as a share, redact/edit event (if the user is logged in and the sender of the event).

show-context boolean=false

Should we show the room's context?

show-send-event boolean=false

Should the element show a form to send events to the room.

It will only show if there is a logged in user (see matrix-login element), and if the user has joined the room.

It renders a <matrix-send-event>, setup for sending into this room, as the logged in user.

send-event-types array='m.room.message'

A list of events the matrix-send-event is allowed to send.

show-space-children boolean=false

Should the element also display Matrix spaces that are children of the space specified in the profile-id.

flag-sanitizer boolean=false

Only set to true if the browser/platform has support for the window.Sanitizer api.

• Docs: https://developer.mozilla.org/en-US/docs/Web/API/Sanitizer
• Sanitizer polyfill: https://github.com/cure53/DOMPurify

See the index.html file on how to import one.

context-limit number=10

If show-context is true, how much element are fetched by the context API when lcicking the "load before/after" context button.

• Docs: https://spec.matrix.org/v1.3/client-server-api/#get_matrixclientv3roomsroomidcontexteventid

filter object={types, not_types, ...}

Filters (types and not_types), as specified in Matrix EventFilter API, for the /messsages and /context endpoints.

By default, it is set to:

{
	types: ['m.room.message', 'org.libli.room.message.track'],
	not_types: [
		'm.room.redaction',
		'm.room.member',
		'libli.widget',
		'im.vector.modular.widgets',
		'im.vector.modular.widgets.libli.widget',
		'm.reaction',
		'm.room.history_visibility',
		'm.room.power_levels',
		'm.room.name',
		'm.room.topic',
		'm.space.child',
		'm.room.avatar',
	]
}

• Docs: https://spec.matrix.org/v1.3/client-server-api/#filtering

<matrix-event>

<matrix-auth>

<matrix-login>

<matrix-logout>

<matrix-joined-rooms>

<matrix-join-room>

<matrix-send-event>

<matrix-create-room>

<matrix-edit-room>

Development

The project does not need any development tools, as it is vanilla Javascript, HTML and CSS. The same way, no build tools are needed, and the proejct is deployed and used unminified.

The easiest way to explore the project, is to:

1. clone repo
2. open index.html in a browser

Alternativelly, for development convenience:

1. yarn to install the development dependenceis
2. yarn develop to start the local developemnt server

Development notes

The project does not use the Matrix official SDK, but a custom one available in the file ./js/api.js.

production

CI/CD is defined in .gitlab.ci

gitlab page

The gitlab page is auto deployed when pushin on main, from the pages job

npm package @sctlib/matrix-room-element

1. bump package.json version, e.g: 0.0.1
2. https://gitlab.com/sctlib/matrix-room-element/-/tags publish a new gitlab tag (in GUI), v0.0.1
3. check the CI/CD pipelines for the publish job

docs

• https://www.matrix.org/docs/guides/creating-a-simple-read-only-matrix-client
• https://matrix.org/docs/api
• https://matrix.org/docs/api/#get-/_matrix/media/v3/thumbnail/-serverName-/-mediaId-

how to post in a room (with element.io)

1. create a matrix user account, or log into your existing one (using any matrix client). Your account can be on the server matrix.org, or any other (thanks to decentralization through federation)
2. create a public chat room, and give your room an alias of the form: #my-room:my-server.com (look in the room settings, you can also have many aliases, and also invite/restrict cooperators to your channel)
3. update the room settings, so that only "moderators" can post mesages (make it fit your multi/single user(s) cooperation usage).
4. In the room's settings, set: "Who can read history?" to "Anyone". Now, new messages will be available on libli's visitors.
5. start posting/uploading images in the chat room