marcscheib/aurelia-syntax-highlighter

Aurelia plugin highlighting syntax based on PrismJS

aurelia-syntax-highlighter

aurelia-syntax-highlighter is a custom attribute for Aurelia to highlight code blocks using PrismJS.

Documentation

Installation

The plugin installation happens via JSPM. Go to your project and verify npm (npm install) and jspm (jspm install) installation was already executed.

Now, you can install the syntax highlighter plugin via the following command:

jspm install aurelia-syntax-highlighter

The command will add the plugin source code to your jspm_packages directory as well as a mapping into your config.js which looks similar to the following:

"aurelia-syntax-highlighter": "github:MarcScheib/[email protected]"

You can also add a specific branch to your application if you are looking for technical previews by executing the following command:

jspm install aurelia-syntax-highlighter=github:MarcScheib/aurelia-syntax-highlighter@master

This will add the current master branch instead of the latest tagged version.

Plugin Configuration in your Application

During the bootstrapping of the Aurelia Framework, you can include the syntax highlighter plugin by simply adding it to the list of loaded plugins:

export function configure(aurelia) {
  aurelia.use
    .standardConfiguration()
    .developmentLogging()
    ...
    .plugin('aurelia-syntax-highlighter'); // Add this line to load the plugin

  aurelia.start().then(a => a.setRoot('app', document.body));
}

In addition, you need to include a CSS file for syntax highlighting. You can go with your own one or use provided ones by Prism. E.g., include the following line in your index.html:

<link rel="stylesheet" href="jspm_packages/github/PrismJS/[email protected]/themes/prism.css">

Usage

You can now use the plugin to highlight your syntax. Simply add the au-syntax attribute to your <code>, e.g.:

<pre><code class="language-css" au-syntax>
.splash {
  text-align: center;
  margin: 10% 0 0 0;
  box-sizing: border-box;
}</code></pre>

It is also possible to bind dynamic values to the custom attribute, e.g. to the input of a textarea:

<pre><code class="language-css" au-syntax.bind="code"></code></pre>

This automatically updates the content of <code> to highlighted syntax of the value of code binding.

Dependencies

Aurelia dependencies:

• aurelia-pal
• aurelia-templating

External dependencies:

• Prism

Used By

This library is an optional plugin and can be used by any framework.

Platform Support

This library can be used in the browser.

Building The Code

To build the code, follow these steps.

1. Ensure that NodeJS is installed. This provides the platform on which the build tooling runs.
2. From the project folder, execute the following command:

npm install

3. Ensure that Gulp is installed. If you need to install it, use the following command:

npm install -g gulp

4. To build the code, you can now run:

gulp build

5. You will find the compiled code in the dist folder, available in three module formats: AMD, CommonJS and ES6.

6. See gulpfile.js for other tasks related to generating the docs and linting.

Running The Tests

To run the unit tests, first ensure that you have followed the steps above in order to install all dependencies and successfully build the library. Once you have done that, proceed with these additional steps:

1. Ensure that the Karma CLI is installed. If you need to install it, use the following command:

npm install -g karma-cli

2. Ensure that jspm is installed. If you need to install it, use the following commnand:

npm install -g jspm

3. Install the client-side dependencies with jspm:

jspm install

4. Ensure that you have Chrome installed. Karma runs the test suite in Chrome.

5. You can now run the tests with this command:

karma start

Running The Sample

To run the sample code using this plugin proceed with these additional steps:

1. Go to the sample directory and install dependencies using jspm:

cd sample
jspm install

2. Go back to the root of the project and use gulp to serve the sample project:

cd ..
gulp watch

aurelia-syntax-highlighter's Issues

Dynamic binding

I'm submitting a ... (check one with "x")

[x] bug report => search github for a similar issue or PR before submitting
[ ] feature request

Current behavior

I have a simple setup like this:

<textarea value.bind="test"></textarea>
<pre>${test}</pre>
<pre class="language-javascript" au-syntax>${test}</pre>
<pre class="language-javascript" au-syntax textcontent.bind="test"></pre>

class MyClass {
  test = '{"a": true}';
}

At first when the page loads, I observe that:

• The first pre shows the correct content with no formatting (OK)
• The second pre shows the correct content with proper formatting (OK)
• The third pre shows the correct content with proper formatting (OK)

When I change the content of the textarea, I observe that:

• The first pre updates its content as expected, no formatting is applied (OK)
• The second pre DOES NOT update its content (NOT OK) but preserves formatting (OK)
• The third pre updates its content as expected (OK) but loses formatting (NOT OK)

Expected behavior
When I change the content of the textarea, I observe that:

• The second pre updates its content as expected and preserves formatting
• The third pre updates its content as expected and preserves formatting