Nine Pedestrians Mesmerized

    @sctlib/matrix-room-element

    0.0.60 • Public • Published

    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/index.js"></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

    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/index.js')
    1. Reference the <matrix-room-element> in your HTML file
    <matrix-room-element profile-id="#libli-news:matrix.org"><matrix-room-element/>
    1. Use the DOM elements to style the component(s) with CSS

    with NPM

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

    import '@sctlib/matrix-room-element/index.js'

    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-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.

    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.

    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',
    	]
    }

    <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

    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

    Install

    npm i @sctlib/matrix-room-element

    DownloadsWeekly Downloads

    59

    Version

    0.0.60

    License

    GPL-3.0-or-later

    Unpacked Size

    91.3 kB

    Total Files

    23

    Last publish

    Collaborators

    • user-09876