diff --git a/README.md b/README.md index f6e059d..019a1cc 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ # Guitar Diagrams JS -[![GitHub Release](https://img.shields.io/github/v/release/KCarlile/guitar-diagrams-js?include_prereleases&logo=github&label=Latest%20version)](https://github.com/KCarlile/guitar-diagrams-js/releases) [![GitHub Actions Workflow Status](https://github.com/KCarlile/guitar-diagrams-js/actions/workflows/release-package.yml/badge.svg)](https://github.com/KCarlile/guitar-diagrams-js/actions/workflows/release-package.yml) [![Super-Linter](https://github.com/KCarlile/guitar-diagrams-js/actions/workflows/linting.yml/badge.svg)](https://github.com/marketplace/actions/super-linter) @@ -17,7 +16,7 @@ _Guitar Diagrams JS_ is an open source JavaScript library for drawing guitar chords and scales on an HTML5 canvas. Project: \ -Version: 0.9.2 +Version: [![GitHub Release](https://img.shields.io/github/v/release/KCarlile/guitar-diagrams-js?include_prereleases&logo=github&label=Latest%20version)](https://github.com/KCarlile/guitar-diagrams-js/releases) ### Why should you use Guitar Diagrams JS? @@ -27,12 +26,14 @@ The benefit of Guitar Diagrams JS is that it provides a visual representation of Here are some other comparisons to Guitar Diagrams JS: -| Name | Description | Visual | Graphical | Instrument Representation | No Sheet Music | Cost | -| ---- | ----------- | ------ | --------- | ------------------------- | -------------- | ---- | -| Guitar Diagrams JS | Create diagrams with minimal code and no graphics | ✅ | ✅ | ✅ | ✅ | $0 | -| Tablature (tabs) | Create diagrams manually with text | ✅ | ✅ | ⚠️ | ✅ | $0 | -| Graphic Design Software | Create diagrams manually with a graphic design program | ✅ | ✅ | ⚠️ | ✅ | [\$22.99/month](https://www.adobe.com/products/photoshop/plans.html) | -| Sheet Music | Create sheet music | ✅ | ❌ | ❌ | ❌ | [\$99](https://www.finalemusic.com/products/finale/special-pricing/) or [\$27.99/month](https://www.avid.com/sibelius/sibelius-ultimate-subscriptions?usertype=individual) | +| Name | Description | Visual | Graphical | Instrument Representation | No Sheet Music Reading | Works with Musical Passages | Cost | +| ---- | ----------- | ------ | --------- | ------------------------- | -------------- | ---------------- | ---- | +| Guitar Diagrams JS | Create diagrams with minimal code and no graphics | ✅ | ✅ | ✅ | ✅ | ❌ | $0 | +| Tablature (tabs) | Create diagrams manually with text | ✅ | ✅ | ⚠️ | ✅ | ✅ | $0, but time consuming and error prone | +| Graphic Design Software | Create diagrams manually with a graphic design program | ✅ | ✅ | ⚠️ | ✅ | ❌ | [\$22.99/month](https://www.adobe.com/products/photoshop/plans.html), and very time consuming | +| Sheet Music | Create sheet music | ✅ | ❌ | ❌ | ❌ | ✅ | [\$99](https://www.finalemusic.com/products/finale/special-pricing/) or [\$27.99/month](https://www.avid.com/sibelius/sibelius-ultimate-subscriptions?usertype=individual), and requires music notation proficiency | + +Key: ✅Yes. ⚠️Maybe, sorta, kinda, optional. ❌ No. ## Project Lead/Owner and Contributors @@ -54,6 +55,8 @@ GitHub profile: [@KCarlile](https://github.com/KCarlile) Please see the following pages for more information: - [`README.md`](README.md): this page +- [`docs/index.md`](docs/index.md): general usage documentation +- [`docs/api-docs.md`](docs/api-docs.md): API usage documentation - [`docs/index.md`](docs/index.md): main landing page for project documentation - [`docs/api-docs.md`](docs/api-docs.md): API usage documentation - [`docs/code-owner-docs.md`](docs/code-owner-docs.md): technical documentation for code owners @@ -68,80 +71,11 @@ See the repository's [Releases page](https://github.com/KCarlile/guitar-diagrams ## Technical Information for Site Builders -### Usage in Your Project - -#### Option 1: Installation as a Node Dependency - -For full details, see the Node JS packages released by this project here: - -You can install Guitar Diagrams JS in your project as a Node JS dependency via NPM. Run the following command from your project's directory: - -```bash -npm install @kcarlile/guitar-diagrams-js@0.9.2 -``` - -Or, alternately, you can manually edit your `package.json` file and add the following entry: - -```json -"@kcarlile/guitar-diagrams-js": "0.9.2", -``` - -#### Option 2: Manual Installation via CDN - -If you want to use a CDN-hosted package (e.g., Guitar Diagrams JS on JSDelivr at `https://cdn.jsdelivr.net/gh/KCarlile/guitar-diagrams-js@main/guitar-diagrams.js`), you can reference it in your code like this: - -```html -
- -``` - -Be sure to add some target HTML element to your page with a matching ID (`gdj1.addCanvas('diagram-1');` where `diagram-1` is the ID) in your JS code so Guitar Diagrams JS knows where to add your drawing: - -```html -
-``` - -#### Option 3: Manual Installation via Local Copies - -You can also install this package manually by downloading it, placing the files in the correct location, and modifying your site's code to reference the library. The following steps outline this process: - -1. Download the repository files from the [GitHub repository for Guitar Diagrams JS](https://github.com/KCarlile/guitar-diagrams-js). -1. The only files about which you should be concerned are the following: - - `guitar-diagrams.js`: main functionality - - `guitar-diagrams-config.js`: config object - - `guitar-diagrams-marker.js`: marker object -1. Place those files in your application at `wherever/you/put/your/js/files/guitar-diagram-js/`. -1. In the JS file with your primary entrypoint, add an import statement: - - ```javascript - import { GuitarDiagramsJS } from 'wherever/you/put/your/js/files/guitar-diagrams-js/guitar-diagrams.js'; - ``` - -1. Following that import statement, begin to reference the library: - - ```javascript - let gdj1 = new GuitarDiagramsJS(); - gdj1.config.canvasID = 'diagram-1-canvas'; // specify the canvas element's an ID - gdj1.addCanvas('diagram-1'); // add the canvas to the specified element ID on the page - gdj1.drawNeck(); // draw the fretboard - ``` - -1. Be sure to add some target HTML element to your page with a matching ID (`gdj1.addCanvas('diagram-1');` where `diagram-1` is the ID) in your JS code so Guitar Diagrams JS knows where to add your drawing: - - ```html -
- ``` +You can find the full usage documentation at [`docs/index.md`](docs/index.md) and the API documentation at [`docs/api-docs.md`](docs/api-docs.md). The following information is just a high-level overview of how to use Guitar Diagrams JS. ### More Information -For more information, please see the [`docs/index.md`](docs/index.md) and ['docs/examples/index.html`](docs/examples/index.html) pages for API documentation and examples. +For more information, please see the [`docs/index.md`](docs/index.md) and [`docs/api-docs.md`](docs/api-docs.md) pages for general usage help and API documentation. See also the [`docs/examples/index.html`](docs/examples/index.html) page for usage examples. ## Technical Information for Code Owners @@ -151,7 +85,7 @@ See [`docs/code-owners.md`](docs/code-owners.md) for documentation related to de There are no specific requirements[1](#footnotes) for dependencies to use Guitar Diagrams JS other than the standard browser compatibility considerations with CSS, JavaScript, and HTML 5's `` tag. Browser compatibility for the `` tag can be found on [the MDN `` page](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas#browser_compatibility). ----- +--- ## References diff --git a/docs/api-docs.md b/docs/api-docs.md new file mode 100644 index 0000000..b99c021 --- /dev/null +++ b/docs/api-docs.md @@ -0,0 +1,639 @@ +# API Documentation + +Lorem ipsum...some description, if necessary, for the API usage section. + +## Table of Contents + +- [API Documentation](#api-documentation) + - [Table of Contents](#table-of-contents) + - [`guitar-diagrams.js` Class](#guitar-diagramsjs-class) + - [`guitar-diagrams.js` Constructors (non-default)](#guitar-diagramsjs-constructors-non-default) + - [`guitar-diagrams.js` Static Public Members](#guitar-diagramsjs-static-public-members) + - [`guitar-diagrams.js` Public Properties](#guitar-diagramsjs-public-properties) + - [`guitar-diagrams.js` Public Methods](#guitar-diagramsjs-public-methods) + - [`guitar-diagrams-config.js` Class](#guitar-diagrams-configjs-class) + - [`guitar-diagrams-config.js` Constructors (non-default)](#guitar-diagrams-configjs-constructors-non-default) + - [`guitar-diagrams-config.js` Public Properties](#guitar-diagrams-configjs-public-properties) + - [canvasID (get)](#canvasid-get) + - [canvasID (set)](#canvasid-set) + - [colorFretboard (get)](#colorfretboard-get) + - [colorFretboard (set)](#colorfretboard-set) + - [colorNut (get)](#colornut-get) + - [colorNut (set)](#colornut-set) + - [colorNutOutline (get)](#colornutoutline-get) + - [colorNutOutline (set)](#colornutoutline-set) + - [colorFrets (get)](#colorfrets-get) + - [colorFrets (set)](#colorfrets-set) + - [colorStrings (get)](#colorstrings-get) + - [colorStrings (set)](#colorstrings-set) + - [colorFretMarker (get)](#colorfretmarker-get) + - [colorFretMarker (set)](#colorfretmarker-set) + - [colorDiagramBackground (get)](#colordiagrambackground-get) + - [colorDiagramBackground (set)](#colordiagrambackground-set) + - [colorLabel (get)](#colorlabel-get) + - [colorLabel (set)](#colorlabel-set) + - [markerStrokeWidth (get)](#markerstrokewidth-get) + - [markerStrokeWidth (set)](#markerstrokewidth-set) + - [markerFontSize (get)](#markerfontsize-get) + - [markerFontSize (set)](#markerfontsize-set) + - [fretCount (get)](#fretcount-get) + - [fretCount (set)](#fretcount-set) + - [scaleFactor (get)](#scalefactor-get) + - [scaleFactor (set)](#scalefactor-set) + - [orientHorizontally (get)](#orienthorizontally-get) + - [orientHorizontally (set)](#orienthorizontally-set) + - [fretMarkerEnabled (get)](#fretmarkerenabled-get) + - [fretMarkerEnabled (set)](#fretmarkerenabled-set) + - [fretStartingNumber (get)](#fretstartingnumber-get) + - [fretStartingNumber (set)](#fretstartingnumber-set) + - [stringNamesEnabled (get)](#stringnamesenabled-get) + - [stringNamesEnabled (set)](#stringnamesenabled-set) + - [stringNames (get)](#stringnames-get) + - [stringNames (set)](#stringnames-set) + - [downloadImageEnabled (get)](#downloadimageenabled-get) + - [downloadImageEnabled (set)](#downloadimageenabled-set) + - [`guitar-diagrams-config.js` Public Methods](#guitar-diagrams-configjs-public-methods) + - [`guitar-diagrams-marker.js` Class](#guitar-diagrams-markerjs-class) + - [`guitar-diagrams-marker.js` Constructors (non-default)](#guitar-diagrams-markerjs-constructors-non-default) + - [`guitar-diagrams-marker.js` Public Properties](#guitar-diagrams-markerjs-public-properties) + - [`guitar-diagrams-marker.js` Public Methods](#guitar-diagrams-markerjs-public-methods) + +--- + +## `guitar-diagrams.js` Class + +### `guitar-diagrams.js` Constructors (non-default) + +Constructor(s) in `guitar-diagrams.js` go here... or _None._ + +### `guitar-diagrams.js` Static Public Members + +Static members in `guitar-diagrams.js` go here... (We might need to talk about how to handled these.) + +### `guitar-diagrams.js` Public Properties + +Properties in `guitar-diagrams.js` go here... + +### `guitar-diagrams.js` Public Methods + +Methods in `guitar-diagrams.js` go here... + +## `guitar-diagrams-config.js` Class + +### `guitar-diagrams-config.js` Constructors (non-default) + +Constructor(s) in `guitar-diagrams-config.js` go here... + +### `guitar-diagrams-config.js` Public Properties + +Properties in `guitar-diagrams-config.js` go here... + +#### canvasID (get) + +Exists as a property of the config property on the GuitarDiagrams object. Sets the ID attribute of the canvas HTML element. + +- **Parameters**: _None_ +- **Return Value**: {string} The ID attribute of the canvas HTML element. +- **Default Value**: {string} 'gdjCanvas' + +_Example:_ + +```javascript +console.log('Canvas ID: ' + gdj1.config.canvasID); +``` + +#### canvasID (set) + +Exists as a property of the config property on the GuitarDiagrams object. Sets the ID attribute of the canvas HTML element. + +- **Parameters**: {string} The ID attribute of the canvas HTML element. +- **Return Value**: _None_ +- **Default Value**: {string} 'gdjCanvas' + +_Example:_ + +```javascript +gdj1.config.canvasID = 'diagram-1-canvas'; +``` + +#### colorFretboard (get) + +Exists as a property of the config property on the GuitarDiagrams object. Gets the HTML color code of the fretboard. + +- **Parameters**: _None_ +- **Return Value**: {string} The HTML color code of the fretboard. +- **Default Value**: {string} '#795548' + +_Example:_ + +```javascript +console.log('Fretboard color: ' + gdj5.config.colorFretboard); +``` + +#### colorFretboard (set) + +Exists as a property of the config property on the GuitarDiagrams object. Sets the HTML color code of the fretboard. + +- **Parameters**: {string} The HTML color code of the fretboard. +- **Return Value**: _None_ +- **Default Value**: {string} '#795548' + +_Example:_ + +```javascript +gdj1.config.colorFretboard = '#FFE0B2'; +``` + +#### colorNut (get) + +Exists as a property of the config property on the GuitarDiagrams object. Gets the HTML color code of the nut. + +- **Parameters**: _None_ +- **Return Value**: {string} The HTML color code of the nut. +- **Default Value**: {string} '#F2F3F4' + +_Example:_ + +```javascript +console.log(gdj1.config.colorNut); +``` + +#### colorNut (set) + +Exists as a property of the config property on the GuitarDiagrams object. Sets the HTML color code of the nut. + +- **Parameters**: {string} The HTML color code of the nut. +- **Return Value**: _None_ +- **Default Value**: {string} '#F2F3F4' + +_Example:_ + +```javascript +gdj1.config.colorNut = '#FFFFFF'; +``` + +#### colorNutOutline (get) + +Exists as a property of the config property on the GuitarDiagrams object. Gets the HTML color code of the nut outline. + +- **Parameters**: _None_ +- **Return Value**: {string} The HTML color code of the nut outline. +- **Default Value**: {string} '#000000' + +_Example:_ + +```javascript +console.log(gdj1.config.colorNutOutline); +``` + +#### colorNutOutline (set) + +Exists as a property of the config property on the GuitarDiagrams object. Sets the HTML color code of the nut outline. + +- **Parameters**: {string} The HTML color code of the nut outline. +- **Return Value**: _None_ +- **Default Value**: {string} '#000000' + +_Example:_ + +```javascript +gdj1.config.colorNutOutline = '#7E5109'; +``` + +#### colorFrets (get) + +Exists as a property of the config property on the GuitarDiagrams object. Gets the HTML color code of the frets. + +- **Parameters**: _None_ +- **Return Value**: {string} The HTML color code of the frets. +- **Default Value**: {string} '#808B96' + +_Example:_ + +```javascript +console.log(gdj1.config.colorFrets); +``` + +#### colorFrets (set) + +Exists as a property of the config property on the GuitarDiagrams object. Sets the HTML color code of the frets. + +- **Parameters**: {string} The HTML color code of the nut outline. +- **Return Value**: _None_ +- **Default Value**: {string} '#808B96' + +_Example:_ + +```javascript +gdj1.config.colorFrets = '#AEB6BF'; +``` + +#### colorStrings (get) + +Exists as a property of the config property on the GuitarDiagrams object. Gets the HTML color code of the strings. + +- **Parameters**: _None_ +- **Return Value**: {string} The HTML color code of the strings. +- **Default Value**: {string} '#CFD8DC' + +_Example:_ + +```javascript +console.log(gdj1.config.colorStrings); +``` + +#### colorStrings (set) + +Exists as a property of the config property on the GuitarDiagrams object. Sets the HTML color code of the strings. + +- **Parameters**: {string} The HTML color code of the strings. +- **Return Value**: _None_ +- **Default Value**: {string} '#CFD8DC' + +_Example:_ + +```javascript +gdj1.config.colorStrings = '#566573'; +``` + +#### colorFretMarker (get) + +Exists as a property of the config property on the GuitarDiagrams object. Gets the HTML color code of the fret markers. + +- **Parameters**: _None_ +- **Return Value**: {string} The HTML color code of the fret markers. +- **Default Value**: {string} '#FFFFFF' + +_Example:_ + +```javascript +console.log(gdj1.config.colorFretMarker); +``` + +#### colorFretMarker (set) + +Exists as a property of the config property on the GuitarDiagrams object. Sets the HTML color code of the fret markers. + +- **Parameters**: {string} The HTML color code of the fret markers. +- **Return Value**: _None_ +- **Default Value**: {string} '#FFFFFF' + +_Example:_ + +```javascript +gdj1.config.colorFretMarker = '#424949'; +``` + +#### colorDiagramBackground (get) + +Exists as a property of the config property on the GuitarDiagrams object. Gets the HTML color code of the diagram background. + +- **Parameters**: _None_ +- **Return Value**: {string} The HTML color code of the diagram background. +- **Default Value**: {string} null + +_Example:_ + +```javascript +console.log(gdj1.config.colorDiagramBackground); +``` + +#### colorDiagramBackground (set) + +Exists as a property of the config property on the GuitarDiagrams object. Sets the HTML color code of the diagram background. + +- **Parameters**: {string} The HTML color code of the diagram background. +- **Return Value**: _None_ +- **Default Value**: {string} null + +_Example:_ + +```javascript +gdj1.config.colorDiagramBackground = '#000000'; +``` + +#### colorLabel (get) + +Exists as a property of the config property on the GuitarDiagrams object. Gets HTML color code of the label text for string names and fret number. + +- **Parameters**: _None_ +- **Return Value**: {string} The HTML color code of the label text for string names and fret number. +- **Default Value**: {string} '#000000' + +_Example:_ + +```javascript +console.log(gdj1.config.colorLabel); +``` + +#### colorLabel (set) + +Exists as a property of the config property on the GuitarDiagrams object. Sets HTML color code of the label text for string names and fret number. + +- **Parameters**: {string} The HTML color code of the label text for string names and fret number. +- **Return Value**: _None_ +- **Default Value**: {string} '#000000' + +_Example:_ + +```javascript +gdj1.config.colorLabel = '#000000'; +``` + +#### markerStrokeWidth (get) + +Exists as a property of the config property on the GuitarDiagrams object. Gets the marker's stroke width. + +- **Parameters**: _None_ +- **Return Value**: {number} The marker's stroke width. +- **Default Value**: {number} 2 + +_Example:_ + +```javascript +console.log(gdj1.markerStrokeWidth); +``` + +#### markerStrokeWidth (set) + +Exists as a property of the config property on the GuitarDiagrams object. Sets the marker's stroke width. + +- **Parameters**: {number} The marker's stroke width. +- **Return Value**: _None_ +- **Default Value**: {number} 2 + +_Example:_ + +```javascript +gdj1.config.markerStrokeWidth = 1; +``` + +#### markerFontSize (get) + +Exists as a property of the config property on the GuitarDiagrams object. Gets the marker's font size. + +- **Parameters**: _None_ +- **Return Value**: {number} The marker's font size. +- **Default Value**: {number} 16 + +_Example:_ + +```javascript +console.log(gdj1.config.markerFontSize); +``` + +#### markerFontSize (set) + +Exists as a property of the config property on the GuitarDiagrams object. Sets the marker's font size. + +- **Parameters**: {number} The marker's font size. +- **Return Value**: _None_ +- **Default Value**: {number} 16 + +_Example:_ + +```javascript +gdj1.config.markerFontSize = 10; +``` + +#### fretCount (get) + +Exists as a property of the config property on the GuitarDiagrams object. Gets the number of frets on the diagram. + +- **Parameters**: _None_ +- **Return Value**: {number} The number of frets on the diagram. +- **Default Value**: {number} 5 + +_Example:_ + +```javascript +console.log(gdj1.config.fretCount); +``` + +#### fretCount (set) + +Exists as a property of the config property on the GuitarDiagrams object. Sets the number of frets on the diagram. + +- **Parameters**: {number} The number of frets on the diagram. +- **Return Value**: _None_ +- **Default Value**: {number} 5 + +_Example:_ + +```javascript +gdj1.config.fretCount = 3; +``` + +#### scaleFactor (get) + +Exists as a property of the config property on the GuitarDiagrams object. Gets the scale factor of the diagram. + +- **Parameters**: _None_ +- **Return Value**: {number} The scale factor of the diagram. +- **Default Value**: {number} 1 + +_Example:_ + +```javascript +console.log(gdj1.config.scaleFactor); +``` + +#### scaleFactor (set) + +Exists as a property of the config property on the GuitarDiagrams object. Sets the scale factor of the diagram. + +- **Parameters**: {number} The scale factor of the diagram. +- **Return Value**: _None_ +- **Default Value**: {number} 1 + +_Example:_ + +```javascript +gdj1.config.scaleFactor = .6; +``` + +#### orientHorizontally (get) + +Exists as a property of the config property on the GuitarDiagrams object. Gets the horizontal status of the diagram. + +- **Parameters**: _None_ +- **Return Value**: {boolean} The horizontal status of diagram. +- **Default Value**: {boolean} false; + +_Example:_ + +```javascript +console.log(gdj1.config.orientHorizontally); +``` + +#### orientHorizontally (set) + +Exists as a property of the config property on the GuitarDiagrams object. Sets the horizontal status of the diagram. + +- **Parameters**: {boolean} The horizontal status of diagram. +- **Return Value**: _None_ +- **Default Value**: {boolean} false; + +_Example:_ + +```javascript +gdj1.config.orientHorizontally = true; +``` + +#### fretMarkerEnabled (get) + +Exists as a property of the config property on the GuitarDiagrams object. Gets the enabled status of fret markers. + +- **Parameters**: _None_ +- **Return Value**: {boolean} The enabled status of fret markers. +- **Default Value**: {boolean} true; + +_Example:_ + +```javascript +console.log(gdj1.config.fretMarkerEnabled); +``` + +#### fretMarkerEnabled (set) + +Exists as a property of the config property on the GuitarDiagrams object. Sets the enabled status of fret markers. + +- **Parameters**: {boolean} The enabled status of fret markers. +- **Return Value**: _None_ +- **Default Value**: {boolean} true; + +_Example:_ + +```javascript +gdj1.config.fretMarkerEnabled = true; +``` + +#### fretStartingNumber (get) + +Exists as a property of the config property on the GuitarDiagrams object. Gets the starting fret number. + +- **Parameters**: _None_ +- **Return Value**: {number} The starting fret number. +- **Default Value**: {number} 0; + +_Example:_ + +```javascript +console.log(gdj1.config.fretStartingNumber); +``` + +#### fretStartingNumber (set) + +Exists as a property of the config property on the GuitarDiagrams object. Sets the starting fret number. + +- **Parameters**: {number} The starting fret number. +- **Return Value**: _None_ +- **Default Value**: {number} 0; + +_Example:_ + +```javascript +gdj1.config.fretStartingNumber = 3; +``` + +#### stringNamesEnabled (get) + +Exists as a property of the config property on the GuitarDiagrams object. Gets the enabled status of string names. + +- **Parameters**: _None_ +- **Return Value**: {boolean} The enabled status of string names. +- **Default Value**: {boolean} false; + +_Example:_ + +```javascript +console.log(gdj1.config.stringNamesEnabled); +``` + +#### stringNamesEnabled (set) + +Exists as a property of the config property on the GuitarDiagrams object. Sets the enabled status of string names. + +- **Parameters**: {boolean} The enabled status of string names. +- **Return Value**: _None_ +- **Default Value**: {boolean} false; + +_Example:_ + +```javascript +gdj1.config.stringNamesEnabled = true; +``` + +#### stringNames (get) + +Exists as a property of the config property on the GuitarDiagrams object. Gets the array of string names. + +- **Parameters**: _None_ +- **Return Value**: {array} The array of string names. +- **Default Value**: {array} ['E','A','D','G','B','e']; + +_Example:_ + +```javascript +console.log(gdj1.config.stringNames); +``` + +#### stringNames (set) + +Exists as a property of the config property on the GuitarDiagrams object. Sets the array of string names. + +- **Parameters**: {array} The array of string names. +- **Return Value**: _None_ +- **Default Value**: {array} ['E','A','D','G','B','e']; + +_Example:_ + +```javascript +gdj1.config.stringNames = ['D','A','D','G']; +``` + +#### downloadImageEnabled (get) + +Exists as a property of the config property on the GuitarDiagrams object. Gets the enabled status of the download image button. + +- **Parameters**: _None_ +- **Return Value**: {boolean} The enabled status of the download image button. +- **Default Value**: {boolean} false; + +_Example:_ + +```javascript +console.log(gdj1.config.downloadImageEnabled); +``` + +#### downloadImageEnabled (set) + +Exists as a property of the config property on the GuitarDiagrams object. Sets the enabled status of the download image button. + +- **Parameters**: {boolean} The enabled status of the download image button. +- **Return Value**: _None_ +- **Default Value**: {boolean} false; + +_Example:_ + +```javascript +gdj1.config.downloadImageEnabled = true; +``` + +### `guitar-diagrams-config.js` Public Methods + +_None._ + +## `guitar-diagrams-marker.js` Class + +### `guitar-diagrams-marker.js` Constructors (non-default) + +Constructor(s) in `guitar-diagram-marker.js` go here... (There's only a default constructor as of now.) + +### `guitar-diagrams-marker.js` Public Properties + +Properties in `guitar-diagrams-marker.js` go here... + +### `guitar-diagrams-marker.js` Public Methods + +Methods in `guitar-diagrams-marker.js` go here... diff --git a/docs/examples/js/guitar-diagrams-js/guitar-diagrams-config.mjs b/docs/examples/js/guitar-diagrams-js/guitar-diagrams-config.mjs index 73a46ca..3b04fd0 100644 --- a/docs/examples/js/guitar-diagrams-js/guitar-diagrams-config.mjs +++ b/docs/examples/js/guitar-diagrams-js/guitar-diagrams-config.mjs @@ -63,16 +63,16 @@ export class GuitarDiagramsJSConfig { // ========== BEGIN properties // ----- References /** - * Gets the ID attribute of the canvas HTML tag. - * @return {string} The ID attribute of the canvas HTML tag. + * Gets the ID attribute of the canvas HTML element. + * @return {string} The ID attribute of the canvas HTML element. */ get canvasID() { return this.#canvasID; } // end get canvasID property /** - * Sets the ID attribute of the canvas HTML tag. - * @param {string} paramCanvasID - The ID attribute of the canvas HTML tag. + * Sets the ID attribute of the canvas HTML element. + * @param {string} paramCanvasID - The ID attribute of the canvas HTML element. */ set canvasID(paramCanvasID) { this.#canvasID = paramCanvasID; @@ -104,7 +104,7 @@ export class GuitarDiagramsJSConfig { } // end get colorNut property /** - * Gets the HTML color code of the nut. + * Sets the HTML color code of the nut. * @param {string} paramColorNut - The HTML color code of the nut. */ set colorNut(paramColorNut) { @@ -120,7 +120,7 @@ export class GuitarDiagramsJSConfig { } // end get colorNutOutline property /** - * Gets the HTML color code of the nut outline. + * Sets the HTML color code of the nut outline. * @param {string} paramColorNutOutline - The HTML color code of the nut outline. */ set colorNutOutline(paramColorNutOutline) { diff --git a/docs/index.md b/docs/index.md index 7d3c92c..51abbd7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,49 +1,150 @@ # Guitar Diagrams JS Documentation -## Overview +## Getting Started with Guitar Diagrams JS -Lorem ipsum... +### Importing the Library into Your Project -## Getting started +There are three primary ways to include the Guitar Diagrams JS library into your project: -### Importing the library into your project +1. Install the Guitar Diagrams JS library as a Node JS dependency +1. Reference the Guitar Diagrams JS library from a hosted CDN provider +1. Reference the Guitar Diagrams JS library from a local copy of the JavaScript (JS) files -Lorem ipsum... +#### Option 1: Installation as a Node JS Dependency -### Initializing a diagram +For full details, see the Node JS packages released by this project here: -Lorem ipsum... +You can install Guitar Diagrams JS in your project as a Node JS dependency via NPM. Run the following command from your project's directory where `x.y.z` (e.g., `1.0.2`) is the version (or branch name, such as `main`) of the library you want to use: -### Creating a diagram with markers +```bash +npm install @kcarlile/guitar-diagrams-js@x.y.z +``` -Lorem ipsum... +Or, alternately, you can manually edit your `package.json` file and add the following entry: -## API Usage +```json +"@kcarlile/guitar-diagrams-js": "x.y.z", +``` -Lorem ipsum... +#### Option 2: Manual Reference via CDN-Hosted Files -### guitar-diagrams.js +If you want to use a CDN-hosted package (e.g., Guitar Diagrams JS on JSDelivr at `https://cdn.jsdelivr.net/gh/KCarlile/guitar-diagrams-js@main/guitar-diagrams.js`), you can reference it in your code like this: -#### guitar-diagrams.js Members +```html + +``` -#### guitar-diagrams.js Methods +Be sure to add some target HTML element to your page with a matching ID (`gdj1.addCanvas('diagram-1');` where `'diagram-1'` is the ID) in your JS code so Guitar Diagrams JS knows where to add your drawing: -### guitar-diagrams-config.js +```html +
+``` -#### guitar-diagrams-config.js Members +#### Option 3: Manual Reference via Local Copies of Files -#### guitar-diagrams-config.js Methods +You can also install this package manually by downloading it, placing the files in the correct location, and modifying your site's code to reference the library. The following steps outline this process: -Lorem ipsum... +1. Download the repository files from the [GitHub repository for Guitar Diagrams JS](https://github.com/KCarlile/guitar-diagrams-js). +1. The only files about which you should be concerned are the following: + - `guitar-diagrams.js`: main functionality + - `guitar-diagrams-config.js`: config object + - `guitar-diagrams-marker.js`: marker object +1. Place those files in your application at `wherever/you/put/your/js/files/guitar-diagram-js/`. +1. In the JS file with your primary entrypoint, add an import statement: -| Name | Description | Parameters | Return Value | Example | Notes | -| ---- | ----------- | ---------- | ------------ | ------- | ----- | -| z | y | x | w | v | u | + ```javascript + + ``` -### Configuration Values +1. Be sure to add some target HTML element to your page with a matching ID (`gdj1.addCanvas('diagram-1');` where `'diagram-1'` is the ID) in your JS code so Guitar Diagrams JS knows where to add your drawing: -Lorem ipsum... + ```html +
+ ``` -| Name | Description | Required | Values | Default | Example | Notes | -| ---- | ----------- | -------- | ------ | ------- | ------- | ----- | -| z | y | x | w | v | u | t | +### Leveraging the Guitar Diagrams JS Library in Your Project + +Once you've successfully referenced the library using one of the methods outlined above, you'll need to prepare your HTML and JavaScript to leverage the library. + +#### Specifying the Location of the Diagram + +In your HTML markup, ensure that you have some block-level element (`

