- added documentation tutorial

DocumentationTutorial/Documentation/Readme.md

@@ -0,0 +1,17 @@
+---
+keywords: Documentation Tutorial
+summary:  The root page that will be shown at startup
+author:   Christoph Hart
+modified: 08.10.2019
+colour:   0xFF885588
+---
+
+This tutorial covers the use of the `MarkdownPanel` as inbuilt project documentation. It covers the following topics:
+
+
+
+- setup the MarkdownPanel
+- customize a [TOC structure](/toc) and appearance
+- embed [Fonts](/embed#font) and [Images](/embed#images)
+- [Open Links](/link) using scripting calls
+- add a server URL that updates the documentation automatically

DocumentationTutorial/Documentation/embed/Readme.md

@@ -0,0 +1,52 @@
+---
+keywords: Embed files
+summary:  How to use fonts an images
+author:   Christoph Hart
+modified: 08.10.2019
+colour:   0xFF555588
+index:    03
+---
+
+This chapter covers the use of external data: displaying images and loading a custom font.
+
+## Font
+
+In order to use a special font, you'll have to go through the default procedure of embedding fonts in HISE:
+
+1. Copy them into the **Images/fonts** subdirectory
+2. Call `Engine.loadFontAs()` to load the font
+3. Choose the **Font** (and **BoldFont**) in the MarkdownPanel's property list.
+
+> Just take a look at the `onInit` callback of this project to see it in action.
+
+## Images
+
+In order to embed images into your doc, you need to copy them into the images folder and make a link to it. 
+The best way to do so is the inbuilt image creator tool in the MarkdownEditor. Just click on the image icon, select any file in your system and it will copy it into the images folder and paste an appropriate link in the current cursor position:
+
+![MyFile](/images/custom/myfile.png) 
+
+You can also opt to rename it in case you've created it using a screen grabber which gave it the meaningfull name **Unbenannt(8).png**.
+
+> Be aware that the images will **NOT** use the Images folder of your plugin. These things are kept separate because they might be updated along with the content.
+
+### SVG images
+
+SVG images can also be embedded, but I highly recommend to use the width limiting syntax here, or small icons / graphs will be expanded to full width and look funny:
+
+This will happen if you load a SVG image like this: `![](images/custom/kick_outline.svg)`
+
+![](images/custom/kick_outline.svg)
+
+Better: `![](images/custom/kick_outline.svg:64px)`
+
+![](images/custom/kick_outline.svg:64px)
+
+## ![](images/custom/kick_outline.svg:64px) Pro-Tip: Using icons in a headline
+
+By default images can't be inlined so they appear inside normal text flow. The only exception is to use icons in a headline like shown above:
+
+
+> `## ![](images/custom/kick_outline.svg:64px) Pro Tip: ...`
+
+

DocumentationTutorial/Documentation/link/Readme.md

@@ -0,0 +1,156 @@
+---
+keywords: How to link
+summary:  Open links in the markdown panel
+author:   Christoph Hart
+modified: 08.10.2019
+---
+
+One of the main [benefits](/link#the-overlay-system) of an inbuilt documentation is that you can add in-place documentation of UI elements and open the page (and anchor) to directly show the documentation of the UI element.
+
+Since there are many ways to do this, HISE just offers a minimal API for this and leaves the implementation up to the developer.  
+This project will show one possible approach:  
+A button that toggles "help" mode, which shows a view panels that overlay UI elements. If you click on of of these elements, it will show the markdown panel with the link to the documentation of the UI element.
+The classes will be self-contained and should be easily transferable to other projects.
+
+## The API
+
+First of all, we'll describe the API. If you want to implement your own help system, you can stop after reading this chapter.
+
+It all comes down to a single property in the MarkdownPanel: `StartURL`.  
+This URL will just tell which markdown panel to show at initialisation. Now what looks like a static property gives us all the features we need: if we want to link to another page, we'll just recreate the MarkdownPanel by changing the object and rebuilding the floating tile.
+
+However this requires us to **not** use the **ContentType** property from the interface designer, but use a JSON object from the scripting world and the `ScriptFloatingTile.setContentData(var data)` scripting call, so in before we can proceed, we have to switch to that approach.
+
+Most of the stuff can just be copied from the object defined in the Interface designer:
+
+```javascript
+const var docData = {
+  "Type": "MarkdownPanel",
+  "ShowBack": false,
+  "ShowSearch": false,
+  "ShowToc": true,
+  "Font": "Roboto",
+  "FontSize": 18,
+  "BoldFontName": "Roboto Fat",
+  "FixTocWidth": 300,
+  "StartURL": "/",
+  "ColourData":
+  {
+    "bgColour": 0xFF222222,
+    "itemColour1": 0xFF880088, // the headline colour
+    "itemColour2": 0xFF110188, // the link colour
+    "textColour": 0xFFAAAAAA
+  }
+};
+```
+
+> Note: if you can't see the code above in the compiled version don't worry, it's a known issue that I'll remove soon...
+
+with these modifications:
+
+- the `Type` has to be specified
+- the `Font` and `FontSize` properties have to be added
+- the `ColourData` needs to be an object within the object
+
+from then on its business as usual: grab a reference to the panel and set the content data:
+
+```javascript
+const var HelpPanel = Content.getComponent("HelpPanel");
+HelpPanel.setContentData(docData);
+```
+
+After we've made that transition, linking to a page is pretty straightforward: we just change the `StartURL` property and call the method again.  
+We'll use a function that does that so we save some typing later:
+
+```javascript
+inline function showLink(url)
+{
+
+    docData.StartURL = url;
+
+    // Rebuild the markdown panel with the given URL
+    HelpPanel.setContentData(docData);
+
+    // We'll also make it visible in case that it isn't...
+    HelpPanel.set("visible", true);
+}
+```
+
+So whenever we want to show a page in the docs, we just call this function and give it the URL to this page.
+
+> A quick way to get valid links that are guaranteed to work is to right click in the TOC and choose "Copy Link".
+
+This concludes the basic setup and we can proceeed with a overlay system that uses panels.
+
+## The overlay system
+
+For our system we need 2 things:
+
+1. The toggle button
+2. The overlay templates.
+
+We'll keep it nice and tidy and put everything in a separate namespace called `HelpOverlay` in a dedicated file.
+
+> If you want to transfer this method to one of your projects, just grab that file and use it like described here.
+
+Before we proceed, we'll clean up and move all the code above into this namespace. We'll also add a function `initDocPanel()` which you need to call with the ID of your MarkdownPanel floating tile.
+
+```javascript
+// Call this somewhere in your onInit callback
+HelpOverlay.initDocPanel("myPanelName");
+```
+
+### The help button
+
+First of all we need a button that toggles the help mode. We'll add another function `HelpOverlay.initHelpButton(buttonId)` which initialises the button and sets its properties accordingly.  
+We'll also define the callback for the button that toggles the overlays (don't bother about the `showOverlays` function, we'll add that later).
+
+
+```javascript
+reg helpMode = 0;
+reg helpButton;
+
+inline function helpButtonCallback(component, value)
+{
+    if(value)
+    {
+        showOverlays(true);
+    }
+    else
+    {
+        showOverlays(false);
+        docPanel.set("visible", false);
+    }
+}
+
+inline function initHelpButton(name)
+{
+    helpButton = Content.getComponent(name);
+    helpButton.set("saveInPreset", false");
+    helpButton.setControlCallback(helpButtonCallback);
+}
+```
+
+Then we need to call this from our onInit script:
+
+```javascript
+HelpOverlay.initHelpButton("HelpButton");
+```
+
+### The overlay panels
+
+The second part of this system are the overlay panels. It is important that adding new overlays is as easy as possible (otherwise chances are high that you won't add these).
+
+The most simplified workflow for this is:
+
+1. Add a panel and use the same ID but with a `_help` suffix
+2. Call HelpOverlay.add(originalId) with **the ID of the original widget**.
+
+The rest will be taken care of automatically:
+
+- setting the position of the panel: parent hierarchy and position
+- setting the paint routine and mouse logic
+- storing it in an array that will be toggled when you click the help button
+
+Take a look at the implementation in HelpOverlay.js. You can of course customize the appearance by changing the paint routine that's been given to those panels.
+

DocumentationTutorial/Documentation/setup/Readme.md

@@ -0,0 +1,35 @@
+---
+keywords: Setup
+summary:  How to setup the documentation
+author:   Christoph Hart
+modified: 08.10.2019
+colour:   0xFF8877EE
+index:    00
+---
+
+The MarkdownPanel can be used to embed a user manual directly into the plugin.
+
+Just add a MarkdownPanel as FloatingTile on your interface and it will display the documentation you've written in the Documentation subfolder.
+
+## Initialisation
+
+There are a few things that the Markdown Panel has to do the first time it is going to be used:
+
+- building of the database. This might take a few seconds for complex documentations.
+- if [server sync](/sync#setup-the-server-url) is enabled, it will fetch the hash from the server and update it if it finds a new version.
+
+This initialisation will take place the first time it is made visible. If you show the panel without any page logic (like this tutorial), this will happen when you first create the plugin's interface.  
+A much more real-world use case approach is that the MarkdownPanel is not visible at the beginning and only shows up after some sort of user interaction (like pressing a help button). In this case it will defer the initialisation until the last possible moment, which is shortly before the user wants to read the documentation.
+
+> So unless you have some special use case, it's highly recommended to make the Markdown Panel not visible at startup.
+
+## Writing the documentation
+
+The documentation will fetch its content from the markdown files in the Documentation subdirectory of your project.  
+The best workflow is to use the scripting workspace with the interface designer on the right and a markdown editor in the left code editor panel. If HISE finds a MarkdownEditor there, you will be able to right click and directly open a new tab with the markdown file.
+
+- Click on the **+** icon
+- Right click on the content of the new tab 
+- Choose MarkdownEditor (below ScriptEditor)
+
+If you want to view the changes you've made, just save the markdown file (Cmd+S), then rebuild the interface.

DocumentationTutorial/Documentation/sync/Readme.md

@@ -0,0 +1,66 @@
+---
+keywords: Update the documentation
+summary:  How to use a online resource to update the docs automatically
+author:   Christoph Hart
+modified: 08.10.2019
+---
+
+Chances are huge that you might want to update the documentation of your plugin after the release: you'll notice that most of the questions that users will have will repeat themselve and where's a better place to adress this as directly in the plugin? That would be a problem if the documentation is baked into the plugin. 
+
+The solution is pretty easy: you can define a Server URL which hosts the compiled documentation files and the plugin will check on startup whether the documentation has changed.
+
+## Setup the server URL
+
+1. Make sure you "export" your documentation into the three doc files.
+2. Upload them to a publicly available server. 
+3. Enter the URL to the location where you host your cached documentation files as `ServerUpdateURL` property in the panel.
+
+Right click on the MarkdownPreviewPanel in your interface inside HISE and choose **Export**, then press OK. After this, the three required files can be found in your AppData's **Documentation** subfolder:
+
+- `Content.dat` - contains a compressed version of all texts
+- `Images.dat` - contains a compressed version of all images
+- `hash.json` - just contains the checksum of the files and determines whether it needs to update one of them.
+
+The server URL that you have to specify needs to point to the **parent directory of a folder called** `cache`:  
+If you host your files on `https://example.com/docs`, you'll have to create a subfolder called `cache` in your `docs` folder, put the file in there and supply `https://example.com/docs` as `ServerUpdateURL`.
+
+> if you use Filezilla, you can add a bookmark that points to your local appdata's Documentation folder and the FTP target location so you just need to drag them over.
+
+So whenever you change the docs, repeat these steps (export in HISE, open up FileZilla (or your favorite FTP client) with the bookmark and drag the files on the server).
+
+## Static HTML version
+
+An embedded documentation is nice, but you probably also want some sort of online manual so that users without internet connection (or possible customers who want to check out your software) can also read your documentation.  
+For this reason, HISE offers a **HTML Page Generator** that takes your markdown files and renders a bunch of static HTML sites that you can upload on the server.
+
+1. Add the template files for the header and the footer.
+2. Export the doc as HTML folder structure
+3. Upload the files to your server.
+
+### Template files
+
+In order to create the HTML files, the HTML generator will look for two files called `header.html` and `footer.html` in the `template` subdirectory of your Documentation folder.  
+The HTML generator will then simply create one file per page using this rule:
+
+> header + content + footer
+
+So the minimal header and footer that makes sense is:
+
+#### Header:
+
+```
+<html>
+<head/>
+<body>
+<div id="content">
+```
+
+#### Footer
+
+```
+</div>
+</body>
+</html>
+```
+
+If you have a minimal understanding of HTML, you'll see that the content is being put into one div container that can be customized with CSS using the `content` ID.