angular-exemplify

Angular Exemplify

A simple angular component for adding code examples based on actual code and markup! Just add <exemplify></exemplify> together with [selector]="'html selector'" and/or [sources]="sourceList" to your code and you're done:D

View example

Dependencies

• Prism - for highlighting
• Bootstrap - for basic styling (optional)
• Raw-loader - a loader for webpack that allows importing files as a String (optional)

Please note that you don't have to use bootstrap and/or raw-loader with angular exemplify although it's recommended.

Installation and usage

Install with:

npm install angular-exemplify --save

If you want to use together with bootstrap 4

Run:

npm install bootstrap --save

Usage in angular-cli project

Please note the instructions below are for projects based on angular-cli, you might need to set up things differently if you're using something else.

Include scripts and styles in build

If you want to use angular exemplify together with prism, make sure to add the prism script and the prism-exemplify.css or one of the prism theme css files to your .angular-cli.json config, bootstrap.css is optional but if you're not using bootstrap you should include exemplify.css to get the basic styling at least:

"styles": [
  "../node_modules/bootstrap/dist/css/bootstrap.css",
  "../node_modules/angular-exemplify/css/prism-exemplify.css",
  "../node_modules/angular-exemplify/css/exemplify.css", // <-- only add this line if you're not using bootstrap
  "styles.css"
],
"scripts": [
  "../node_modules/prismjs/prism.js"
],

If you're using sass, you could also import the corresponding sass files like this instead of adding the css files:

@import "~angular-exemplify/scss/prism-exemplify";
@import "~angular-exemplify/scss/exemplify"; // <-- only add this line if you're not using bootstrap
@import "~bootstrap/scss/bootstrap";

Import ExemplifyModule

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { AppComponent } from './app.component';
import { ExemplifyModule } from "angular-exemplify";

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    FormsModule,
    ExemplifyModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Basic usage

Add <exemplify [selector]="'.btn.btn-primary'"></exemplify> below your element like this:

<button class="btn btn-primary" (click)="doSomething()">Action</button>
<exemplify [selector]="'.btn.btn-primary'"></exemplify>

Where selector could be a any html selector.

View demo for live preview and more examples.

Options

Attribute	Type	Usage/description	Default
show	boolean	should the example be shown or hidden by default	false
sources	array	an array of objects specifying sources
escapeStrings	array	an array with strings that should be escaped (necessary for attribute strings that are written using camel case i.e. inputs, template variables etc.), see issue #1 for more info.
texts	object	override default texts by passing an object containing one or more of the following properties: sourceNotFound, markup, show, hide, copy, copySuccess, copyError

Using external sources

To keep the examples in sync with your code you should reference the source files. Here's an example based on a app published and deployed to github pages.

sources = [{
    "name":"app.module.ts",
    "src":"https://raw.githubusercontent.com/hjalmers/angular-markup-example/master/src/app/app.module.ts"
  },{
    "name":"app.component.ts",
    "src":"https://raw.githubusercontent.com/hjalmers/angular-markup-example/master/src/app/app.component.ts"
  },{
    "name":"app.component.css",
    "src":"https://raw.githubusercontent.com/hjalmers/angular-markup-example/master/src/app/app.component.css",
    "lang":"css"
  }]

If you want to use raw-loader to load project files

Install with:

npm install raw-loader --save-dev`

Then you need to add the following typings to your typings.d.ts file.

declare module '!raw-loader!*' {
    const contents: string;
    export = contents;
}

To avoid errors related to require when using raw-loader like this:

sorces = [{
    name: 'app.component.ts',
    src: require('!raw-loader!app/app.component.ts'),
    lang: 'markup'
  }]

Install types for node:

npm install @types/node --save-dev

And add node to your types in tsconfig.app.json`

{
  "compilerOptions": {
    ...
    "types": [
      "node" <-- Add this
    ]
  }
}