Merge pull request #810 from ICRAR/eagle-1376

EAGLE-1376: Update settings documentation

.gitignore

@@ -22,3 +22,4 @@ docker-compose.yml
 /playwright-report/
 /blob-report/
 /playwright/.cache/
+src/tutorials/*.js

docs/settings.rst

@@ -44,39 +44,23 @@ Tabs Breakdown
 User Options
 """"""""""""
 
-**Confirm Discard Changes** - Prompt user to confirm that unsaved changes to the current file should be discarded when opening a new file, or when navigating away from EAGLE.
-
-**Confirm Remove Repositories** - Prompt user to confirm removing a repository from the list of known repositories.
-
-**Confirm Reload Palettes** - Prompt user to confirm when loading a palette that is already loaded.
-
-**Confirm Delete** - Prompt user to confirm when deleting node(s) or edge(s) from a graph.
+**Reset Action Confirmations** - Enable all action confirmation prompts. EAGLE allows users to skip confirmation dialogs by clicking "Don't show me again" when dismissing them. This setting allows users to undo that action, re-enabling the confirmation dialogs.
 
 **Disable JSON Validation** - Allow EAGLE to load/save/send-to-translator graphs and palettes that would normally fail validation against schema.
 
 **Overwrite Existing Translator Tab** - When translating a graph, overwrite an existing translator tab.
 
-**Show File Loading Warnings** - Display list of issues with files encountered during loading.
-
-**UI Mode** - User Interface Mode. Simple Mode removes palettes, uses a single graph repository, simplifies the parameters table. Expert Mode enables the display of additional settings usually reserved for advanced users.
-
 
 UI options
 """"""""""
 
 **Show non key parameters** - Show additional parameters that are not marked as key parameters for the current graph.
 
-**Display Node Keys** - Node keys are usually only necessary for troubleshooting purposes.
-
-**Hide Palette Tab** - The Palette tab is not required for loading and executing graphs. Hiding it will reduce visual complexity.
-
-**Hide Read Only Parameters** - Hide Read Only Parameters
-
 **Translator Mode** - There are a few modes affecting the amount of permissions available:  **minimal** - using default algorithm and settings, hiding the translation tab. **Default** - using default algorithm allowing for some extra control via the translation tab. **Expert** - Offers additional translating algorithms.
 
 **Graph Zoom Divisor** - The number by which zoom inputs are divided before being applied. Larger divisors reduce the amount of zoom.
 
-**Show edge/node errors/warnings in inspector** - Show the errors/warnings found for the selected node/edge in the inspector, below the other editor widgets. Errors and warnings are always shown the the checkGraph display in the navbar.
+**Show edge/node errors/warnings in Graph** - Show the errors/warnings found for the selected node/edge in the inspector, below the other editor widgets. Errors and warnings are always shown the the checkGraph display in the navbar.
 
 Advanced Editing
 """"""""""""""""
@@ -85,13 +69,21 @@ Advanced Editing
 
 **Allow Component Editing** - Allow the user to add/remove ports and parameters from components.
 
-**Allow Palette Editing** - Allow the user to edit and create palettes.
+**Allow Modify Graph Configurations** - Allow the user to add/remove parameters from graph configurations.
+
+**Allow Graph Editing** - Allow the user to create and edit graphs.
+
+**Allow Palette Editing** - Allow the user to create and edit palettes.
 
 **Allow Readonly Palette Editing** - Allow the user to modify palettes that would otherwise be readonly. These are usually only the default loaded palettes.
 
 **Allow Edge Editing** - Allow the user to edit edge attributes.
 
-**Auto-suggest destination nodes** - If an edge is drawn to empty space, EAGLE will automatically suggest compatible destination nodes.
+**Filter Node Suggestions** - Filter node options when drawing edges into empty space.
+
+**Value Editing** - Set which values are allowed to be edited. Possible values are: "Config Only", "Normal", "Readonly". "Config Only" means that only parameters within graph configurations are editable. "Normal" means that all parameters are editable, except those flagged as readonly. "Readonly" means that even readonly parameters are editable.
+
+**Auto-complete edges level** - Specifies the minimum validity level of auto-complete edges displayed when dragging a new edge
 
 External Services
 """""""""""""""""
@@ -104,10 +96,18 @@ External Services
 
 **Docker Hub Username** - The username to use when retrieving data on images stored on Docker Hub.
 
+**Explore Palettes Service** - The service hosting the repository from which palettes will be fetched by the 'Explore Palettes' feature
+
+**Explore Palettes Repository** - The repository from which palettes will be fetched by the 'Explore Palettes' feature
+
+**Explore Palettes Branch** - The branch of the repository from which palettes will be fetched by the 'Explore Palettes' feature
+
 Developer
 """""""""
 
-**Translate With New Categories** - Replace the old categories with new names when exporting. For example, replace 'Component' with 'PythonApp' category.
+**Show Developer Notifications** - EAGLE generates a number of messages intended to alert developers to unusual occurrences or issues. Enabling this setting displays those messages.
+
+**Show File Loading Warnings** - Display list of issues with files encountered during loading.
 
 **Open Translator In Current Tab** - When translating a graph, display the output of the translator in the current tab.
 
@@ -117,4 +117,10 @@ Developer
 
 **Print Undo State To JS Console** - Prints the state of the undo memory whenever a change occurs. The state is written to the browser's javascript console.
 
-**Use Old Output Format** - Prolong use of 'old' output format, with 'inputPorts' and 'outputPorts' arrays, while corresponding changes to DALiuGE are in progress.
+**Display all Category options** - Displays all category options when changing the category of a node
+
+**Allow modified graph translation** - Allow users to submit graphs for translation even when not saved or committed
+
+**Apply active graph config before translation** - Apply the active graph config to the graph before sending the graph for translation
+
+**Fetch repository for URLs** - Automatically fetch the contents of the object's repository when a graph/palette is specified in the URL

e2e/addingAndRemovingRepositories.spec.ts

@@ -12,9 +12,9 @@ test('Adding and Removing Repositories', async ({ page }) => {
   const REPO_BRANCH = "yan-812-2";
   const repoHTMLId = '#'+REPO_NAME.replace('/', '_') + "_" + REPO_BRANCH;
 
-  //making sure the repo doesnt exist for some reason, if it does, remove it
+  //making sure the repo doesn't exist for some reason, if it does, remove it
   if(await page.locator('#ICRAR_daliuge_yan-812-2').count() === 1){
-    await page.locator('.repoConatiner').filter({has:page.locator(repoHTMLId)}).getByText('eject').click()
+    await page.locator('.repoContainer').filter({has:page.locator(repoHTMLId)}).getByText('eject').click()
   }
 
   //click the add repository button

src/Eagle.ts

@@ -1901,7 +1901,7 @@ export class Eagle {
     }
 
     loadDefaultPalettes = () : void => {
-        // get collapsed/expanded state of palettes from html locaStorage
+        // get collapsed/expanded state of palettes from html local storage
         let templatePaletteExpanded: boolean = Setting.findValue(Setting.OPEN_TEMPLATE_PALETTE);
         let builtinPaletteExpanded: boolean = Setting.findValue(Setting.OPEN_BUILTIN_PALETTE);
         templatePaletteExpanded = templatePaletteExpanded === null ? false : templatePaletteExpanded;
@@ -2107,12 +2107,6 @@ export class Eagle {
     }
 
     _postLoadGraph = (file: RepositoryFile) : void => {
-        // set the active graph config (to the last graph config in the LG)
-        const graphConfigs: GraphConfig[] = this.logicalGraph().getGraphConfigs();
-
-        // if there is at least one graph config, make the last one active
-        // if there are no graph configs, make a new empty graph config and set active
-
         //needed when centering after init of a graph. we need to wait for all the constructs to finish resizing themselves
         setTimeout(function(){
             Eagle.getInstance().centerGraph()
@@ -2588,13 +2582,13 @@ export class Eagle {
     saveGraphScreenshot = async () : Promise<void> =>  {
         const eagle = Eagle.getInstance()
 
-        const mediaDevices = navigator.mediaDevices as any; //workaround to prevent a Typescript issue with giving getDisplayMedia funciton an option
+        const mediaDevices = navigator.mediaDevices as any; //workaround to prevent a Typescript issue with giving getDisplayMedia function an option
         const stream:MediaStream = await mediaDevices.getDisplayMedia({preferCurrentTab: true,selfBrowserSurface: 'include'});
 
         //prepare the graph for a screenshot
         eagle.centerGraph()
         eagle.setSelection(null,Eagle.FileType.Graph)
-        document.querySelector('body').style.cursor = 'none';//temporarily disabling the cursor so it doesnt appear in the screenshot
+        document.querySelector('body').style.cursor = 'none';//temporarily disabling the cursor so it doesn't appear in the screenshot
 
         try {        
             const width = stream.getVideoTracks()[0].getSettings().width
@@ -2616,8 +2610,8 @@ export class Eagle {
 
                 //cropping the ui, so the screenshot only includes the graph
                 const ctx = canvas.getContext('2d');
-                const realwidth = window.innerWidth
-                const divisor = realwidth/width
+                const realWidth = window.innerWidth
+                const divisor = realWidth/width
 
                 const lx = (eagle.leftWindow().size()+50)/divisor
                 const rx = (eagle.rightWindow().size()+50)/divisor
@@ -2801,7 +2795,7 @@ export class Eagle {
             return field.isReadonly();
         }
 
-        console.warn("something in value readonly permissions has one wrong!");
+        console.warn("something in value readonly permissions has gone wrong!");
         return true
     }
 
@@ -4274,7 +4268,7 @@ export class Eagle {
             let minX = Setting.findValue(Setting.LEFT_WINDOW_VISIBLE) ? this.leftWindow().size()+MARGIN: 0+MARGIN;
             let maxX = Setting.findValue(Setting.RIGHT_WINDOW_VISIBLE) ? $('#logicalGraphParent').width() - this.rightWindow().size() - MARGIN : $('#logicalGraphParent').width() - MARGIN;
             let minY = 0 + navBarHeight + MARGIN;
-            //using jquery here to get the bottom window height because it is internally saved in VH (percentage screen height). Doing it this way means we dont have to convert it to pixels
+            //using jquery here to get the bottom window height because it is internally saved in VH (percentage screen height). Doing it this way means we don't have to convert it to pixels
             let maxY = $('#logicalGraphParent').height() - $('#bottomWindow').height() - MARGIN + navBarHeight;
             if(increaseSearchArea){
                 minX = minX - 300

src/Setting.ts

@@ -292,12 +292,12 @@ export class Setting {
     static readonly ALLOW_COMPONENT_EDITING : string = "AllowComponentEditing";
     static readonly ALLOW_READONLY_PALETTE_EDITING : string = "AllowReadonlyPaletteEditing";
     static readonly ALLOW_EDGE_EDITING : string = "AllowEdgeEditing";
-    static readonly SHOW_NON_KEY_PARAMETERS : string = "ShowNonKeyParameters"; // TODO: maybe rename SHOW_NON_GRAPH_CONFIG_PARAMETERS?
+    static readonly SHOW_NON_CONFIG_PARAMETERS : string = "ShowNonConfigParameters";
     static readonly FILTER_NODE_SUGGESTIONS : string = "AutoSuggestDestinationNodes";
 
     static readonly ALLOW_PALETTE_EDITING : string = "AllowPaletteEditing";
     static readonly ALLOW_GRAPH_EDITING : string = "AllowGraphEditing";
-    static readonly ALLOW_SET_KEY_PARAMETER : string = "AllowSetKeyParameter"
+    static readonly ALLOW_MODIFY_GRAPH_CONFIG : string = "AllowModifyGraphConfig";
     static readonly STUDENT_SETTINGS_MODE : string = "StudentSettingsMode"
     static readonly VALUE_EDITING_PERMS : string = "ValueEditingPerms"
     static readonly AUTO_COMPLETE_EDGES_LEVEL : string = "AutoCompleteEdgesLevel"
@@ -309,8 +309,6 @@ export class Setting {
     static readonly EXPLORE_PALETTES_REPOSITORY : string = "ExplorePalettesRepository";
     static readonly EXPLORE_PALETTES_BRANCH : string = "ExplorePalettesBranch";
 
-    static readonly TRANSLATE_WITH_NEW_CATEGORIES: string = "TranslateWithNewCategories"; // temp fix for incompatibility with the DaLiuGE translator
-
     static readonly CREATE_APPLICATIONS_FOR_CONSTRUCT_PORTS: string = "CreateApplicationsForConstructPorts";
     static readonly DISABLE_JSON_VALIDATION: string = "DisableJsonValidation";
 
@@ -387,7 +385,7 @@ const settings : SettingsGroup[] = [
         "UI Options",
         () => {return true;},
         [
-            new Setting(true, "Show non key parameters", Setting.SHOW_NON_KEY_PARAMETERS, "Show additional parameters that are not marked as key parameters for the current graph",false, Setting.Type.Boolean, false,true,true,true,true),
+            new Setting(true, "Show non key parameters", Setting.SHOW_NON_CONFIG_PARAMETERS, "Show additional parameters that are not part of a graph configuration for the current graph",false, Setting.Type.Boolean, false,true,true,true,true),
             new Setting(false, "Show Developer Tab", Setting.SHOW_DEVELOPER_TAB, "Reveals the developer tab in the settings menu", false, Setting.Type.Boolean, false,false,false,false,true),
             new Setting(true, "Translator Mode", Setting.USER_TRANSLATOR_MODE, "Configure the translator mode", false, Setting.Type.Select, Setting.TranslatorMode.Minimal,Setting.TranslatorMode.Minimal,Setting.TranslatorMode.Normal,Setting.TranslatorMode.Normal,Setting.TranslatorMode.Expert, Object.values(Setting.TranslatorMode)),
             new Setting(true, "Graph Zoom Divisor", Setting.GRAPH_ZOOM_DIVISOR, "The number by which zoom inputs are divided before being applied. Larger divisors reduce the amount of zoom.", false, Setting.Type.Number,1000,1000,1000,1000,1000),
@@ -412,7 +410,7 @@ const settings : SettingsGroup[] = [
         [
             new Setting(true, "Allow Invalid edges", Setting.ALLOW_INVALID_EDGES, "Allow the user to create edges even if they would normally be determined invalid.", false, Setting.Type.Boolean, false, false, false, false, true),
             new Setting(true, "Allow Component Editing", Setting.ALLOW_COMPONENT_EDITING, "Allow the user to add/remove ports and parameters from components.",false, Setting.Type.Boolean,false, false, false, true,true),
-            new Setting(true, "Allow Set Key Parameter", Setting.ALLOW_SET_KEY_PARAMETER, "Allow the user to add/remove key parameter flags from parameters.", false, Setting.Type.Boolean,false, true, true, true,true),
+            new Setting(true, "Allow Modify Graph Configurations", Setting.ALLOW_MODIFY_GRAPH_CONFIG, "Allow the user to add/remove parameters from graph configurations.", false, Setting.Type.Boolean,false, true, true, true,true),
             new Setting(true, "Allow Graph Editing", Setting.ALLOW_GRAPH_EDITING, "Allow the user to edit and create graphs.", false, Setting.Type.Boolean, false, false, true, true, true),
             new Setting(true, "Allow Palette Editing", Setting.ALLOW_PALETTE_EDITING, "Allow the user to edit palettes.", false, Setting.Type.Boolean, false, false, false, true, true),
             new Setting(true, "Allow Readonly Palette Editing", Setting.ALLOW_READONLY_PALETTE_EDITING, "Allow the user to modify palettes that would otherwise be readonly.", false, Setting.Type.Boolean,false,false,false,false,true),

src/tutorials/graphBuilding.ts

@@ -116,7 +116,7 @@ newTut.newTutStep("Connecting nodes", "<em>Click and hold the output Port of the
 .setAlternateHighlightTargetFunc(function(){return $("#logicalGraphParent")})
 .setConditionFunction(function(eagle:Eagle){if(eagle.logicalGraph().getEdges().length != 0){return true}else{return false}}) //check if there are any edges present in the graph
 
-newTut.newTutStep("Graph Errors and warnings", "This is the error checking system, it is showing a checkmark, so we did everything correctly. If there are errors in the graph you are able to troubleshoot them by clicking here.", function(){return $("#checkGraphDone")})
+newTut.newTutStep("Graph Errors and warnings", "This is the error checking system, it is showing a check mark, so we did everything correctly. If there are errors in the graph you are able to troubleshoot them by clicking here.", function(){return $("#checkGraphDone")})
 
 // newTut.newTutStep("Graph Errors and warnings", "This modal may aid you in troubleshooting graphs. In this case these errors are all port type errors. Eagle can automatically fix errors such as these for you. To do this you can press 'F' in the graph or <em>click on 'Fix All'</em>", function(){return $("#errorModalFixAll")})
 // .setType(TutorialStep.Type.Press)

src/tutorials/graphConfigs.ts

@@ -1,7 +1,6 @@
 import { Eagle } from '../Eagle';
 import { RightClick } from '../RightClick';
-import { Tutorial, TutorialStep, TutorialSystem } from '../Tutorial';
-import { SideWindow } from '../SideWindow';
+import { TutorialStep, TutorialSystem } from '../Tutorial';
 import { Setting } from '../Setting';
 
 const newTut = TutorialSystem.newTutorial('Graph Configurations', 'An introduction to using graph configurations.')

src/tutorials/quickStart.ts

@@ -13,12 +13,12 @@ newTut.newTutStep("Right Panel", "Multipurpose panel with several tabs offering
 newTut.newTutStep("User Interface Element Tooltips", "Much of Eagle's interface is using icons. You can always hover over the icons and most of the other elements to get more information on what they do.", function(){return $("#navbarSupportedContent .btn-group")})
     .setBackPreFunction(function (eagle) {eagle.closeShortcuts()})
 
-newTut.newTutStep("Keyboard Shortcuts", "Many of the major functions are available through keyboard shurtcuts and you can find the mapping here. To access this modal, find it in the navbar under 'Help' or simply press 'K'.", function(){return $("#shortcutsModal")})
+newTut.newTutStep("Keyboard Shortcuts", "Many of the major functions are available through keyboard shortcuts and you can find the mapping here. To access this modal, find it in the navbar under 'Help' or simply press 'K'.", function(){return $("#shortcutsModal")})
     .setWaitType(TutorialStep.Wait.Modal)
     .setBackPreFunction(function(eagle){eagle.openShortcuts()})
     .setPreFunction(function(eagle){eagle.openShortcuts()})
 
-newTut.newTutStep("Click To Open Settings", "The settings modal allows to cusomize EAGLE's user experience. By default, EAGLE is simplified by hiding a lot of functionality via the UI modes. To find out more check our <a target='_blank' href='https://eagle-dlg.readthedocs.io/en/master/settings.html#settings'>settings documentation</a>. <em>To continue the tutorial please click the highlighted settings icon button!</em>", function(){return $("#settings")})
+newTut.newTutStep("Click To Open Settings", "The settings modal allows to customize EAGLE's user experience. By default, EAGLE is simplified by hiding a lot of functionality via the UI modes. To find out more check our <a target='_blank' href='https://eagle-dlg.readthedocs.io/en/master/settings.html#settings'>settings documentation</a>. <em>To continue the tutorial please click the highlighted settings icon button!</em>", function(){return $("#settings")})
     .setType(TutorialStep.Type.Press)
     .setPreFunction(function(eagle){eagle.closeShortcuts();})
     .setBackPreFunction(function(eagle){eagle.closeSettings();})