You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Easily create custom web cards containing GitHub's repository data.
1
+
# GitHub-Repos-WebCards
2
+
Easily create custom web cards containing GitHub's repositories data.
3
3
4
4
## What and why?
5
5
During the development of my new static (without backend) blog/website, I wanted to include some data from my coding projects. Since they are hosted on GitHub, I thought it would be best to get the data automatically from GitHub through its APIs, instead of having to manually update the data each time. I looked for projects that did this, but found few resources and almost all of them were very dated. Others had a fixed theme that did not integrate with the style of my site and they were not showing the data I wanted. So I decided to write a small script myself, and hoping it will be useful, I leave it available here for everyone.
6
6
7
-
## It's really needed? What adds to the GitHub's APIs?
7
+
## Is it really needed? What does it add to the GitHub's APIs?
8
8
Sincerely no, it's not something of unique and special. Is simply a wrapper of the GitHub's APIs and doesn't add anything to them. However, I think it can be common to want to pull data from GitHub, for example in developer portfolios. It is, of course, possible to make all the desired requests manually from scratch, but this requires some effort and tedium. This project hopes to provide something, while simple, that is workable and provides a stable baseline allowing you to not reinvent the wheel if you only want some basic repo statistics. **It is not meant for complex projects that require sophisticated interactions with GitHub's APIs.**
9
9
10
10
## Demo
11
-
A demo is avaible [here](https://juliusnixi.github.io/GitHub-Repo-WebCards/). It's the 'index.html' this repo file.
11
+
A demo is avaible [here](https://juliusnixi.github.io/GitHub-Repos-WebCards/). It's the 'index.html' this repo file hosted on GitHub pages.
12
12
13
13
## Styles and frameworks agnostic
14
14
A key concept of the project is the style and framework agnosticism. In fact, I want anyone to be able to take the data and decide what style to use with them and on what frontend framework. In the future, could be added some default themes, but freedom from styling and tech stack will always be central.
@@ -24,92 +24,92 @@ Two possibility:
24
24
* Download the javascript vanilla script from here to serve it with your site's assets, so you are independent.
25
25
* Serve it through a CDN in this way (thanks to [jsDelivr](https://www.jsdelivr.com)):
* Get data from a specific single repo and its owner.
33
33
```html
34
-
<gh-repo-cards
34
+
<gh-repos-cards
35
35
style="display: none;"
36
36
data-user="GITHUB-USERNAME"
37
37
data-repo="GITHUB-REPO-NAME">
38
38
39
39
<div
40
-
class="gh-repo-cards-div">
40
+
class="gh-repos-cards-div">
41
41
42
+
<p> ...Optional content... </p>
42
43
<!-- ... DESIRED DATA HERE (SEE BELOW) ... -->
43
44
44
45
</div>
45
46
46
-
</gh-repo-cards>
47
+
</gh-repos-cards>
47
48
```
48
49
* Get ALL the repositories data from a GitHub owner.
49
50
```html
50
-
<gh-repo-cards
51
-
style="display: none;"data-user="GITHUB-USERNAME"
51
+
<gh-repos-cards
52
+
style="display: none;"
53
+
data-user="GITHUB-USERNAME"
52
54
data-repo="%all"
53
55
data-sort="created"
54
56
data-direction="desc">
55
57
56
58
<div
57
-
class="gh-repo-cards-div">
59
+
class="gh-repos-cards-div">
58
60
59
61
<p> ...Optional content... </p>
60
62
<!-- ... DESIRED DATA HERE (SEE BELOW) ... -->
61
63
62
64
</div>
63
65
64
-
</gh-repo-cards>
66
+
</gh-repos-cards>
65
67
```
66
68
### All repositories args explaination
67
-
Note here the `data-repo="%all"`. '%' is not an admitted character for the GitHub's repository name, so there is no danger of conflict if you wanted to get a single repository with that name, it cannot exist on GitHub.
68
-
The `data-sort="created"` and the `data-direction="desc"` attributes are used only in this all mode, otherwise ignored. They are optional, if both not present, the order of the respositories is undefined (random). If the first is present but not the second, an error is throw. If the second is present, but not the first, the second is ignored and no sort is applied. `data-sort` could be one from `['created', 'updated', 'pushed', 'full_name']`. `data-direction` could be one from `['asc', 'desc']`. In this mode the script will clone the `gh-repo-cards-div` and all its content, there will be a new one (copy) for each repo. So in the example above all the repos will have the `<p>` at the beginning.
69
+
Note here the `data-repo="%all"`. '%' is not an admitted character for the GitHub repository name, so there is no danger of conflict if you wanted to get a single repository with that name, it cannot exists on GitHub.
70
+
The `data-sort="created"` and the `data-direction="desc"` attributes are used only in this all mode, otherwise ignored. They are optional, if both not present, the order of the respositories is undefined (random). If the first is present but not the second, an error is throw. If the second is present, but not the first, the second is ignored and no sort is applied. `data-sort` could be one from `['created', 'updated', 'pushed', 'full_name']`. `data-direction` could be one from `['asc', 'desc']`. In this mode the script will clone the `gh-repos-cards-div` and all its content, there will be a new one (copy) for each repo. So in the example above all the repos will have the `<p>` at the beginning.
69
71
70
72
## General explaination for both modes
71
-
* The data will be injected in every `<gh-repo-cards>`.
73
+
* The data will be injected in every `<gh-repos-cards>`.
72
74
* The `style="display: none;"` is optional, but recommended, it will automatically removed from this script after the data injection to prevent showing empty html structure to the website viewer during the data download. So **don't use inline CSS on this tag**.
73
-
* In each `<gh-repo-cards>` exactly 1 `<div>` with at least the `gh-repo-cards-div` class must be present, otherwise an error is throw. All the html strcture to contain the desired data must be in this div, otherwise their won't be filled.
74
-
* The `data-user` and `data-repo` attributes in the `<gh-repo-cards>` must be present and setted respectively to the desired GitHub repository owner and to his repository's name.
75
+
* In each `<gh-repos-cards>` exactly 1 `<div>` with at least the `gh-repos-cards-div` class must be present, otherwise an error is throw. All the html strcture to contain the desired data must be in this div, otherwise their won't be filled.
76
+
* The `data-user` and `data-repo` attributes in the `<gh-repos-cards>` must be present and setted respectively to the desired GitHub repository owner and to his repository's name.
75
77
76
78
## Usage
77
-
Wherever and whenever you want simply call the javascript function `GHRepoCardsInit(ENABLE_CACHING)`. The function **must be called only once**, otherwise an error is throw to avoid undefined behaviours. The function must take as arg a boolean. True to enable the cache system, false otherwise. If the cache is disabled, if a cache has been previously setted, it will be cleared. The function will fill all the `gh-repo-cards-div` in the `<gh-repo-cards>` tags with the requested data.
79
+
Wherever and whenever you want simply call the javascript function `GHRepoCardsInit(ENABLE_CACHING)`. The function **must be called only once**, otherwise an error is throw to avoid undefined behaviours. The function must take as arg a boolean. True to enable the cache system, false otherwise. If the cache is disabled, if a cache has been previously setted, it will be cleared. The function will fill all the `gh-repos-cards-div` in the `<gh-repos-cards>` tags with the requested data.
Put the desired html data structure inside the `gh-repo-cards-div`.
95
+
Put the desired html data structure inside the `gh-repos-cards-div`.
94
96
95
97
## Basic APIs
96
98
The functions that compose the script are also avaible as APIs to be called outside the script to allow you to take advantage of them if you need to develop your own custom features. However, if you think these might be useful to everyone you might consider collaborating directly on this repo. To use them see this example:
97
99
```javascript
98
100
GHRepoCardsInit(true).then(result=> {
99
-
// Use APIs here.
101
+
// Use APIs functions here.
100
102
// Optionally here you can also process the data injected however you want.
Note that here we take advantage of the `getData()` function to download data that the script itself doesn't get. For all avaible GitHub's APIs endpoints refer [here](https://docs.github.com/en/rest?apiVersion=2022-11-28). Here's the listand signatures:
106
+
Note that here we take advantage of the `getData()` function to download data that the script itself doesn't get. For all avaible GitHub's APIs endpoints refer [here](https://docs.github.com/en/rest?apiVersion=2022-11-28). Here's the list, signatures and infos on the script's APIs:
105
107
*`function clearDataLocal(repoName)` : Pass `null` to clear all the repos data saved in the cache. Otherwise, pass the specific repo's name as string to remove it from the cache.
106
-
*`function saveDataLocal(repoData)` : Pass the repo object to save in the local cache. `repoData` is a `{}`containing all repo's data. It's the returned value of `getSingleRepo(...)` (see below) call function.
107
-
*`function getDataLocal()` : Returns an object `{}` containing as keys the repos' names and as values the`repoData`objects. `repoData` is a `{}`containing all repo's data. It's the returned value of `getSingleRepo(...)` (see below) call function.
108
-
*`function putData(repoData, cardDiv)` : Pass the object containing the repo's data to inject in the html structures contained in the `cardDiv`. `repoData` is a `{}`containing all repo's data. It's the returned value of `getSingleRepo(...)` (see below) call function.
108
+
*`function saveDataLocal(repoData)` : Pass the repo object to save in the local cache. `repoData` is a `{}`rapresenting [this](https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#get-a-repository) response from GitHub's APIs. If the repo is already present, it's overwritten with a new expiry.
109
+
*`function getDataLocal()` : Returns an object `{}` containing for each repo name as key an another object as value with`repoData`and `expiry` keys. `repoData` is a `{}`rapresenting [this](https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#get-a-repository) response from GitHub's APIs. `expiry` contains when the data will be invalidated from the cache and redownloaded. It's this function that when called checks if the data contained in the cache are expired and if so, delete them before returning.
110
+
*`function putData(repoData, cardDiv)` : Pass the object containing the repo's data to inject in the html structures contained in the `cardDiv`. `repoData` is a `{}`rapresenting [this](https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#get-a-repository) response from GitHub's APIs. `cardDiv` must be an html div element with at least the `gh-repos-cards-div` class.
109
111
*`async function getData(query)` : Pass the query as string. It's the GitHub's API desired endpoint. It's the part of string after `https://api.github.com/`. So this prefix it's prefixed by the function, don't pass it. Its returned value depends from the GitHub's APIs.
110
-
*`async function getAllRepos(userString, sortString)` : Pass the GitHub owner username as string. Pass as `sortString` something like `sortString = "&sort=REPOSORT&direction=SORTDIRECTION`, the capsed params are explained above in the "All repositories args explaination" section. No data are saved in the cache. Returns an object `{}` containing as keys the repos' names and as values the `repoData` objects. `repoData` is a `{}` containing all repo's data. It's the returned value of `getSingleRepo(...)` (see below) call function.
111
-
*`async function getSingleRepo(userString, repoString)` : Pass the GitHub's repo owner's username as string. Pass the GitHub's repo's name as string. No data are saved in the cache. Returns a `repoData` object. `repoData` is a `{}` rapresenting [this](https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#get-a-repository) response from GitHub's APIs.
112
-
113
-
112
+
*`async function getAllRepos(userString, sortString)` : Pass the GitHub owner username as string. Pass as `sortString` something like `sortString = "&sort=REPOSORT&direction=SORTDIRECTION`, the capsed params are explained above in the "All repositories args explaination" section. No data are saved in the cache, make it you if you want. The returned value is like `getDataLocal()`. Here `expiry` is not significant since the data could be getted from cache (if enabled and so with a valid expiry) or redownloaded otherwise.
113
+
*`async function getSingleRepo(userString, repoString)` : Pass the GitHub repo owner's username as string. Pass the GitHub repo's name as string. No data are saved in the cache, make it you if you want. The returned value is like `getDataLocal()`. Here `expiry` is not significant since the data could be getted from cache (if enabled and so with a valid expiry) or redownloaded otherwise.
0 commit comments