Jump to content

Forum / Gitter Sidecar Implementation


Recommended Posts

Just found that we can embed Gitter in to the forum as a side car! This would be a cool addition and its basically putting both are main comm's for Denarius in to one section.

Link to find: https://sidecar.gitter.im/

Add some Gitter to your site

Sidecar is a (mostly) code-free way of embedding Gitter into your website with a simple JavaScript snippet.

It works out of the box with no customization, or you can control its behaviour with some basic configuration.

Just copy and paste it into your site:

<script>
  ((window.gitter = {}).chat = {}).options = {
    room: 'denariusproject'
  };
</script>
<script src="https://sidecar.gitter.im/dist/sidecar.v1.js" async defer></script>

 

Overview

Primarily sidecar has an activation element that will show sidecar and a target element where sidecar gets loaded. These elements are specified by default but can be customised (see below).

UI Customisation

If you need a custom button or want to insert the chat in your own element, use the following setup:

  • Activation element: The "Open Chat" button
  • Target element: The wrapper element that the chat is embedded into
<script>
  ((window.gitter = {}).chat = {}).options = {
    room: 'gitterHQ/sidecar',
    activationElement: '.my-special-button',
    targetElement: '.my-special-target-element'
  };
</script>

Toggle Buttons

You can define toggle/open/close buttons in your page using the .js-gitter-toggle-chat-button class and an optional data-gitter-toggle-chat-state attribute. If you do not provide a data-gitter-toggle-chat-state, it will default to 'toggle'. See the examples/toggle-chat-class-buttons example.

<button class="js-gitter-toggle-chat-button">Toggle Chat</button>
<button class="js-gitter-toggle-chat-button" data-gitter-toggle-chat-state="true">Open Chat</button>
<button class="js-gitter-toggle-chat-button" data-gitter-toggle-chat-state="false">Close Chat</button>

Examples

Options

Set options with the global window option:

<script>
  ((window.gitter = {}).chat = {}).options = {
    room: 'gitterHQ/sidecar'
  };
</script>

You can also override these options individually on the target element:

<div
  class="gitter-chat-embed"
  data-room="gitterHQ/sidecar"
></div>
  • options.room: string - This is the Gitter room that sidecar will load (gitterHQ/sidecar)
    • Acceptable values: string
    • Default: undefined
  • options.targetElement: Where you want to embed the chat.
    • Acceptable values: Dom node, array of dom nodes, or a string selector
    • Default: Elements that match '.gitter-chat-embed'
  • options.activationElement: When options.showChatByDefault is false, this is the element you have to click/interact with to get the chat to actually embed, "Open Chat" button.
    • Acceptable values: Dom node, array of dom nodes, a string selector, or boolean
    • Default: undefined
    • Note: This will automatically get generated if you don't specify it (undefined, or true)
      • Note: Passing in false or null will disable the activation element
  • options.showChatByDefault: Whether to embed the chat on page load(true) or wait until the options.activation is resolved/clicked/interacted with(false).
    • Acceptable values: boolean
    • Default: false
    • Note: Use with caution, useful for use cases where you have a page dedicated to chat.
  • options.useStyles: This will embed CSS into your document to style the activation and target element. If you want to customise these, set this option to false and specify your own CSS.
    • Acceptable values: boolean
    • Default: true
  • preload: Whether the Gitter chat iframe should be loaded in when the chat embed instance is created(this is the page load for default embed)
    • Acceptable values: boolean
    • Default: false

Window Options:

You can set any of the chat options above in this object as well

  • window.gitter.chat.options.disableDefaultChat: Stop the default chat from loading on the page when including the Sidecar script. So you can handle the Gitter chat creation yourself.
    • The default chat is stored on window.gitter.chat.defaultChat.

API

gitter.Chat

var chat = new window.gitter.Chat(/* options */);`
  • options (getter): Get a readable copy of the options used for this chat instance
  • toggleChat(isChatOpen): Function/method - Takes a boolean which toggles the visibility of the chat panel
    • This can be used an explicit show/hide method by passing in a explict show(true) or hide(false) boolean.
  • destroy(): Function/method - Clean-up and remove any elements created by the embed

Events

Emitted on Document:

  • gitter-sidecar-ready: Emitted when the sidecar script has loaded and is available via window.gitter
  • gitter-sidecar-instance-started: Emitted after any Sidecar chat instance has initialized
    • Data: chat: The sidecar chat instance that was initialized

Emitted on Target Element:

  • gitter-chat-toggle: Emitted whenever the chat is opened or closed
    • Data: state: Whether it was opened(true) or closed(false)
  • gitter-chat-started: Emitted after the Sidecar chat instance has initialized
    • Data: chat: The sidecar chat instance that was initialized

example:

document.querySelector('.gitter-chat-embed').addEventListener('gitter-chat-toggle', function(e) {
  console.log(e.detail.state ? 'Chat Opened' : 'Chat Closed');
});

 

  • Upvote 2

Thanks,

Stu - (RecoStar)

Denarius Mod

denarius-dnr.png.c89033ca9f0500ec0bcdf83c7dbb6e27.png

Link to post
Share on other sites

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Guest
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

×
×
  • Create New...