@ngx-prism/core

Simple Angular 4+ Prism highlighter module. Click to get package with rxjs on board.
Next update will be available only on @angular-package with name @angular-package/prism/core.

Demonstration
Installation
Usage
Inputs
Lifecycle Hooks
Change detection
Scripts
Git
- Commit
- Versioning
License
Donate

Pros(+)

AOT (Ahead Of Time Compilation) package: faster rendering, fewer asynchronous requests, smaller Angular framework download size, detect template errors earlier, better security.
MIT License: it can be used commercially.
Component changeDetectionStrategy is set to OnPush, It gives better overall performance.
[New] Change detector status is initially Detached and detectChanges() is used in every component property declared in its own property __properties. This is because of using @angular-package/change-detection.
Setters instead of ngOnChanges() method to detect changes.
Dynamically changes highlight string with code input property, and dynamically changes properties for change detection by setting them true or false with input cd.
It uses prismjs highlightElement(element, async, callback) to higlight, so async and hooks internal prism features can be used.
Interpolates string to highlight with interpolation object.
Performs highlight depending on whether property change detection is active or is not (by checking cd property).
Live @angular/cli usage demonstration and inside repository.
No known vulnerabilities found by snyk.io.

Cons(-)

Hooks are defined globally.
You cannot use both ng-content and property code the same time.
Need to provide new instance of objects to get them changed.

Important!

By default all properties are sensitive to detection.
Instead of using ngOnChanges angular cycle hook, now, it base only on setters and getters.
It is designed to use ng-content and property code separately. You should NOT use both the same time.
In @angular/cli add --aot to ng serve in scripts to have script "start": "ng serve --aot".
Selector prism-highlight is changed to ngx-prism.

Demonstration

Live demonstration

Clone this repository:

git clone https://github.com/ngx-prism/core.git

Go to demo folder and with your command line write the following:

npm i && npm start

Open http://localhost:4200/ in your browser.

Example demonstration usage of both core and rxjs is in https://github.com/ngx-prism/demo repository. To install it, do the following:

git clone https://github.com/ngx-prism/demo.git
cd demo
npm i && npm start

Open http://localhost:4200/ in your browser.

Installation

First, install @ngx-prism/core package with command:

npm i --save @ngx-prism/core

Add peer dependencies:

npm i --save @types/prismjs@1.9.0 prismjs@1.9.0

Usage

Now, import PrismModule into your module:

// example.module.ts
import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';

import { PrismModule } from '@ngx-prism/core'; // <----- Here
import { ExampleComponent } from './example.component'; // your component

@NgModule({
  declarations: [ ExampleComponent ],
  imports: [
    CommonModule,
    PrismModule // <----- Here
  ],
  exports: [ ExampleComponent ]
})
export class ExampleModule { }

Use <ngx-prism></ngx-prism> tag with content inside and specify its content with property [language] to highlight it:

// example.component.ts
import { Component } from '@angular/core';

@Component({
  selector: 'example-component',
  template: `
    <ngx-prism [language]="language">
      {{content}}
    </ngx-prism>
  `
})
export class ExampleComponent {
  language = 'html';
  content = '<p>test</p>';
  constructor() { }
}

or use <ngx-prism></ngx-prism> tag with [code] and [interpolation] attribute like in ExampleComponent below:

// example.component.ts
import { Component } from '@angular/core';

@Component({
  selector: 'example-component',
  template: `
    <ngx-prism
      [language] = "language"
      [hooks] = "hooks"
      [code] = "content"
      [interpolation] = "interpolate"
    ></ngx-prism>`
})
export class ExampleComponent {
  content = '<p>test {{language}}</p>';
  hooks = {
    'before-sanity-check': (env) => { console.log(`before-sanity-check`, env); },
    'before-highlight': (env) => { console.log(`before-highlight`, env); },
    'after-highlight': (env) => { console.log(`after-highlight`, env); },
    'complete': (env) => { console.log(`complete`, env); },
    'before-insert': (env) => { console.log(`before-insert`, env); }
  };
  interpolate = {
    language: 'language interpolated'
  };
  language = 'html';
  constructor() { }
}

It is possible to import themes files in @angular/cli:

@import '~prismjs/themes/prism-coy.css';
@import '~prismjs/themes/prism-dark.css';
@import '~prismjs/themes/prism-funky.css';
@import '~prismjs/themes/prism-okaidia.css';
@import '~prismjs/themes/prism-solarizedlight.css';
@import '~prismjs/themes/prism-tomorrow.css';
@import '~prismjs/themes/prism-twilight.css';
@import '~prismjs/themes/prism.css';

Inputs

name	Type	Description
async	boolean	"Whether to use Web Workers to improve performance and avoid blocking the UI when highlighting very large chunks of code." - prismjs
callback	(element: Element) => void \| undefined = undefined	"An optional callback to be invoked after the highlighting is done. Mostly useful when async is true, since in that case, the highlighting is done asynchronously." - prismjs
cd (ChangeDetection)	PropertiesInterface {[index:string]:boolean}	Properties provided with `index` as name and value `true` will be sensitive for changes.
code	string	"A string with the code to be highlighted." - prismjs
hooks	Object	Callback with specific execute time and name: `before-sanity-check`, `before-highlight`, `after-highlight`, `complete`, `before-insert`.
interpolation	Object \| undefined	Data property values to inject.
language	string	"Valid language identifier, for example 'javascript', 'css'." - prismjs

Lifecycle Hooks

Angular Lifecycle Hooks

PrismComponent

ngAfterViewInit():

Sets property ready to true which by default is false.
Property ready is used in highlightElement(result: { code: string, language: string }): void method to performs when ready is set to true - prismService.highlight() method to highlight code.

ngAfterContentInit():

Update __properties for change detection with inputted property cd.

Change detection

Angular source

Component changeDetectionStrategy is set to OnPush means that the change detector's mode will be initially set to CheckOnce, and status CheckOnce means that after calling detectChanges the status of the change detector will become Checked. Status Checked means that the change detector should be skipped until its mode changes to CheckOnce.

Change detector status is now manually set to Detached by default and it means that its sub tree is not a part of the main tree and should be skipped. However it will call detectChanges() in Setters with indicated properties.

Scripts

Clone repository:

git clone https://github.com/ngx-prism/core.git

Go to just created folder:

cd core

To build a clean package, means before that script removes node_modules, dist folder and install dependencies:

npm run clean:start

To build a package:

npm start

To run karma tests:

npm test

GIT

Commit

Versioning

Semantic Versioning 2.0.0

Given a version number MAJOR.MINOR.PATCH, increment the:
MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

FAQ How should I deal with revisions in the 0.y.z initial development phase?

The simplest thing to do is start your initial development release at 0.1.0 and then increment the minor version for each subsequent release.

How do I know when to release 1.0.0?

If your software is being used in production, it should probably already be 1.0.0. If you have a stable API on which users have come to depend, you should be 1.0.0. If you’re worrying a lot about backwards compatibility, you should probably already be 1.0.0.

License

Donate

Click to donate

echonax/core