====== Matrix ======

<note tip>
This is just the start page of the Matrix documentation, have a look at //More Documentation// section at the bottom.

If you have questions about Encryption have a look at 
  * [[services:matrix:encryption|End-to-End-encryption for Matrix on Element]], and
  * [[services:matrix:mobile|Matrix on your phone]].
</note>

We are running a [[https://en.wikipedia.org/wiki/Matrix_(communication_protocol)|Matrix]] instance. Go to [[https://meet.physik.fu-berlin.de|meet.physik.fu-berlin.de]] to use the web client, where you can log in with your regular Physics account credentials.

Matrix is an instant messaging protocal, and is accessed by using a client. Analogously to how email is a protocol, and Gmail is a client. Like with email, there are many clients for Matrix. Different people can use different clients to contact each other. A good client to start using Matrix with is Element. You can use the web version of Element at [[https://meet.physik.fu-berlin.de|meet.physik.fu-berlin.de]], or use other versions of [[https://play.google.com/store/apps/details?id=im.vector.app|Android Clients]], [[https://itunes.apple.com/us/app/vector.im/id1083446067|iOS clients]] or [[https://element.io/get-started|Desktop clients]] ([[https://packages.riot.im/desktop/install/win32/x64/Element%20Setup.exe|Windows]], [[https://packages.riot.im/desktop/install/macos/Element.dmg|MacOS]], [[https://flathub.org/apps/details/im.riot.Riot|Linux]]) or any other Matrix client to [[https://matrix.physik.fu-berlin.de|matrix.physik.fu-berlin.de]]

Our Matrix server is not federated with the rest of the Matrix ecosystem, due to unresolved privacy questions, but we are giving access to external collaborators upon request.

===== First Steps =====

When you first log in at [[https://meet.physik.fu-berlin.de|meet.physik.fu-berlin.de]], you will see something like this

{{ :services:matrix:1.png?1000 |}}


The important parts of the screen are these
{{ :services:matrix:2.png?1000 |}}

  - is the user menu
  - is the bar of communities you are a part of
  - is the button to join/make a room, and is on top of the (currently empty) list of rooms we are participating in
  - is the button to start a direct message session with another user, and is on top of the (currently empty) list of direct conversations we are having
  - Is a search box used to find a specific room/person in your contacts. The compass icon to the right of it is to explore public rooms.

  

We will now look at all of these in turn.

==== Direct Messages and Rooms ====

When you press the button to start a direct message (the plus button in the //People// tab) labelled with <color #ed1c24>(4)</color>. You are presented with 
{{ :services:matrix:directmessage.png?direct |}}
If you use Matrix for a bit longer it will be filled with suggestions, but for a new user, it is empty. In the box you can type the name or ZEDAT account of the person you are searching for. Press //Go// to invite the person to chat. 

In this example we get an invite for such a direct message session. It pops up in the space where all our conversations are listed. By clicking on it we can choose whether to join or reject the conversation
{{ :services:matrix:4.png?1000 |}}

If we join, we end up in the messaging window
{{ :services:matrix:5.png?1000 |}}
and can start to chat. For more information what Matrix allows have a look at Beyond Text.

Let's use this window to explain what we can see
{{ :services:matrix:5_labeled.png?1000 |}}

At the bottom is the //message box// where you can enter your messages. To the right of the message box there are five buttons highlighted in red for (from left to right)
   * adding attachments,
   * emojis,
   * stickers (currently not supported),
   * starting a voice call, and
   * starting a video call.
The latter will add a widget to a [[services:jitsi:start|Jitsi room]] on our [[https://jitsi.physik.fu-berlin.de|Jitsi instance]] on top of the message space if you have more than two people in a room or directly start a video call if you are only two.

Furthermore, there are another four buttons on top of the screen highlighted in red and labelled 2.
From left to right:
   *Pinned messages
   *search within the chat
   *access to your notifications, and 
   *room info (which also contains some more settings)



=== Rooms ===

A room is a group chat. You can create a room by pressing the plus button beside the rooms tab labelled by <color #ed1c24>(3)</color>. Here you have the option to choose a room name, and whether the room will be public (searchable) or not. Once the room is created, you can invite individuals to it by pressing on the information button within the room, clicking invite, and then typing in their names.


{{ :services:matrix:6.png?500 |}}

To create a private room, just give it a name and optionally a topic and press //Create Room//. At first you will be alone, but you can invite more people via the //user list//.

If you press the "Make this room public" toggle, the window changes to
{{ :services:matrix:7.png?500 |}}
and will allow you to give the room a permanent identifier, the //room alias//, which uniquely identifies the room.

But what if you just want to join an exisiting public room. The //Explore // button (compass icon) <color #ed1c24>(5)</color> has you covered. When you click it you get a window where you can search the list of public rooms by name and room alias. 
{{ :services:matrix:explore.png?direct |}}

One such room is [[https://meet.physik.fu-berlin.de/#/room/!dLIiuUvCGCEVjzfutq:physik.fu-berlin.de?via=physik.fu-berlin.de#/room/!dLIiuUvCGCEVjzfutq:physik.fu-berlin.de?via=physik.fu-berlin.de|ZEDV-Support]], where the Physics IT service answers support questions and generally interacts with users. It looks like a direct chat session, only with more people, because that's what it is.
{{ :services:matrix:zedv_example.png?1000 |}}

==== Beyond Text ====

In the Matrix client we provide, you can do more than write simple text (and uploading files and images). You can style your text with [[https://commonmark.org/help/|Markdown]], including Hyperlinks and syntaxhighlighted code. You can also write LaTeX code for math inside dollar signs, e.g. ''$\LaTeX$'' for inline math and ''$$\LaTeX$$'' for display math.

When you hover over one of your messages you get a little context menu, that we will explain now. The buttons are (from left to right) //quick reactions//, //reply//, //edit// and //more options//
{{ :services:matrix:message_mouseover.png?direct |}}

=== Edits ===

Sometimes you have a typo and would like to fix it, with Matrix you can, just press the //edit// button on the message mouseover.

Before
{{ :services:matrix:edit_pre.png?direct |}}

After
{{ :services:matrix:edit_post.png?direct |}}


=== Delete Messages ===

Have you sent something to the wrong person? You can delete messages via the //delete// options on the //more options// (three dots) message mouseover.

Before
{{ :services:matrix:remove_pre.png?direct |}}

After
{{ :services:matrix:remove_post.png?direct |}}

=== Replies ===

Want to add some context that has already scrolled past in a busy room? The //reply// function has got you covered, just press the //reply// button on the message mouseover.
{{ :services:matrix:reply.png?direct |}}

=== Tabcompletion ===

One last feature, names tabcomplete. If you start typing ''@'' followed by the name or username of of a user, a little menu will pop up where you can choose the name by clicking or via the tab key if you are down to a single choice
{{ :services:matrix:tabcomplete.png?direct |}}

This results in a //mention// that is highlighted for the user you mentioned.
{{ :services:matrix:mention.png?direct |}}

Other things that tabcomplete are room names (starting with a ''#''), emojis (starting with a '':'') and communities (starting with a ''+'').

===== Further Steps =====

==== User Settings (Changing Your Name) ====

In the user menu <color #ed1c24>(1)</color> you can set many options.
{{ :services:matrix:settingsscreenshot.png?600 |{{ :services:matrix:settings.png?direct&1000 |}}}}

Among these settings are whether and how you want to receive desktop notifications, the theme you want (currently we only have the defaults light and dark), but also how your name is displayed and what your profile picture is. 
{{ :services:matrix:name_and_profilepic.png?direct |}}

If you change your name or profile picture, other users will see it right away, but the menu will only show it once you log out and back in.

You can also change your name and avatar on a per-room basis. This works only with commands. To change your name, type ''/myroomnick <name>''. To change your avatar in the room, use ''/myroomavatar'', then you will be prompted to choose a file from your computer which will be your new avatar.

==== Leaving a room ====

You can use the context menu for rooms
{{ :services:matrix:roommenu.png?1000 |}}

Or you can just type ''/part'' as a message into the room.

==== Getting people into a room ====

You can directly link to a (public) room via the information button on the top right 
{{ :services:matrix:sharing_a_room.png?1000 |}}
Press "Share room", and you will be presented with multiple means of sharing the room with someone
{{ :services:matrix:sharing_a_room2.png?600 |}}
==== Spaces ====

<note tip>This feature used to be called communities before, but has been supplanted by //spaces// as of late May 2021.</note>

You might wonder, "I have a group of people, but we also have a set of topics and a single room for that might be confusing!" Or you might wonder "Some of my rooms and conversations belong to this one thing, I'd like to group them together somehow." That is what spaces are for, they can group people and rooms, that means they are a tool to organise rooms and people by topic. When creating a space, you can add existing rooms, direct conversations and users to it. You can always add more rooms and people later and both rooms and people can be members of arbitrarily many spaces, so you can group them however you like.

Unfortunately which spaces exist on the server is currently **not** searchable, so you will need to be invited to join an existing space. This should become more comfortable soon™️.

Spaces are handled via the sidebar on the far left of your screen. It might look something like this.

{{ :services:matrix:spacessidebar.png | }}

This shows the sidebar of an account with two spaces (with initials T and F). Clicking on either of them will narrow the list of direct conversations and rooms to only those that belong to that space. The button at the top will return you to the view where you see all your direct conversations and rooms you are a member of (the //Home screen//). The bottom at the bottom will create a new space.

By default rooms that are part of a space are not shown in the list of rooms on the Home screen. If you want a room, that is part of a space, shown there you will need to either
  - set it as a favourite via the three button menu when you hover over its name,
  - right-click on the Home button and then on //Show all rooms//, or
  - enable //Show all rooms in Home// in the Spaces section of the //Preferences//
You can also just search for the name of the room in the search box above the list of all your rooms and conversations.

=== Public Spaces ===

When you click to create a new space you will be greeted with a small window

{{ :services:matrix:spacescreationdialog.png | }}

You can create public spaces (that - in the future - will be searchable like public rooms) and private spaces. Private spaces are for closed groups or just for your personal usage to organise rooms just the way you like.

If you click to create a public space you will get this small window

{{ :services:matrix:spacespubliccreationdialog.png | }}

where you can set a name and description for the space. This dialog is the same when creating a private space. 

Afterwards you will be offered to create rooms for that space

{{ :services:matrix:spacesroomcreation.png | }}

If you already have rooms that you want to add to the space and don't want to create new ones, you must delete the suggestions so that the **Continue** button changes to a **Skip for now** button.

Afterwards you can add other people to your room either by copying an invite link or via the usual dialog to add people to a room.

{{ :services:matrix:spacespublicinvite.png | }}

You can always add rooms and people to your space later.

Finally you will land on the landing page of your space

{{ :services:matrix:spaceoverview.png | }}

Here you can add more rooms and people to your space or change its name and description and whether it is public or private (via the settings menu that you can reach via the gear symbol)

=== Private Spaces ===

You can create private spaces for your groups or projects or just for yourself. That's the first question you will be asked when creatin a private space

{{ :services:matrix:spacesprivatequestion.png | }}

If you press **Just me** here, you will be shown a list of all the rooms you are a member of and you can mark them to be added to your private space.

if you press **Me and my teammates** you will be shown a dialog to invite people

{{ :services:matrix:spacesteammatesinvite.png | }}

You //must// invite them via their usernames or skip this step for now, since for our Matrix instance users will not be able to join via app.element.io

Afterwards you will get the same room creation dialog as for public spaces discussed above, where you need to remove the suggested room names if you don't want to create new rooms to skip that step.

If you later decide you want to share your private space with other people, you can always do that and invite people to it. Since the menu to add rooms to spaces is much nicer for personal use private rooms, this is the recommended way to create private spaces and to later invite more users to it instead of going through the general private space creation.
===== Usage tips =====

  * You can search for other users by their display name or ZEDAT username, the display name is the person's name by default, but users may change it.
  * You can highlight messages for certain users by mentioning them. You do this by typing ''@'' followed by their name, use tab to autocomplete.
  * The little symbols to the right of messages are read markers.
  * Messages can be formatted in Markdown (tables are unfortunately not supported in the current Markdown flavour).
  * You can share images and files.
  * Emojis can be typed by starting with a colon '':'' followed by the name, choices will pop up.
  * Messages can be edited after sending them. Use the context menu when hovering over a message.
  * You can reply to messages, quoting them thereby. Use the context menu when hovering over a message.
  * You can react to messages. Use the smilie context menu when hovering over a message.
  * You can add a [[services:jitsi:start|Jitsi]] widget using our Jitsi server to bind a fixed Jitsi room to your Matrix room via the video camera button on the far right of the message input box
  * If you need to see the actual events your client and the Matrix server are exchanging, you can see them by clicking ''View Source'' on the context menu of a message. Starting with Element (1.10.9) you first need to activate that option by typing ''/devtools'' first in the message box and hitting enter.
===== More Documentation =====

  * [[services:matrix:encryption|How to guide for end-to-end encryption on Element]]