neo4j-labs · nielsdejong · Nov 16, 2023 · Oct 10, 2023 · Oct 27, 2023 · Oct 27, 2023
diff --git a/changelog.md b/changelog.md
@@ -1,3 +1,36 @@
+## NeoDash 2.4.0
+NeoDash 2.4 is out! 🎂 This release packs a ton of new features, as well as improvements to the existing visualizations.
+
+Key new features:
+- A new sidebar with support for managing, save and load multiple dashboards directly from the UI.
+   [#657](https://github.com/neo4j-labs/neodash/pull/657)
+- Added **Forms** as a new extension. Forms let you combine multiple parameter selectors in one card and have users edit/submit data to Neo4j.  [#568](https://github.com/neo4j-labs/neodash/pull/568)
+- Added a new advanced visualization type: Gantt charts. [#684](https://github.com/neo4j-labs/neodash/pull/684)
+- Doubled the grid resolution for dashboards, giving you more freedom to arrange visualizations. [#682](https://github.com/neo4j-labs/neodash/pull/682)
+- Several improvements for the natural language queries extension - including customizable prompting, and faster schema retrieval. [#600](https://github.com/neo4j-labs/neodash/pull/600)
+
+Other improvements:
+- Support for multiselect checkboxes as a report action for tables. [#688](https://github.com/neo4j-labs/neodash/pull/688/commits)
+- Added keyboard shortcuts (CMD/CTRL+Enter) for running Cypher queries from the editor. [#694](https://github.com/neo4j-labs/neodash/pull/694/)
+- Added new experimental graph layouts (trees in various directions), with customizable level distance. [#690](https://github.com/neo4j-labs/neodash/pull/690)
+- Increased customizability for the Pie chart's styling.  [#638](https://github.com/neo4j-labs/neodash/pull/638/)
+- Fixed issues with parameter selector: Better handling of integer / long parameters and processing external updates. [#641](https://github.com/neo4j-labs/neodash/pull/641/)
+- Improvements on text readability for the experimental dark mode. [#668](https://github.com/neo4j-labs/neodash/pull/668/)
+- UX improvements on database connection interface. [#675](https://github.com/neo4j-labs/neodash/pull/675/)
+- Added option to provide a custom message when no data is returned by a report. [#683](https://github.com/neo4j-labs/neodash/pull/683/)
+- Fixed issue where column names were not hidden correctly. [#685](https://github.com/neo4j-labs/neodash/pull/685/commits)
+
+Thanks to all the contributors for this release: 
+[alfredorubin96](https://github.com/alfredorubin96),
+[AleSim94](https://github.com/AleSim94),
+[BennuFire](https://github.com/BennuFire),
+[jacobbleakley-neo4j](https://github.com/jacobbleakley-neo4j),
+[hugorplobo](https://github.com/hugorplobo),
+[brahmprakashMishra](https://github.com/brahmprakashMishra),
+[m-o-n-i-s-h](https://github.com/m-o-n-i-s-h),
+[JonanOribe](https://github.com/JonanOribe),
+[nielsdejong](https://github.com/nielsdejong)
+
 ## NeoDash 2.3.5
 This is a bugfix / stability release directly following 2.3.4.
 

diff --git a/cypress/e2e/start_page.cy.js b/cypress/e2e/start_page.cy.js
@@ -8,6 +8,7 @@ import {
   loadDashboardURL,
   sankeyChartCypherQuery,
   gaugeChartCypherQuery,
+  formCypherQuery,
 } from '../fixtures/cypher_queries';
 
 const WAITING_TIME = 20000;
@@ -86,7 +87,7 @@ describe('NeoDash E2E Tests', () => {
     cy.get('main .react-grid-item:eq(2) .MuiDataGrid-columnHeaders', { timeout: WAITING_TIME })
       .should('contain', 'title')
       .and('contain', 'released')
-      .and('not.contain', '__id');
+      .and('contain', '__id');
     cy.get('main .react-grid-item:eq(2) .MuiDataGrid-virtualScroller .MuiDataGrid-row').should('have.length', 5);
     cy.get('main .react-grid-item:eq(2) .MuiDataGrid-footerContainer').should('contain', '1–5 of 8');
     cy.get('main .react-grid-item:eq(2) .MuiDataGrid-footerContainer button[aria-label="Go to next page"]').click();
@@ -244,13 +245,28 @@ describe('NeoDash E2E Tests', () => {
     cy.get('main .react-grid-item:eq(2) .MuiCardContent-root h1', { timeout: 45000 }).should('have.text', 'Hello');
   });
 
-  // it('creates a radar report', () => {
-  //     // TODO - create a test for radar.
-  // })
+  it.skip('creates a form report', () => {
+    enableFormsExtension();
+    checkInitialState();
+    createReportOfType('Form', formCypherQuery, true, false);
+    cy.get('main .react-grid-item:eq(2) .form-add-parameter').click();
+    cy.wait(200);
+    cy.get('#autocomplete-label-type').type('Movie');
+    cy.get('#autocomplete-label-type-option-0').click();
+    cy.wait(200);
+    cy.get('#autocomplete-property').type('title');
+    cy.get('#autocomplete-property-option-0').click();
 
-  // it('creates a sankey report', () => {
-  //     // TODO - create a test for sankey charts.
-  // })
+    cy.get('.ndl-dialog-close').click();
+
+    cy.get('main .react-grid-item:eq(2) button[aria-label="run"]').scrollIntoView().should('be.visible').click();
+    cy.wait(500);
+    cy.get('#autocomplete').type('The Matrix');
+    cy.get('#autocomplete-option-0').click();
+    cy.get('#form-submit').click();
+    cy.wait(500);
+    cy.get('.form-submitted-message').should('have.text', 'Form Submitted.Reset Form');
+  });
 
   // Test load stress-test dashboard from file
   // TODO - this test is flaky, especially in GitHub actions environment.
@@ -285,6 +301,14 @@ function enableAdvancedVisualizations() {
   cy.wait(200);
 }
 
+function enableFormsExtension() {
+  cy.get('main button[aria-label="Extensions').should('be.visible').click();
+  cy.get('#checkbox-forms').scrollIntoView();
+  cy.get('#checkbox-forms').should('be.visible').click();
+  cy.get('.ndl-dialog-close').scrollIntoView().should('be.visible').click();
+  cy.wait(200);
+}
+
 function selectReportOfType(type) {
   cy.get('main .react-grid-item button[aria-label="add report"]').should('be.visible').click();
   cy.get('main .react-grid-item')
@@ -298,7 +322,7 @@ function selectReportOfType(type) {
   cy.wait(100);
 }
 
-function createReportOfType(type, query, fast = false) {
+function createReportOfType(type, query, fast = false, run = true) {
   selectReportOfType(type);
   if (fast) {
     cy.get('main .react-grid-item:eq(2) .ReactCodeMirror').type(query, { delay: 1, parseSpecialCharSequences: false });
@@ -308,8 +332,9 @@ function createReportOfType(type, query, fast = false) {
   cy.wait(400);
 
   cy.get('main .react-grid-item:eq(2)').contains('Advanced settings').click();
-
-  cy.get('main .react-grid-item:eq(2) button[aria-label="run"]').click();
+  if (run) {
+    cy.get('main .react-grid-item:eq(2) button[aria-label="run"]').click();
+  }
 }
 
 function checkInitialState() {

diff --git a/cypress/fixtures/cypher_queries.js b/cypress/fixtures/cypher_queries.js
diff --git a/docs/README.md b/docs/README.md
@@ -6,7 +6,7 @@ An external workflow picks up this directory, embeds it into the Neo4j docs, and
 ```
 https://neo4j.com/labs/neodash/{version}
 ```
-For example: https://neo4j.com/labs/neodash/2.3
+For example: https://neo4j.com/labs/neodash/2.4
 
 ## Local Build
 To compile and view the documentation locally, navigate to this (`./docs`) folder and run:

diff --git a/docs/antora.yml b/docs/antora.yml
@@ -1,13 +1,13 @@
 name: neodash
-version: 2.3
+version: 2.4
 title: NeoDash
 start_page: ROOT:index.adoc
 nav:
   - modules/ROOT/nav.adoc
 
 asciidoc:
   attributes:
-    docs-version: 2.3
+    docs-version: 2.4
     page-product: NeoDash
     page-type: NeoDash Manual
     page-canonical-root: /labs
diff --git a/docs/modules/ROOT/images/createform.png b/docs/modules/ROOT/images/createform.png
diff --git a/docs/modules/ROOT/images/formbutton.png b/docs/modules/ROOT/images/formbutton.png
diff --git a/docs/modules/ROOT/images/forms.png b/docs/modules/ROOT/images/forms.png
diff --git a/docs/modules/ROOT/images/formselector.png b/docs/modules/ROOT/images/formselector.png
diff --git a/docs/modules/ROOT/images/formsimple.png b/docs/modules/ROOT/images/formsimple.png
diff --git a/docs/modules/ROOT/images/gantt.png b/docs/modules/ROOT/images/gantt.png
diff --git a/docs/modules/ROOT/images/llm-examples.png b/docs/modules/ROOT/images/llm-examples.png
diff --git a/docs/modules/ROOT/images/select-multiple-table.png b/docs/modules/ROOT/images/select-multiple-table.png
diff --git a/docs/modules/ROOT/images/select-single-table.png b/docs/modules/ROOT/images/select-single-table.png
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
@@ -16,11 +16,13 @@
 *** xref:user-guide/reports/treemap.adoc[Treemap]
 *** xref:user-guide/reports/radar.adoc[Radar Chart]
 *** xref:user-guide/reports/sankey.adoc[Sankey Chart]
+*** xref:user-guide/reports/gantt.adoc[Gantt Chart]
 *** xref:user-guide/reports/map.adoc[Map]
 *** xref:user-guide/reports/single-value.adoc[Single Value]
 *** xref:user-guide/reports/gauge-chart.adoc[Gauge Chart]
 *** xref:user-guide/reports/raw-json.adoc[Raw JSON]
 *** xref:user-guide/reports/parameter-select.adoc[Parameter Select]
+*** xref:user-guide/reports/form.adoc[Form]
 *** xref:user-guide/reports/iframe.adoc[iFrame]
 *** xref:user-guide/reports/markdown.adoc[Markdown]
 ** xref:user-guide/publishing.adoc[Publishing]
@@ -29,7 +31,8 @@
 *** xref:user-guide/extensions/advanced-visualizations.adoc[Advanced Visualizations]
 *** xref:user-guide/extensions/rule-based-styling.adoc[Rule-Based Styling]
 *** xref:user-guide/extensions/report-actions.adoc[Report Actions]
-*** xref:user-guide/extensions/natural-language-queries.adoc[Natural Language Queries]
+*** xref:user-guide/extensions/natural-language-queries.adoc[Text2Cypher - Natural Language Queries]
+*** xref:user-guide/extensions/forms.adoc[Forms]
 ** xref:user-guide/faq.adoc[FAQ]
 * xref:developer-guide/index.adoc[Developer Guide]
 ** xref:developer-guide/build-and-run.adoc[Build & Run]

diff --git a/docs/modules/ROOT/pages/developer-guide/deploy-a-build.adoc b/docs/modules/ROOT/pages/developer-guide/deploy-a-build.adoc
@@ -37,7 +37,7 @@ Depending on the webserver type and version, this could be different directory.
 As an example - to copy the files to an nginx webserver using `scp`:
 
 ```bash
-scp neodash-2.3.5 username@host:/usr/share/nginx/html
+scp neodash-2.4.0 username@host:/usr/share/nginx/html
 ```
 
 NeoDash should now be visible by visiting your (sub)domain in the browser.

diff --git a/docs/modules/ROOT/pages/developer-guide/state-management.adoc b/docs/modules/ROOT/pages/developer-guide/state-management.adoc
@@ -11,7 +11,7 @@ structure:
 {
   "dashboard": {
     "title": "My Dashboard Name",
-    "version": "2.3",
+    "version": "2.4",
     "settings": {
       "pagenumber": 0,
       "editable": true,
@@ -56,7 +56,7 @@ dashboard. Take the following simple dashboard as an example.
 {
   "dashboard": {
     "title": "A Simple Dashboard",
-    "version": "2.3",
+    "version": "2.4",
     "settings": {
       "pagenumber": 0,
       "editable": true,

diff --git a/docs/modules/ROOT/pages/user-guide/extensions/advanced-visualizations.adoc b/docs/modules/ROOT/pages/user-guide/extensions/advanced-visualizations.adoc
@@ -8,9 +8,10 @@ The following visualizations are part of this extension:
 
 - A link:../../reports/sankey[Sankey Chart] to visualize flows.
 - Three charts to plot hierarchical data (link:../../reports/sunburst[Sunburst], link:../../reports/circle-packing[Circle Packing], link:../../reports/treemap[Treemap])
-- A link:../../reports/gauge-chart[Gauge Chart] to show percentages 
+- A link:../../reports/gauge-chart[Gauge Chart] to show percentages.
 - An link:../../reports/choropleth[Choropleth] to visualize numeric, country-data.
 - An link:../../reports/areamap[Area Map] to show an interactive world map, annotated with numeric country / region values.
+- A link:../../reports/gantt[Gantt] chart to visualize dependencies between tasks. 
 - A link:../../reports/radar[Radar Chart] to create a radial view of multiple categoric values.
 
 image::advanced-visualizations.png[Advanced Visualizations]
diff --git a/docs/modules/ROOT/pages/user-guide/extensions/forms.adoc b/docs/modules/ROOT/pages/user-guide/extensions/forms.adoc
@@ -0,0 +1,13 @@
+= Forms
+
+The 'forms' extension lets you combine different parameter selectors to update / modify your graph data.
+Update queries are predefined by the dashboard builder, and the user is limited to specifying the parameters for the query only.
+
+See link:../../reports/form[Form] on how to create, configure, and use forms.
+
+> Keep in mind that data-altering forms require your Neo4j user to have **write-access** to the graph. Make sure you give access to a select group of power-users only.
+
+
+
+
+image::forms.png[Forms]
diff --git a/docs/modules/ROOT/pages/user-guide/extensions/index.adoc b/docs/modules/ROOT/pages/user-guide/extensions/index.adoc
@@ -17,7 +17,8 @@ The currently available extensions in NeoDash are:
 - link:advanced-visualizations[Advanced Visualizations]
 - link:rule-based-styling[Rule-based Styling]
 - link:report-actions[Report Actions]
-- link:natural-language-queries[Natural Language Queries]
+- link:natural-language-queries[Text2Cypher - Natural Language Queries]
+- link:forms[Forms]
 
 == Types of Extensions
 

diff --git a/docs/modules/ROOT/pages/user-guide/extensions/natural-language-queries.adoc b/docs/modules/ROOT/pages/user-guide/extensions/natural-language-queries.adoc
@@ -1,25 +1,23 @@
-= Natural Language Query Generation in NeoDash!
+= Text2Cypher - Natural Language Queries
 Use natural language to generate Cypher queries in NeoDash. Connect to an LLM through an API, and let NeoDash use your database schema + the report types to generate queries automatically.
 
-== Natural Language Queries
-Natural Language Queries feature allows users to interact with NeoDash using natural language to generate Cypher queries for querying Neo4j graph databases. 
+== How it works
+This extension feature allows users to interact with NeoDash using natural language to generate Cypher queries for querying Neo4j graph databases. 
 This integration leverages Language Models (LLMs) to interpret user inputs and generate Cypher queries based on the provided schema definition.
 
 == Configuration
 To enable Natural Language Queries in NeoDash, follow these configuration steps:
 
 1. Open NeoDash and navigate to the "Extensions" section in the left sidebar.
-2. Locate the "Natural Language Queries" extension and click on it to activate it.
-3. Once activated, a new button will appear in the sidebar(see image below). Click on the button to open the configuration window.
+2. Locate the "Text2Cypher" extension and click on it to activate it.
+3. Once activated, a new button will appear on top of the screen, with a red exclamation mark (⚠️). Click this button.
 4. In the configuration window, you will be prompted to provide the necessary information to connect to the Language Model (LLM). Enter the model provider, API key, deployment url if needed by the model provider, and select the desired model to use.
 5. After providing the required information, click on the "Start Querying" button to finalize the configuration.
 
-image::extensionbutton.png[Extension Button enables Natural Language Queries button in the sidebar]
-
 image::llmconfiguration.png[Configuration settings for the Natural Language Queries extension]
 
 == Usage
-Once the Natural Language Queries extension is configured, you can start using it in your NeoDash reports. Here's how:
+Once the extension is configured, you can start using it in your NeoDash reports. Here's how:
 
 1. Open the Report settings for the desired report.
 2. In the report settings, you will find a toggle switch located above the editor. This switch allows you to toggle between Cypher and English languages.
@@ -33,7 +31,21 @@ This allows you to review and modify the generated Cypher query before execution
 
 image::englisheditor.png[Example of the English editor in NeoDash]
 
-=== Here is how it works behind the scenes:
+== Improving Accuracy with Custom Prompting
+To boost the accuracy of the language model, you can provide your own example queries to be fed into the prompt.
+Specifying queries specific to your data model & use-cases can significantly improve the quality of Text2Cypher translations.
+
+To access the model examples screen, open up the settings for the extensions.
+After specifying the provider and model, click the "Tweak Prompts" button on the bottom-left of the window.
+This leads you to the example interface:
+
+image::llm-examples.png[Custom Examples for your prompt]
+
+In this interface, you can specify one or more examples that are sent to the language model.
+An example consists of both a Cypher query, and a natural language equivalent of that query.
+You can create as many examples as you want, but keeping them close to your user queries will yield best results.
+
+== Underlying Functionality
 * Retrieve the Schema: The system prompts at the beginning of the interaction to retrieve the database schema. This ensures that the generated queries adhere to the provided schema and available relationship types and properties.
 
 * Prompting in English: Once the schema is retrieved, you can start prompting your queries in plain English. NeoDash, powered by the LLM, will interpret your English query and generate the corresponding Cypher query based on the provided schema.

diff --git a/docs/modules/ROOT/pages/user-guide/reports/form.adoc b/docs/modules/ROOT/pages/user-guide/reports/form.adoc
@@ -0,0 +1,75 @@
+= Form
+
+A form is a special type of report that lets users run predefined, parameterized queries.
+A single form can consist of:
+
+- Zero or more link:../parameter-select[parameter selectors].
+- A button that triggers submitting the form.
+
+When creating a form, you write the Cypher query that is called when the submit button is clicked.
+This query can then use the parameters specified as input. The image below provides an example of a form. On the left, the settings used to define the form, on the right, the final form as visible to the user.
+
+image::createform.png[Complex Form]
+
+
+== Examples
+
+=== Simple Button
+
+A form without parameters is a button that runs a specified query. 
+One or more buttons can be used to perform simple operations in the graph. 
+Below is an example of a simple button form. On submitting, the following query is executed:
+
+[source,cypher]
+----
+MERGE (c:Counter)
+SET c.count = c.count+1
+----
+
+image::formbutton.png[Button Form]
+
+=== A Parameter and a Button
+To create a form with dynamic input, use both a parameter and a button. 
+Below is an example of a form that deletes nodes from the graph. On submit, the following query is executed:
+
+[source,cypher]
+----
+MATCH (p:Person)
+WHERE p.name = $neodash_person_name
+DETACH DELETE p
+----
+
+image::formsimple.png[Simple Form]
+
+=== Parameters Only
+
+By hiding the submit button, a form can also be used as a space-efficient way to embed multiple parameter selectors.
+Disable `Has Submit Button` in the report's advanced settings, and add two or more parameter selectors to the form.
+
+image::formselector.png[Parameter-only Form]
+
+
+== Advanced Settings
+
+[width="100%",cols="19%,17%,26%,38%",options="header",]
+|===
+|Name |Type |Default Value |Description
+
+|Form Button Text |text |Submit |Text displayed on the button that submits the form.
+
+|Reset Button Text | text |Reset Form |Text displayed on the button that resets the form to data entry mode.
+
+|Confirmation Message | multiline text |Form submitted. |Text displayed to the user after the form is submitted successfully.
+
+|Clear parameters after submit |on/off |on | Clears all dashboard parameters in the form after submitting.
+
+|Has Submit Button |on/off |on | When enabled, lets the user submit the form with a button. Disabling turns the form into parameters-only mode.
+
+|Has Reset Button |on/off |on |When enabled, lets the user reset the form to enter more data. 
+
+|Has Submit Message |on/off |on |When enabled, the user to a seperate screen after submitting the form. Else, always stay in data-entry mode.
+
+|Report Description |markdown text | | When specified, adds another button the report header that opens a pop-up. This pop-up contains the rendered markdown from this setting. 
+
+
+|===