# Basic Widget usage

Paste the code anywhere on your website (preferably **HEAD** or **before closing BODY** tag).

```markup
<script>
  var HW_config = {
    selector: ".CHANGE_THIS", // CSS selector where to inject the badge
    account: "ACCOUNT_ID" // your account ID, you can find it in Settings->Widget
  };
</script>
<script async src="//cdn.headwayapp.co/widget.js"></script>
```

For example if you have a heading with a logo on your page that looks like:

```markup
<h1>
  <a href="">Acme Corp.</a>
</h1>
```

You can set the code to inject the badge into the `h1` tag:

```javascript
var HW_config = {
  selector: "h1",
  account: "ACCOUNT_ID"
};
```

The end result will look like this:

```markup
<h1>
  <a href="">Acme Corp.</a>
  <span id="HW_badge_cont">
    <span id="HW_badge">1</span>
  </span>
</h1>
```

### Options

* `account` (required) - Your account ID
* `selector` (required) - CSS selector where to inject the badge
* `enabled` - a boolean value if the widget should automatically initialize itself. If set to `false` it's up the the developer to initialize the widget with `Headway.init()` or `Headway.init(config)`
* `translations` - See Translations section below.
* `position.x` (experimental) - force horizontal position of the widget ("left" or "right")
* `position.y` (experimental) - force vertical position of the widget ("top" or "bottom")
* `trigger` - Selector for externally triggering the widget popover. The popover will still be anchored to the badge, not the external trigger.
* `callbacks.onWidgetReady` - callback fired when widget has loaded.
* `callbacks.onShowWidget` - callback fired when widget is shown.
* `callbacks.onShowDetails` - callback fired when an item in the widget is clicked.
* `callbacks.onReadMore` - callback fired when user clicks on readMore link.
* `callbacks.onHideWidget` - callback fired when user closes the widget.

```javascript
var HW_config = {
  selector: ".CHANGE_THIS",
  account: "ACCOUNT_ID",
  callbacks: {
    onWidgetReady: function(widget) {
      console.log("Widget is here!");
      console.log("unseen entries count: " + widget.getUnseenCount());
    },
    onShowWidget: function(){
      console.log("Someone opened the widget!");
    },
    onShowDetails: function(changelog){
      console.log(changelog.position); // position in the widget
      console.log(changelog.id); // unique id
      console.log(changelog.title); // title
      console.log(changelog.category); // category, lowercased
    },
    onReadMore: function(changelog){
      console.log(changelog); // same changelog object as in onShowDetails callback
    },
    onHideWidget: function(){
      console.log("Who turned off the light?");
    }
  }
};
```

### Initializing widget programmatically (SPA)

Some apps reload content dynamically (through Angular, React or other means), this means that you'll probably want to initialize the widget inside of your JavaScript code. To do this you need to use `Headway.init()` – this will create a new widget instance.

You can pass a single argument with `Headway.init(config)` which is the config object, in this case it doesn't have to be named `HW_config` but anything, for example:

```markup
<script src="//cdn.headwayapp.co/widget.js"></script>
<script>
  var config = {
    selector: ".CHANGE_THIS",
    account: "ACCOUNT_ID"
  };
  Headway.init(config);
</script>
```

**Tip:**

* Running `Headway.init()` again will destroy the previous widget and replace it with a new instance.
* In **Angular/React** you should initialize the widget every time the badge element container is re-rendered.

### Translating the text inside of the widget

* `title` changes the title of the widget from **Latest awesome changes** to anything you wish
* `labels` will replace current labels with provided ones
* `readMore` changes the read more link from **Read the whole scoop**
* `footer` link at the bottom of the widget

```javascript
var HW_config = {
  selector: ".CHANGE_THIS",
  account: "ACCOUNT_ID",
  translations: {
    title: "The Changelog",
    readMore: "Read more",
    labels: {
      "new": "News",
      "improvement": "Updates",
      "fix": "Fixes"
    },
    footer: "Read more 👉"
  }
};
```

### Styling the badge

Since the badge is injected into your HTML, you can simply style it with CSS.

For example if you need the badge to overlay an element on your page, you can either inject it into your own element container that is positioned over an element, or alter the badge styles:

```css
#HW_badge_cont {
  position: absolute !important;
}
```

Similarly you can change the color of the badge itself:

```css
#HW_badge {
  background: #5ab987 !important;
}
```