Skip to content

Commit dfcd271

Browse files
CodyToleneCodyTolene
authored
Merge pull request #2 from ProAngular/ct/wrap-up-todos
Ct/wrap up todos
2 parents e066a40 + b2eb5ae commit dfcd271

18 files changed

+650
-139
lines changed

Diff for: ‎README.md

+148-4
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
<p align="center">
22
<a href="https://www.ProAngular.com" target="_blank">
3-
<img src="src/assets/images/pro-angular-logo.png" />
3+
<img src="https://github.com/ProAngular/ngx-gist/raw/main/src/assets/images/pro-angular-logo.png" />
44
</a>
55
<h1 align="center">
66
<a href="https://www.ProAngular.com" target="_blank">
77
Pro Angular
8-
</a>: GitHub gist Code Snippet Display
8+
</a>: GitHub gist Code Snippet Tabs
99
</h1>
1010
</p>
1111

@@ -14,11 +14,155 @@
1414
[![Join the chat at https://gitter.im/ProAngular/community](https://badges.gitter.im/ProAngular/lobby.svg)](https://gitter.im/ProAngular/community)
1515
[![Verify and Deploy to GitHub Packages](https://github.com/ProAngular/ngx-gist/actions/workflows/on-merge-main-deploy-gpr.yml/badge.svg)](https://github.com/ProAngular/ngx-gist/actions/workflows/on-merge-main-deploy-gpr.yml)
1616
[![Verify and Deploy to npmjs](https://github.com/ProAngular/ngx-gist/actions/workflows/on-merge-main-deploy-npmjs.yml/badge.svg)](https://github.com/ProAngular/ngx-gist/actions/workflows/on-merge-main-deploy-npmjs.yml)
17+
[![Monthly Downloads](https://img.shields.io/npm/dm/@ProAngular/ngx-gist.svg)](https://www.npmjs.com/package/@proangular/ngx-gist)
18+
[![npm bundle size (minified + gzip)](https://img.shields.io/bundlephobia/minzip/ProAngular/ngx-gist.svg)](https://bundlephobia.com/result?p=ProAngular/ngx-gist)
19+
[![License](https://img.shields.io/npm/l/express.svg?maxAge=2592000)](/LICENSE)
1720

1821
# Description
1922

20-
An Angular Material and HighlighJs styled display box for GitHub gist and local code snippets.
23+
An Angular Material and HighlighJs styled display box for GitHub gist and local code snippets. All files from the remote/local gist are displayed in separate tabs for users to easily navigate. Many optional features and themes are available. Enjoy!
2124

2225
# Demo
2326

24-
TODO: Further documentation.
27+
TODO: Add demo here.
28+
29+
# Requirements
30+
31+
This project uses Angular Material tabs so an Angular Material must be installed and available along with a theme. You can define a theme if you use this application outside of Angular using the public API `materialTheme` (see below for more information). See other peer dependancies in the package description.
32+
33+
# Installation
34+
35+
```bash
36+
ng add @proangular/ngx-gist@latest
37+
```
38+
or
39+
```bash
40+
npm install @proangular/ngx-gist --save
41+
```
42+
43+
Import `NgxGistModule` where needed
44+
```diff
45+
...
46+
+ import { NgxGistModule } from '@proangular/ngx-gist';
47+
...
48+
49+
@NgModule({
50+
imports: [
51+
...
52+
+ NgxGistModule
53+
],
54+
...
55+
})
56+
export class AppModule { }
57+
```
58+
59+
# Usage
60+
61+
### Default - fetched gist (auto cached for 24 hours)
62+
63+
ngx-gist will fetch the gist once and store it locally for 24 hours. In that timeframe, if the user returns or visits another page where this gist was previously loaded, it will reload the content without having to reach out to GitHub again.
64+
```html
65+
<ngx-gist gistId="gistId_123abc"></ngx-gist>
66+
```
67+
68+
### Fetched gist (forced no cache)
69+
70+
Force no cache. This will force ngx-gist to retrieve the content live from GitHub every time this content loads. This is disabled by default, but could be useful if your gists change frequently.
71+
```html
72+
<ngx-gist
73+
gistId="gistId_123abc"
74+
[useCache]="false"
75+
></ngx-gist>
76+
```
77+
78+
### Displaying one specific file
79+
80+
Display only one specific file when your gist has many.
81+
```html
82+
<ngx-gist
83+
displayOnlyFileNames="super.js"
84+
gistId="gistId_123abc"
85+
></ngx-gist>
86+
```
87+
88+
### Displaying multiple, specific files
89+
90+
Display only one specific file when your gist has many.
91+
```html
92+
<ngx-gist
93+
[displayOnlyFileNames]="['csstest.css', 'main.ts']"
94+
gistId="gistId_123abc"
95+
></ngx-gist>
96+
```
97+
98+
### Displaying a basic code snippet (without a remote gist)
99+
100+
These are not fetched from GitHub and are brought in elsewhere from your application (seperate HTTP request, or statically for example). With this method you can display code snippets without having to create a remote gist. Also, please notice here that no "Open Gist on GitHub" link is displayed here.
101+
```html
102+
<ngx-gist [gist]="localGistObject"></ngx-gist>
103+
```
104+
105+
### Hiding line numbers
106+
107+
Line numbers are enabled by default, but you can turn them off like so.
108+
```html
109+
<ngx-gist
110+
gistId="d55ea012b585a16a9970878d90106d74"
111+
[showLineNumbers]="false"
112+
></ngx-gist>
113+
```
114+
115+
# Component API
116+
117+
| Input Name | Input Typing | Default Value | Description |
118+
| ------------------------ | ---------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
119+
| **displayOnlyFileNames** | string \| readonly string[] \| undefined | `undefined` | Display in the DOM only the selected filename(s) from the gists files array. Can be either a string or string array. File names much match exactly, be sure to remove any leading or trailing whitespace in the provided strings. |
120+
| **hideGistLink** | bool | `false` | Optionally hide the gist link which opens the gist on GitHub. The gist links automatically dispaly for remote gists, but can be hidden with this feature. |
121+
| **gist** | NgxGist \| undefined | `undefined` | Provide a static gist model here directly which will be displayed if no `gistId` is provided for remote fetching. Also this model will be displayed should a fetch fail when retrieving `gistId`, or overwritten once the pertaining `gistId` data is fetched. |
122+
| **gistId** | string | `undefined` | Provide the GitHub gist id to be fetched and loaded. This can be found in URL of the gists you create. For example the id `TH1515th31DT0C0PY` in: https://gist.github.com/FakeUserName/TH1515th31DT0C0PY. Alternatively, provide a value directly in the sibling input `gist`. |
123+
| **languageName** | string \| undefined | `undefined` | When defined, override automatic language detection [and styling] and treat all gists as this lanuage. See supported language strings here: https://github.com/highlightjs/highlight.js/blob/main/SUPPORTED_LANGUAGES.md |
124+
| **materialTheme** | MaterialPrebuiltTheme \| undefined | `undefined` | Define a material core theme to apply. Ideally, you should already have your global material theme set at the root of your project so try to avoid using this if possible. Note: These are loaded from the CDN: `https://unpkg.com` |
125+
| **showLineNumbers** | bool | `true` | Display or hide the line numbers in your gist code snippets. |
126+
| **useCache** | bool | `true` | Cache the GitHub gist request in local memory for 24 hours. GitHub has a request limit, so this helps in reducing bandwidth. Loads previously fetched gist content from the users machine on refresh and page re-visits. |
127+
128+
# Compatibility
129+
130+
| Angular version | @proangular/ngx-gist | Install |
131+
| --------------- | -------------------------- | ------------------------------------ |
132+
| v14 | v1.x.x | `ng add @proangular/ngx-gist@latest` |
133+
| v13 | v1.x.x | `ng add @proangular/ngx-gist@latest` |
134+
| v12 | v1.x.x | `ng add @proangular/ngx-gist@latest` |
135+
136+
# Development
137+
138+
Please submit all issues, and feature requests here: [https://github.com/ProAngular/ngx-gist/issues](https://github.com/ProAngular/ngx-gist/issues)
139+
140+
Contribution:
141+
142+
1. Clone the repo and create a new branch:
143+
* `git clone https://github.com/ProAngular/ngx-gist.git`
144+
* `git checkout -b username/feature-or-bug-description`
145+
2. Bump up the version of package in `package.json` and `package-lock.json`, commit all changes, push.
146+
* `git add -A`
147+
* `git commit -m "My commit message"`
148+
* `git push origin username/feature-or-bug-description`
149+
3. Submit code in published PR for review and approval. Add a good description and link any possible user stories or bugs.
150+
* [Create a new pull request](https://github.com/ProAngular/ngx-gist/compare).
151+
4. Allow CI actions to completely run and verify files.
152+
5. Add/ping reviewers and await approval.
153+
154+
Thank you for any and all contributions!
155+
156+
# Donation
157+
158+
As a husband and father of four children, your donations mean the world to me! Any donations are greatly appreciated and keep me going!
159+
* [https://www.paypal.me/CodyTolene](https://www.paypal.me/CodyTolene)
160+
* [https://github.com/sponsors/ProAngular](https://github.com/sponsors/ProAngular)
161+
162+
# License
163+
164+
Copyright &copy; 2022 [Cody Tolene](https://www.CodyTolene.com)
165+
166+
All content is licensed under the [MIT license].
167+
168+
[mit license]: LICENSE

Diff for: ‎package-lock.json

+15-2
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

Diff for: ‎package.json

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@proangular/ngx-gist",
3-
"version": "1.0.2",
3+
"version": "1.0.3",
44
"description": "An Angular Material and HighlighJs styled display box for GitHub gist and local code snippets.",
55
"author": "Pro Angular <[email protected]>",
66
"homepage": "https://www.proangular.com",
@@ -32,6 +32,7 @@
3232
"@angular/platform-browser": ">=12 <15",
3333
"@ngneat/until-destroy": "^9.2.1",
3434
"highlight.js": "^11.6.0",
35+
"highlightjs-line-numbers.js": "^2.8.0",
3536
"io-ts": "^2.2.17",
3637
"io-ts-types": "^0.5.16"
3738
},

Diff for: ‎src/app/app.component.ts

+88-11
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { NgxGist } from './public/ngx-gist.model';
12
import { Component } from '@angular/core';
23

34
@Component({
@@ -9,26 +10,102 @@ import { Component } from '@angular/core';
910
<h3 align="center">
1011
Examples of displaying local and GitHub gists and code snippets.
1112
</h3>
12-
<!-- EXAMPLE: FETCH _NEW_ GIST FROM GITHUB (NOT-SAVED) -->
13+
14+
<hr />
15+
16+
<h4>FETCHED GIST (AUTO CACHED FOR 24 HOURS)</h4>
17+
<p>
18+
ngx-gist will fetch the gist once and store it locally for 24 hours. In
19+
that timeframe, if the user returns or visits another page where this
20+
gist was previously loaded, it will reload the content without having to
21+
reach out to GitHub again.
22+
</p>
1323
<ngx-gist gistId="d55ea012b585a16a9970878d90106d74"></ngx-gist>
14-
<!-- EXAMPLE: FETCH _CACHED_ GIST FROM MEMORY (ON SUBSEQUENT REQUESTS) -->
24+
25+
<h4>FETCHED GIST (FORCED NO CACHE)</h4>
26+
<p>
27+
Force no cache. This will force ngx-gist to retrieve the content live
28+
from GitHub every time this content loads. This is disabled by default,
29+
but could be useful if your gists change frequently.
30+
</p>
31+
<ngx-gist
32+
gistId="d55ea012b585a16a9970878d90106d74"
33+
[useCache]="false"
34+
></ngx-gist>
35+
36+
<h4>DISPLAYING ONE SPECIFIC FILE</h4>
37+
<p>Display only one specific file when your gist has many.</p>
1538
<ngx-gist
39+
displayOnlyFileNames="super.js"
1640
gistId="d55ea012b585a16a9970878d90106d74"
17-
[useCache]="true"
1841
></ngx-gist>
19-
<!-- EXAMPLE: DISPLAYING A SPECIFIC FILE -->
42+
43+
<h4>DISPLAYING MULTIPLE, SPECIFIC FILES</h4>
44+
<p>You can also display any number of specific files by name.</p>
2045
<ngx-gist
21-
displayOnlyFileName="super.js"
46+
[displayOnlyFileNames]="['csstest.css', 'main.ts']"
2247
gistId="d55ea012b585a16a9970878d90106d74"
23-
[useCache]="true"
2448
></ngx-gist>
25-
<!-- TODO: SUPPORT LOCAL GIST -->
26-
<!--
49+
50+
<h4>DISPLAYING A BASIC CODE SNIPPET (WITHOUT A REMOTE GIST)</h4>
51+
<p>
52+
These are not fetched from GitHub and are brought in elsewhere from your
53+
application (separate HTTP request, or statically, for example). With
54+
this method, you can display code snippets without having to create a
55+
remote gist. Also, please notice here that no "Open Gist on GitHub" link
56+
is displayed here.
57+
</p>
2758
<ngx-gist [gist]="localGistObject"></ngx-gist>
28-
-->
59+
60+
<h4>HIDING LINE NUMBERS</h4>
61+
<p>
62+
Line numbers are enabled by default, but you can turn them off like so.
63+
</p>
64+
<ngx-gist
65+
gistId="d55ea012b585a16a9970878d90106d74"
66+
[showLineNumbers]="false"
67+
></ngx-gist>
2968
</ngx-body>
3069
<ngx-footer #footer></ngx-footer>
3170
`,
32-
styles: [],
71+
styles: [
72+
`
73+
h2 {
74+
margin-top: 2rem;
75+
}
76+
h3 {
77+
margin-bottom: 3rem;
78+
}
79+
`,
80+
],
3381
})
34-
export class AppComponent {}
82+
export class AppComponent {
83+
public readonly localGistObject = NgxGist.create({
84+
// Required
85+
files: [
86+
{
87+
content: getTimeSnippet,
88+
filename: 'get-time.ts',
89+
},
90+
{
91+
content: printHelloWorldSnippet,
92+
filename: 'print-hello-world.js',
93+
},
94+
],
95+
// Optional
96+
created_at: undefined,
97+
languageOverride: undefined,
98+
});
99+
}
100+
101+
const getTimeSnippet = `
102+
function getTime(): number {
103+
return new Date().getTime();
104+
}
105+
`.trimStart();
106+
107+
const printHelloWorldSnippet = `
108+
function printHelloWorld() {
109+
console.log('Hello world!');
110+
}
111+
`.trimStart();

Diff for: ‎src/app/app.module.ts

+4
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,17 @@ import { NgxGistModule } from './public/ngx-gist.module';
55
import { BodyComponent, FooterComponent, HeaderComponent } from './layout';
66
import { HttpClientModule } from '@angular/common/http';
77
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
8+
import { MatToolbarModule } from '@angular/material/toolbar';
9+
import { MatButtonModule } from '@angular/material/button';
810

911
@NgModule({
1012
declarations: [AppComponent, BodyComponent, FooterComponent, HeaderComponent],
1113
imports: [
1214
BrowserAnimationsModule,
1315
BrowserModule,
1416
HttpClientModule,
17+
MatButtonModule,
18+
MatToolbarModule,
1519
NgxGistModule,
1620
],
1721
providers: [],

Diff for: ‎src/app/layout/body.component.ts

+1
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import { Component } from '@angular/core';
1212
section {
1313
padding: 1rem;
1414
min-height: 90vh;
15+
margin-top: 64px;
1516
}
1617
`,
1718
],

0 commit comments

Comments
 (0)