From de3e9835049dafbd3126f7424d255c3ceaf50060 Mon Sep 17 00:00:00 2001 From: Julian Molina Date: Mon, 5 Apr 2021 21:11:39 +0200 Subject: [PATCH] Tutorial node page upgrade --- .../Schemas/Docs-Nodes/tutorial.json | 226 ++++++++++++++---- ...aragraph-styles-021-docs-anchor-style.json | 4 +- ...to-upgrade-your-existing-installation.json | 104 +++----- 3 files changed, 226 insertions(+), 108 deletions(-) diff --git a/Projects/Superalgos/Schemas/Docs-Nodes/tutorial.json b/Projects/Superalgos/Schemas/Docs-Nodes/tutorial.json index 61d1f07ba..7b372ab67 100644 --- a/Projects/Superalgos/Schemas/Docs-Nodes/tutorial.json +++ b/Projects/Superalgos/Schemas/Docs-Nodes/tutorial.json @@ -11,23 +11,23 @@ }, { "style": "Text", - "text": "Nodes in the hierarchy may be arranged freely, meaning that there may be as many tutorial topics and tutorial steps as desired. Tutorial topics may contain tutorial steps but also tutorial topics. This allows nesting topics to use them as subtopics.", - "updated": 1617610249818 + "text": "Nodes in the hierarchy may be arranged freely, meaning that there may be as many tutorial topics and tutorial steps as desired. Tutorial topics may contain tutorial steps but also other tutorial topics. This allows nesting topics to be used as subtopics.", + "updated": 1617649482153 }, { "style": "Text", - "text": "The system – as usual – reads the hierarchy in a clockwise direction starting from the node to the right of the parent Tutorial node, and goes to the depest point of each branch before moving to the next one.", - "updated": 1617609961401 + "text": "The system – as usual – evaluates the hierarchy in a clockwise direction starting from the node to the right of the parent Tutorial node, and goes to the deepest node of each branch before moving to the next one.", + "updated": 1617649522223 }, { - "style": "Text", - "text": "In general terms, all types of nodes behave similarly in the sense that each node, independently of the precise type, represents a Tutorial Step in and of itself. Subtle differences shall be covered where appropriate.", - "updated": 1617609984716 + "style": "Callout", + "text": "In general terms, all types of nodes behave similarly in the sense that each node, independently of the precise type, represents a tutorial step in and of itself. That is, all nodes including the top-level Tutorial node, the Tutorial Topic node, and the Tutorial Step node may display a content page as a step in the tutorial. Subtle differences shall be pointed where appropriate.", + "updated": 1617622995279 }, { "style": "Note", - "text": "The key similarity among all types of nodes in the hierarchy is that all of them may draw content from the tutorial's collection of pages in the Docs. That is, each node in the hierarchy points to a page in the Docs, and it is that page in the Docs that features the content that tutorials display. The pointer is specified in the configuration of each node (see the docs property).", - "updated": 1617611604392 + "text": "The key similarity among all types of nodes in the hierarchy is that all of them may draw content from the tutorial's collection of pages in the Docs. That is, each node in the hierarchy points to a Docs Page, and it is that page in the Docs that features the content displayed for the given step. The pointer is specified in the configuration of each node (see the docs property).", + "updated": 1617623101039 }, { "style": "Block", @@ -41,7 +41,12 @@ { "style": "Text", "text": "The configuration of each node in the tutorial hierarchy determines the content and behavior of each step. All types of nodes share the same basic configuration. However, Tutorial Step nodes have extra properties, described on the Tutorial Step node page.", - "updated": 1617610392929 + "updated": 1617623609988 + }, + { + "style": "Success", + "text": "The configuration properties discussed on this page apply to all types of nodes in the hierarchy.", + "updated": 1617623631110 }, { "style": "Text", @@ -58,25 +63,47 @@ "text": "The HTML page features a limited space and does not support scrolling. If too much information is defined in the associated Docs Page, the resulting content overflows the available space in the tutorial window. There is no system-side control to deal with such overflows, so it's up to you to spread information across multiple steps and keep each page within its limits.", "updated": 1613839536547 }, + { + "style": "Title", + "text": "Configuration Properties", + "updated": 1617635291377 + }, { "style": "Subtitle", - "text": "Properties", - "updated": 1609705050135 + "text": "icon", + "updated": 1617635214170 + }, + { + "style": "Text", + "text": "The property icon requires two definitions:", + "updated": 1617635366207 }, { "style": "List", - "text": "icon: Features the name of the icon without the extension, and the project the icon belongs to. For your reference, icons are stored in the following path:", - "updated": 1617610705494 + "text": "The \"name\" of the icon without the extension; " + }, + { + "style": "List", + "text": "The \"project\" the icon belongs to." + }, + { + "style": "Text", + "text": "For your reference, icons are stored in the following path:" }, { "style": "Json", "text": "\\Projects\\[Project-Name]\\Icons", "updated": 1617610685030 }, + { + "style": "Success", + "text": "Use the existing collection of icons to illustrate each step of the tutorial. These illustrations help make for more compelling communication.", + "updated": 1617623866873 + }, { "style": "Text", - "text": "When the configuration exists, the icon is placed within a table, on the left-hand side of the text block featured in the definition field of the corresponding Docs page. When there is no icon, the definition occupies the full width.", - "updated": 1617610852528 + "text": "When the configuration exists, the icon is placed within a table, side by side with the text block that makes up the definition field of the associated Docs Page. When there is no icon, the definition occupies the full width of the page.", + "updated": 1617635415677 }, { "style": "Json", @@ -85,13 +112,18 @@ }, { "style": "Text", - "text": "The above configuration places the balance.png icon of the Superalgos project in the table of the corresponding Docs page.", - "updated": 1617610921825 + "text": "The above configuration places the balance.png icon of the Superalgos project in the table of the corresponding Docs page (see the docs property below).", + "updated": 1617635461827 }, { - "style": "List", - "text": "position: Determines the position of the floating HTML. There are three alternatives... \"Left\", \"Right\", or leave the field empty to position the page in the center of the screen.", - "updated": 1617610967355 + "style": "Subtitle", + "text": "position", + "updated": 1617635475423 + }, + { + "style": "Text", + "text": "The position property determines the position of the floating HTML. There are three alternatives... \"Left\", \"Right\", or leave the field empty to position the page on the center of the screen.", + "updated": 1617635484212 }, { "style": "Json", @@ -99,38 +131,72 @@ "updated": 1613840787300 }, { - "style": "List", - "text": "slider: Determines the position of the horizontal slider. There are three alternatives... \"toTop\", \"toBottom\", \"toMiddle\".", - "updated": 1617610973439 + "style": "Text", + "text": "The configuration above places the tutorial step on the left-hand side of the screen.", + "updated": 1617635642707 + }, + { + "style": "Subtitle", + "text": "slider", + "updated": 1617635668767 + }, + { + "style": "Text", + "text": "The slider property determines the position of the horizontal slider. There are three alternatives... \"toTop\", \"toBottom\", \"toMiddle\"." }, { "style": "Json", - "text": "\"slider\": \"toBottom\"" + "text": "\"slider\": \"toBottom\" // Opens the Charting Space", + "updated": 1617624084984 }, { - "style": "List", - "text": "pressButton: Allows you to forcefully \"Stop\" the tutorial, go to the \"Next\" step, go to the \"Previous\" step, or \"Skip\" a step. When a step is loaded and one of these options is configured in this property, the action is applied immediately. A common use of this feature is to skip a step, for instance, a Tutorial Topic node that is used solely for organizational purposes within the hierarchy, thus has no content.", - "updated": 1617611004815 + "style": "Json", + "text": "\"slider\": \"toTop\" // Opens the Design Space", + "updated": 1617624125599 + }, + { + "style": "Json", + "text": "\"slider\": \"toMiddle\" // Enables using the Charting Space and the Design Space concurrently", + "updated": 1617624154127 + }, + { + "style": "Subtitle", + "text": "pressButton", + "updated": 1617635952027 + }, + { + "style": "Text", + "text": "The pressButton property allows you to forcefully \"Stop\" the tutorial, go to the \"Next\" step, go to the \"Previous\" step, or \"Skip\" a step. When a step is loaded and one of these options is configured in this property, the action is applied immediately." + }, + { + "style": "Note", + "text": "A common use of this feature is to skip a step, for instance, a Tutorial Topic node that is used solely for organizational purposes within the hierarchy, thus features no content. Leave the field empty for the step to play in the usual fashion.", + "updated": 1617649582774 }, { "style": "Json", "text": "\"pressButton\": \"Next\"", "updated": 1613841332185 }, + { + "style": "Text", + "text": "The above configuration takes the user to the next step in the tutorial without displaying any content for the node in question.", + "updated": 1617648136262 + }, { "style": "Success", - "text": "You may use Tutorial Topic nodes for organizational purposes only, for instance, to arrange the hierarchy in a way that it's easy to maintain. Topics with too many steps are harder to deal with later on. In other words, you may use a Tutorial Topic node to group several steps, even if you don't intend the Tutorial Topic node to display any content. In such cases, you may use this property to skip the step that is not intended for content-display.", - "updated": 1617611332634 + "text": "You may use Tutorial Topic nodes for organizational purposes only, for instance, to arrange the hierarchy in a way that it's easy to read and maintain. Topics with too many steps are harder to deal with later on. In other words, you may use a Tutorial Topic node to group several steps, even if you don't intend the Tutorial Topic node to display any content. In such cases, you may use this property to skip the step that is not intended for content display.", + "updated": 1617649616576 }, { - "style": "Note", - "text": "Leave the filed empty for the step to play in the usual fashion.", - "updated": 1617611454046 + "style": "Subtitle", + "text": "docs", + "updated": 1617636114812 }, { - "style": "List", - "text": "docs: The property is used to point to the Docs Tutorial Page that feeds content to the particular tutorial step. The definition requires the name of the Project, the Docs Page Category which is always Tutorial, and the complete name of the Tutorial Step page.", - "updated": 1617611566144 + "style": "Text", + "text": "The docs property is used to point to the Docs Tutorial Page that feeds content to the particular tutorial step. The definition requires the name of the Project, the Docs Page Category which is always \"Tutorial\", and the complete name of the Docs Page, that is, the \"type\" as specified in the JSON file.", + "updated": 1617648211414 }, { "style": "Json", @@ -138,14 +204,92 @@ "updated": 1613842164831 }, { - "style": "List", - "text": "controlDocs: the property is used to control the behavior of the Docs panel. The panel property may be set to \"Open\" or \"Close\". The property closeTutorialEditor may switch on (true) and off (false) the Docs editor. When set to false, the Docs panel shows the page corresponding to the active tutorial step or the page in the Docs that is requested. When the property is set to true and there is no request to open a Docs page, then the Docs panel shows the search box. The page property is where you define which page in the Docs must be loaded. You must specify the Project, the Docs Page Category, and the type which is the complete name of the page.", - "updated": 1613843493276 + "style": "Subtitle", + "text": "controlDocs", + "updated": 1617648219190 + }, + { + "style": "Text", + "text": "The property is used to control the behavior of the Docs panel. Within controlDocs, several properties are available, and all of them are optional. Let's review each in detail." + }, + { + "style": "Text", + "text": "The panel property may be set to \"Open\" or \"Close\". This property controls the tab that allows you to open the Docs Panel in one step, and close it on a different step when it's no longer needed.", + "updated": 1617649653900 }, { "style": "Json", - "text": " \"controlDocs\": {\n \"panel\": \"Open\",\n \"closeTutorialEditor\": true,\n \"page\": {\n \"project\": \"Superalgos\",\n \"category\": \"Topic\",\n \"type\": \"Trading System Hierarchy\"\n }\n }", - "updated": 1613842185832 + "text": "\"controlDocs\": {\n \"panel\": \"Open\",\n }", + "updated": 1617634451884 + }, + { + "style": "Text", + "text": "" + }, + { + "style": "Success", + "text": "If the Docs Panel is closed, the rest of the properties are somehow irrelevant. However, when the Docs Panel is open, the rest of the properties control what is displayed in the Docs Panel.", + "updated": 1617635061507 + }, + { + "style": "Text", + "text": "The property closeTutorialEditor may switch on and off the Docs editor. When set to false or when there is no definition, and provided no specific Docs Page is called (see controlDocs below), the Docs panel shows the page associated with the current tutorial step in editing mode.", + "updated": 1617649781891 + }, + { + "style": "Json", + "text": "\"controlDocs\": {\n \"panel\": \"Open\",\n \"closeTutorialEditor\": false,\n }", + "updated": 1617648310737 + }, + { + "style": "Success", + "text": "Because this definition is set to false by default, this is the usual behavior. That is, by default, when the Docs Panel is opened while a tutorial step is playing, the Docs Panel shows the Docs Page associated with the specific step so that the page may be edited right then and there.", + "updated": 1617648335347 + }, + { + "style": "Text", + "text": "When the closeTutorialEditor property is set to true and there is no request to open a Docs page (see page property below), then the Docs panel shows whatever Docs Page was being displayed in the previous step.", + "updated": 1617648434580 + }, + { + "style": "Json", + "text": "\"controlDocs\": {\n \"panel\": \"Open\",\n \"closeTutorialEditor\": true,\n }", + "updated": 1617634444688 + }, + { + "style": "Success", + "text": "You may want to close the tutorial editor when the user is supposed to interact with the Docs from one step to the next. For example, let's say the tutorial instructs the user to run a search and discusses the search results in the following step. In that case, you will want the tutorial editor to remain closed, as otherwise, the search performed by the user would be lost, and instead the page corresponding to the new tutorial step would be loaded.", + "updated": 1617649832578 + }, + { + "style": "Text", + "text": "The searchPage property overruns the tutorial editor settings and loads the home search page featuring the search box in the center.", + "updated": 1617649861459 + }, + { + "style": "Json", + "text": "\"controlDocs\": {\n \"panel\": \"Open\",\n \"searchPage\": true,\n }", + "updated": 1617648855034 + }, + { + "style": "Success", + "text": "Use the above setting when you wish the user to get the clean search box to make a search or run a command.", + "updated": 1617648884933 + }, + { + "style": "Text", + "text": "The page property is where you define which Docs Page must be loaded. You must specify the Project, the Docs Page Category, and the \"type\" which is the complete name of the page. The optional property anchor allows you to points the user to a specific paragraph in the page with the Docs Anchor Style.", + "updated": 1617649332425 + }, + { + "style": "Json", + "text": "\"controlDocs\": {\n \"panel\": \"Open\",\n \"page\": {\n \"project\": \"Superalgos\",\n \"category\": \"Topic\",\n \"type\": \"Syntax Overview\",\n \"anchor\": \"Previous Property\"\n }\n }", + "updated": 1617649170254 + }, + { + "style": "Success", + "text": "Use the above configuration when you wish the user to read a specific page in the Docs.", + "updated": 1617649085529 } ] } \ No newline at end of file diff --git a/Projects/Superalgos/Schemas/Docs-Topics/docs-paragraph-styles-021-docs-anchor-style.json b/Projects/Superalgos/Schemas/Docs-Topics/docs-paragraph-styles-021-docs-anchor-style.json index 9a41f82cc..4746dd679 100644 --- a/Projects/Superalgos/Schemas/Docs-Topics/docs-paragraph-styles-021-docs-anchor-style.json +++ b/Projects/Superalgos/Schemas/Docs-Topics/docs-paragraph-styles-021-docs-anchor-style.json @@ -3,8 +3,8 @@ "pageNumber": 21, "type": "Docs Anchor Style", "definition": { - "text": "Anchor paragraphs are used together with the Docs Goto Command. When you want to generate a Docs Link to an specific part of a Docs Page, you first need to create an Anchor paragraph in order to be able to create the link to that part of the page.", - "updated": 1615591597546 + "text": "Anchor paragraphs are used together with the Docs Goto Command. When you want to generate a Docs Link to a specific part of a Docs Page, you first need to create an Anchor paragraph to be able to create the link to the specific paragraph in the page.", + "updated": 1617649387777 }, "paragraphs": [ { diff --git a/Projects/Superalgos/Schemas/Docs-Topics/troubleshooting-003-how-to-upgrade-your-existing-installation.json b/Projects/Superalgos/Schemas/Docs-Topics/troubleshooting-003-how-to-upgrade-your-existing-installation.json index 91c711069..78f928dce 100644 --- a/Projects/Superalgos/Schemas/Docs-Topics/troubleshooting-003-how-to-upgrade-your-existing-installation.json +++ b/Projects/Superalgos/Schemas/Docs-Topics/troubleshooting-003-how-to-upgrade-your-existing-installation.json @@ -9,82 +9,46 @@ "paragraphs": [ { "style": "Text", - "text": "You should expect new releases of Superalgos to become available every few months. Release announcements are made through the Official Superalgos Telegram Announcements Channel.", - "updated": 1611511377439 + "text": "You should expect new releases of Superalgos to become available every few months. Release announcements are made through the official Superalgos Announcements Channel.", + "updated": 1617647047464 }, { "style": "Note", - "text": "During this beta stage, patches may be released as frequently as several times per week. Due to their high-frequency, minor updates go unannounced. If you ever experience a malfunction, make sure you upgrade your installation to the latest version available in the Superalgos repository before reporting a bug.", - "updated": 1611511390486 + "text": "During the beta stage, patches and new features may become available in the develop branch as frequently as several times per week. Due to the high frequency of their occurrence, minor updates go unannounced. If you ever experience a malfunction, make sure you upgrade your installation to the latest version available in the develop branch of the Superalgos repository before reporting a bug.", + "updated": 1617647903163 }, { "style": "Title", - "text": "New Releases" - }, - { - "style": "Text", - "text": "If you are upgrading to a new official release, make sure you follow these instructions as well as those under the All Upgrades section." - }, - { - "style": "Subtitle", "text": "Read the Announcement Carefully" }, { "style": "Text", - "text": "Read and understand the announcement explaining the changes and how they may impact your workflow. Most importantly, find out if the new version requires upgrading your workspace." - }, - { - "style": "Subtitle", - "text": "Check the Getting Started Guide" - }, - { - "style": "Text", - "text": "It would be wise to go through the potentially new Getting Started Guide in the documentation, as it may reveal important information." - }, - { - "style": "Subtitle", - "text": "Back Up Your Personal Work" - }, - { - "style": "Text", - "text": "If the new version requires upgrading to a new workspace, you must decide which parts of your work you wish to backup so that you may restore them on the upgraded workspace (e.g.: you may want to backup your trading systems, data mines, super scripts, specific settings or configurations such as testing sessions, time machines, and so on)." - }, - { - "style": "Text", - "text": "If there is no need to upgrade the workspace, that means that the new version of the system should work well with your existing workspace, provided that you are only one version behind." + "text": "Read and understand the announcement explaining the changes and how they may impact your workflow. Most importantly, find out if the new version requires upgrading your workspaces or the rest of the assets you may be working with (trading systems, data mines, etc).", + "updated": 1617646452770 }, { "style": "Title", - "text": "All Upgrades" + "text": "Back-Up Your Personal Work", + "updated": 1617647919380 }, { - "style": "Subtitle", - "text": "Back Up the Workspace" + "style": "Important", + "text": "Always back up your personal work. Whether the new version is backward-compatible or not, you may — for whatever reason — want to go back to the state of affairs before the upgrade.", + "updated": 1617647956316 }, { "style": "Text", - "text": "Always back up your existing workspace before switching versions. You may go back to a working version of the software in case something goes wrong with the new one, by installing the previous version of the system and restoring your old workspace from a backup file if needed." + "text": "The new version will always ship with its own Plugin Workspaces. The release announcement should make it clear if the new version is backward-compatible or not. If it's not, the announcement should cover any consideration relevant to upgrading from the previous version.", + "updated": 1617648003762 }, { - "style": "Subtitle", + "style": "Title", "text": "Put the House in Order" }, { "style": "Text", - "text": "1. Stop all tasks that may be running in the network hierarchy, and close your browser. Allow a minute or two until all activity stops before closing the Console/Command Line/Terminal running the servers." - }, - { - "style": "Text", - "text": "2. Check if you have any personal files, such as your workspace backups and so on in your Superalgos-master folders. Move them to a different location if you do, or take precautions not to delete them in the next step." - }, - { - "style": "Text", - "text": "3. You will keep the Data-Storage and My-Workspaces folders intact and delete all the remaining folders within the Superalgos folder." - }, - { - "style": "Important", - "text": "You do not need to get rid of the historic market data or the workspaces you have been working with every time you upgrade your system. Do not delete your Data-Storage or your My-Workspaces folder.", - "updated": 1611511439947 + "text": "Stop all tasks that may be running in the Network hierarchy. Allow a minute or two until all activity stops.", + "updated": 1617646656306 }, { "style": "Title", @@ -93,8 +57,18 @@ }, { "style": "Text", - "text": "Always follow the instructions in the Official Announcements Channel and the official blog post about the new release.", - "updated": 1611511529701 + "text": "Run the App Update Command to install the new version of the app. Follow the instructions to close the browser and stop the client once the system is updated.", + "updated": 1617647599654 + }, + { + "style": "Title", + "text": "Apply the Guidance in the Announcement", + "updated": 1617647633126 + }, + { + "style": "Text", + "text": "If the official announcement provides information on how to upgrade your assets to use them in the new version, this is the time to follow the relevant guidance.", + "updated": 1617647676913 }, { "style": "Important", @@ -107,18 +81,21 @@ }, { "style": "Text", - "text": "Once the system loads in your browser window and before you start working, you need to empty Chrome’s cache and do a hard reload to make sure the browser does use the newly installed files." + "text": "Once the system loads in your browser window and before you start working, it's always good practice to empty Chrome’s cache and do a hard reload to make sure the browser does use the newly installed files.", + "updated": 1617647736967 }, { - "style": "Text", - "text": "1. Hit F12 to open Chrome’s Developer Tools. You do not need to use the Developers Tools, but opening it allows performing the next task." + "style": "List", + "text": "Hit F12 to open Chrome’s Developer Tools. You do not need to use the Developers Tools, but opening it allows performing the next task.", + "updated": 1617647751232 }, { - "style": "Text", - "text": "2. Right-click on the refresh icon and select Empty Cache and Hard Reload from the drop-down menu. Once refreshed, you may close Developer Tools with F12." + "style": "List", + "text": "Right-click on the refresh icon and select Empty Cache and Hard Reload from the drop-down menu. Once refreshed, you may close Developer Tools with F12.", + "updated": 1617647755781 }, { - "style": "Text", + "style": "List", "text": "F12 to open Developer Tools, then right-click on the refresh icon." }, { @@ -135,11 +112,8 @@ }, { "style": "Text", - "text": "Before going deep back to work, it is always recommeended to test the new version a bit and make sure that your existing work performs as you would expect." - }, - { - "style": "Text", - "text": "If you run into any issues, feel free to drop us a line in our Community." + "text": "Before going deep back to work, it is always recommended to test the new version a bit and make sure that your existing work performs as you would expect.", + "updated": 1617648042507 } ] } \ No newline at end of file