Skip to content

Commit a510a75

Browse files
jonericksonjonerickson
authored
Updated widget docs (#15)
1 parent 266421f commit a510a75

File tree

5 files changed

+87
-28
lines changed

5 files changed

+87
-28
lines changed

‎docs/external-integration/api.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -42,12 +42,12 @@ in each example with the correct values.
4242

4343
::: code-group
4444

45-
```php [PHP]
45+
```php:line-numbers [PHP]
4646
use GuzzleHttp\Client;
4747
4848
// Create a client with a base URI
4949
$client = new Client([
50-
'base_uri' => 'https://api.perscom.io/v1',
50+
'base_uri' => 'https://api.perscom.io/v1/',
5151
'timeout' => 2.0,
5252
'headers' => [
5353
'Accept' => 'application/json',
@@ -60,7 +60,7 @@ $client = new Client([
6060
$response = $client->request('GET', 'users');
6161
```
6262

63-
```js [Javascript (fetch)]
63+
```js:line-numbers [Javascript (fetch)]
6464
fetch('https//api.perscom.io/v1/users', {
6565
method: 'GET',
6666
headers: {
@@ -78,8 +78,8 @@ fetch('https//api.perscom.io/v1/users', {
7878
})
7979
```
8080

81-
```js [Javascript (axios)]
82-
var axios = require("axios");
81+
```js:line-numbers [Javascript (axios)]
82+
var axios = require('axios')
8383
8484
axios
8585
.get('https://api.perscom.io/v1/users', {

‎docs/external-integration/widgets.md‎

Lines changed: 52 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -9,21 +9,39 @@ Each widget integration requires your PERSCOM ID and the use of an API key with
99
PERSCOM ID can be found under the general settings of your Dashboard.
1010
:::
1111

12+
## Choosing The Widget
13+
14+
Each widget uses the same HTML code snippet to display the data. However, to set which widget you would like outputted, you must set the
15+
`data-widget` attribute to the intended widget. The available options are listed below.
16+
17+
```html
18+
<div id="perscom_widget_wrapper">
19+
<script
20+
id="perscom_widget"
21+
data-perscomid="PERSCOMID"
22+
data-apikey="APIKEY"
23+
data-widget="roster" // [!code focus]
24+
src="https://widget.perscom.io/widget.js"
25+
type="text/javascript"
26+
></script>
27+
</div>
28+
```
29+
1230
## Available Widgets
1331

1432
The following widgets are currently available.
1533

16-
1. [Roster](/external-integration/widgets/roster)
17-
2. [Awards](/external-integration/widgets/awards)
18-
3. [Ranks](/external-integration/widgets/ranks)
34+
1. [Roster](/external-integration/widgets/roster) `data-widget='roster'`
35+
2. [Awards](/external-integration/widgets/awards) `data-widget='awards'`
36+
3. [Ranks](/external-integration/widgets/ranks) `data-widget='ranks'`
1937

2038
## Authentication and Authorization
2139

2240
Each widget requires the creation of an API key with the `access:widget` scope assigned. Generating API keys is a simple process that can be
2341
accomplished in your Dashboard. Creation and management of API keys require the `manage:api` permission. Contact your account administrator
2442
if you cannot access the API section within your Dashboard.
2543

26-
Second, each widget requires your PERSCOM ID which can be found in the General Settings area of your Dashboard.
44+
Second, each widget requires your PERSCOM ID which can be found in the general settings area of your Dashboard.
2745

2846
These two items will be inserted into the widget when you add them to your website. Failure to add these values with result in an
2947
authentication error when viewing the widget.
@@ -32,27 +50,47 @@ Click [here](/external-integration/api) for more documentation on the API.
3250

3351
## Customization
3452

35-
Each widget may be customized using CSS by using the uniquely named DOM elements that comprise each widget. To get started, inspect the
36-
widget in your preferred browser so that you can see the HTML. Identify the element you would like to customize and make note of the `id`
37-
attribute. Using the HTML `<style>` tag, add your custom CSS above the widget HTML. You can view the example below for further explanation.
53+
The widgets are embedded within an `iframe` HTML element that prevents the host website from overriding and altering the styling of the
54+
widget. While this may seem like a disadvantage, it helps prevent the unwanted style changes to the widget that can happen by the hosting
55+
website. However, the widget is wrapped in a parent div that may be customized to alter how the `iframe` is embedded within your website.
56+
See the example below on how to customize the `perscom_widget_wrapper`.
3857

3958
### Example
4059

41-
In the following example, we are going to center each table column header within the roster widget. The `id` of the `<th>` element that we
42-
are going to customize is `perscom_widget_table_header_column`. Making note of this, we have inserted the custom CSS above the widget.
60+
In the following example, we are going to adjust the height of the parent div to fit the widget appropriately. The CSS is added just above
61+
the code snippet for it to take affect.
4362

4463
```html
4564
<style>
46-
#perscom_widget_table_header_column {
47-
text-align: center;
65+
#perscom_widget_wrapper {
66+
height: 500px;
4867
}
4968
</style>
5069

51-
<div id="perscom_roster" data-apikey="APIKEY" data-perscomid="PERSCOMID"></div>
52-
<link href="https://widget.perscom.io/widget.css" rel="stylesheet" />
53-
<script src="https://widget.perscom.io/widget.js"></script>
70+
<div id="perscom_widget_wrapper">
71+
<script
72+
id="perscom_widget"
73+
data-perscomid="PERSCOMID"
74+
data-apikey="APIKEY"
75+
data-widget="roster"
76+
src="https://widget.perscom.io/widget.js"
77+
type="text/javascript"
78+
></script>
79+
</div>
5480
```
5581

82+
## Externally Accessing The Widget
83+
84+
The PERSCOM.io widget can be accessed outside of the HTML code snippet that you used to post within your website. To see your widget live,
85+
without embedding it in a website, you can visit the URL's below. Make sure to set APIKEY and PERSCOMID to the correct values.
86+
87+
Roster:
88+
[https://widget.perscom.io/roster?apikey=APIKEY&perscomid=PERSCOMID](https://widget.perscom.io/roster?apikey=APIKEY&perscomid=PERSCOMID)
89+
Awards:
90+
[https://widget.perscom.io/awards?apikey=APIKEY&perscomid=PERSCOMID](https://widget.perscom.io/awards?apikey=APIKEY&perscomid=PERSCOMID)
91+
Ranks:
92+
[https://widget.perscom.io/ranks?apikey=APIKEY&perscomid=PERSCOMID](https://widget.perscom.io/ranks?apikey=APIKEY&perscomid=PERSCOMID)
93+
5694
## Development
5795

5896
The PERSCOM.io Widget project is **open source** and actively looking for developers to participate. If you have experience with frontend

‎docs/external-integration/widgets/awards.md‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,14 @@ Make sure to replace APIKEY and PERSCOMID with the appropriate values.
1313
<!-- Place the code block where you would like the widget displayed on your website. !-->
1414
<!-- Replace APIKEY and PERSCOMID with your API key with the ‘access:widget' scope and PERSCOM ID, respectively. !-->
1515

16-
<div id="perscom_awards" data-apikey="APIKEY" data-perscomid="PERSCOMID"></div>
17-
<link href="https://widget.perscom.io/widget.css" rel="stylesheet" />
18-
<script src="https://widget.perscom.io/widget.js"></script>
16+
<div id="perscom_widget_wrapper">
17+
<script
18+
id="perscom_widget"
19+
data-perscomid="PERSCOMID"
20+
data-apikey="APIKEY"
21+
data-widget="awards"
22+
src="https://widget.perscom.io/widget.js"
23+
type="text/javascript"
24+
></script>
25+
</div>
1926
```

‎docs/external-integration/widgets/ranks.md‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,14 @@ Make sure to replace APIKEY and PERSCOMID with the appropriate values.
1313
<!-- Place the code block where you would like the widget displayed on your website. !-->
1414
<!-- Replace APIKEY and PERSCOMID with your API key with the ‘access:widget' scope and PERSCOM ID, respectively. !-->
1515

16-
<div id="perscom_ranks" data-apikey="APIKEY" data-perscomid="PERSCOMID"></div>
17-
<link href="https://widget.perscom.io/widget.css" rel="stylesheet" />
18-
<script src="https://widget.perscom.io/widget.js"></script>
16+
<div id="perscom_widget_wrapper">
17+
<script
18+
id="perscom_widget"
19+
data-perscomid="PERSCOMID"
20+
data-apikey="APIKEY"
21+
data-widget="ranks"
22+
src="https://widget.perscom.io/widget.js"
23+
type="text/javascript"
24+
></script>
25+
</div>
1926
```

‎docs/external-integration/widgets/roster.md‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,16 @@ Make sure to replace APIKEY and PERSCOMID with the appropriate values.
1313
<!-- Place the code block where you would like the widget displayed on your website. !-->
1414
<!-- Replace APIKEY and PERSCOMID with your API key with the ‘access:widget' scope and PERSCOM ID, respectively. !-->
1515

16-
<div id="perscom_roster" data-apikey="APIKEY" data-perscomid="PERSCOMID"></div>
17-
<link href="https://widget.perscom.io/widget.css" rel="stylesheet" />
18-
<script src="https://widget.perscom.io/widget.js"></script>
16+
<div id="perscom_widget_wrapper">
17+
<script
18+
id="perscom_widget"
19+
data-perscomid="PERSCOMID"
20+
data-apikey="APIKEY"
21+
data-widget="roster"
22+
src="https://widget.perscom.io/widget.js"
23+
type="text/javascript"
24+
></script>
25+
</div>
1926
```
2027

2128
## Example

0 commit comments

Comments
 (0)