`, `

`, etc.) with a unique ID that you can reference from JavaScript, such as: + +```html +
+``` + +Remember the unique ID of this block-level element as you'll be using it in the next section. + +### Initializing a Diagram + +After your import statement, add the JavaScript to associate your block-level element's unique ID with an instance of a Guitar Diagrams JS object, like this: + +```javascript +let gdj1 = new GuitarDiagramsJS(); +gdj1.config.canvasID = 'diagram-1-canvas'; +gdj1.addCanvas('diagram-1'); +gdj1.drawNeck(); +``` + +This will result in the most basic guitar diagram of a blank fretboard. The following explains what each line does: + +| Line | Code | Description | Notes | +| ---- | ---- | ----------- | ----- | +| 1 | `let gdj1 = new GuitarDiagramsJS();`| Instantiate a new `GuitarDiagramsJS` object and assign it to the `gdj1` variable| | +| 2 | `gdj1.config.canvasID = 'diagram-1-canvas';` | Set the canvasID value of the gdj1's config object to `'diagram-1-canvas'` | `'diagram-1-canvas'` is a unique ID for the `` HTML element that will be added to your HTML within the block-level element. This ID is important so you can reference it later if you want to style the canvas itself. | +| 3 | `gdj1.addCanvas('diagram-1');` | Add the Guitar Diagrams JS HTML `` element to the parent block-level HTML element as specified by the element's unique ID | The ID string being passed here is the one specified in your HTML, like the example above: ```
``` | +| 4 | `gdj1.drawNeck();` | Draw the neck of the diagram with the previously specified parameters | | + +See _Example 1_ on the [Examples page](examples/index.html). + +### Creating a Diagram with Markers + +To add markers to a diagram, after calling `gdj1.drawNeck();`, you'll need to specify those markers and then draw them, like this: + +```javascript +let gdj2 = new GuitarDiagramsJS(); +gdj2.config.canvasID = 'diagram-2-canvas'; +gdj2.config.stringNamesEnabled = true; +gdj2.addCanvas('diagram-2'); +gdj2.drawNeck(); +gdj2.addMarker(1, 1, '1', GuitarDiagramsJS.Shape.Square); +gdj2.addMarker(2, 2, '2', GuitarDiagramsJS.Shape.Triangle); +gdj2.addMarker(3, 3, '3', GuitarDiagramsJS.Shape.Diamond); +gdj2.addMarker(4, 4, '4'); +gdj2.addMarker(5, 0, '0'); +gdj2.addMarker(6, 0, 'X'); +gdj2.addMarker(3, 1); +gdj2.drawAllMarkers(); +``` + +This will result in a basic guitar fretboard diagram with 7 different markers added. The following explains what each line does: + +| Line | Code | Description | Notes | +| ---- | ---- | ----------- | ----- | +| 1 | `let gdj2 = new GuitarDiagramsJS();`| Instantiate a new `GuitarDiagramsJS` object and assign it to the `gdj1` variable| | +| 2 | `gdj2.config.canvasID = 'diagram-2-canvas';` | Set the canvasID value of the gdj1's config object to `'diagram-2-canvas'` | `'diagram-2-canvas'` is a unique ID for the `` HTML element that will be added to your HTML within the block-level element. This ID is important so you can reference it later if you want to style the canvas itself. | +| 3 | `gdj1.addCanvas('diagram-2');` | Add the Guitar Diagrams JS HTML `` element to the parent block-level HTML element as specified by the element's unique ID | The ID string being passed here is the one specified in your HTML, like the example above, but with a different ID for diagram 2: ```
``` | +| 4 | `gdj1.drawNeck();` | Draw the neck of the diagram with the previously specified parameters | | +| 5 | `gdj2.addMarker(1, 1, '1', GuitarDiagramsJS.Shape.Square);` | Adds a marker on the string 1, fret 1, with text "1", and square shape | | +| 6 | `gdj2.addMarker(2, 2, '2', GuitarDiagramsJS.Shape.Triangle);` | Adds a marker on the string 2, fret 2, with text "2", and triangle shape | | +| 7 | `gdj2.addMarker(3, 3, '3', GuitarDiagramsJS.Shape.Diamond);` | Adds a marker on the string 3, fret 3, with text "3", and diamond shape | | +| 8 | `gdj2.addMarker(4, 4, '4');` | Adds a marker on the string 4, fret 4, with text "4" | If a shape is not specified, circle is the default shape. | +| 9 | `gdj2.addMarker(5, 0, '0');` | Adds a marker on the string 5, fret 0, with text "0" | If a shape is not specified, circle is the default shape. "0" for fret marker indicates an open string. | +| 10 | `gdj2.addMarker(6, 0, 'X');` | Adds a marker on the string 6, fret 0, with text "X" | If a shape is not specified, circle is the default shape. "X" for fret marker indicates a muted string. | +| 11 | `gdj2.addMarker(3, 1);` | Adds a marker on the string 3, fret 1 | If text is not specified, the marker will be blank. If a shape is not specified, circle is the default shape. | +| 12 | `gdj2.drawAllMarkers();` | Draws all of the specified markers on the fretboard | If a specified marker would be rendered beyond the visible fretboard, it will not be rendered and an error will be logged to the console. | + +See _Example 2_ on the [Examples page](examples/index.html). + +See the full [API documentation](api-docs.md) for all of the options for markers. + +## API Usage Details + +See the [API Documentation page](api-docs.md) for more information about how to use the API, including constructors (non-default), properties, public methods, and more.