Dash Ace

Dash Ace is a Plotly Dash component of Ace editor that wraps up a react ace editor

It supports the following four modes: Python, SQL, Text, Norm and several themes: github, monokai, tomorrow, twilight, textmate. If you want other languages and themes, you can fork the repo and modify the code. Dynamic loading of modes and themes are not supported yet.

Installation

pip install dash-ace-persitent

Example

The following is a simple example using this component.

import dash
import dash_ace
import dash_html_components as html
import flask
from flask import jsonify
from flask_cors import CORS

server = flask.Flask(__name__)
CORS(server)

app = dash.Dash(__name__,
                server=server,
                routes_pathname_prefix='/dash/'
                )

app.layout = html.Div([
    dash_ace.DashAceEditor(
        id='input',
        value='def test(a: int) -> str : \n'
              '    return f"value is {a}"',
        theme='github',
        mode='python',
        tabSize=2,
        enableBasicAutocompletion=True,
        enableLiveAutocompletion=True,
        autocompleter='/autocompleter?prefix=',
        placeholder='Python code ...'
    )
])


@server.route('/autocompleter', methods=['GET'])
def autocompleter():
    return jsonify([{"name": "Completed", "value": "Completed", "score": 100, "meta": "test"}])


if __name__ == '__main__':
    app.run_server(debug=True)

Properties

| Prop | Default | Type | Description | | ------------------------- | -------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | 'ace-editor' | str | Unique Id to be used for the editor | | placeholder | 'Type code here ...' | str | Placeholder text to be displayed when editor is empty | | mode | 'python' | str | Language for parsing and code highlighting | | syntaxKeywords | {} | dict | Custom language keywords, see format | | syntaxFolds | None | str | Custom language folding character to fold code | | theme | 'github' | str | theme to use | | value | '' | str or List[str] | values you want to populate in the code | | className | None | str | custom className | | fontSize | 14 | int | pixel value for font-size | | showGutter | True | bool | show gutter | | showPrintMargin | True | bool | show print margin | | highlightActiveLine | True | bool | highlight active line | | focus | False | bool | whether to focus | | cursorStart | 1 | int | the location of the cursor | | wrapEnabled | False | bool | Wrapping lines | | readOnly | False | bool | make the editor read only | | orientation | 'below' | str | diff view orientation, 'below' or 'beside' | | minLines | None | int | Minimum number of lines to be displayed | | maxLines | None | int | Maximum number of lines to be displayed | | enableBasicAutocompletion | False | bool | Enable basic autocompletion | | enableLiveAutocompletion | False | bool | Enable live autocompletion | | autocompleter | None | str | Custom auto completer from a language server | | prefixLine | False | bool | Custom auto completer takes the current line as the prefix (False to take the current word) | | triggerWords | None | list | The list of possible words before the cursor can trigger the custom auto completer (default to any words) | | enableSnippets | False | bool | Enable snippets | | tabSize | 4 | int | tabSize | | debounceChangePeriod | None | int | A debounce delay period for the onChange event | | editorProps | None | dict | properties to apply directly to the Ace editor instance | | setOptions | None | dict | options to apply directly to the Ace editor instance | | commands | None | list | new commands to add to the editor | | annotations | None | list | annotations to show in the editor i.e. [{ row: 0, column: 2, type: 'error', text: 'Some error.'}], displayed in the gutter | | markers | None | list | markers to show in the editor, i.e. [{ startRow: 0, startCol: 2, endRow: 1, endCol: 20, className: 'error-marker', type: 'background' }]. Make sure to define the class (eg. ".error-marker") and set position: absolute for it. | | style | None | dict | camelCased properties Get started with: |

Custom Language

Dash ace editor has a simple mechanism to create a custom mode that extends from python language. The syntax highlighting allows custom keywords to be defined in syntaxKeywords. Additional folding characters can be defined in syntaxFolds. The following is a custom syntax configuration for Norm.

    syntaxKeywords = {
        "variable.language": "this|that|super|self|sub|",
        "support.function": "enumerate|range|pow|sum|abs|max|min|argmax|argmin|len|mean|std|median|all|any|",
        "support.type": "String|Integer|Bool|Float|Image|UUID|Time|DateTime|Type|",
        "storage.modifier": "parameter|atomic|primary|optional|id|time|asc|desc|",
        "constant.language": "true|false|none|na|",
        "keyword.operator": "and|or|not|except|unless|imply|in|",
        "keyword.control": "as|from|to|import|export|return|for|exist|with|"
    }

    syntaxFolds = '\\:='

The syntax rules can be created and tested on Mode Creator.

Custom Auto Completer

A language server can provide a better intellisense service to recommend the most relevant keywords, types and variables. autocompleter='/autocompleter?prefix=' configures the editor to consult the API given a prefix. The returned list of recommended words has the schema of name: str, value: str, score: int, meta: str. The popup menu in UI shows value and meta and order the recommended words by the score. The one with the highest score lists at the top.

Ace editor autocompletion by default takes the word at the cursor as the prefix. Setting prefixLine=True allows the custom auto completer to receive the entire line before the cursor as the prefix. Note that ace editor does not invoke live auto completion for anything other than words. Press Ctrl+Space to show the recommended completions if you would like to access members like test. or to declare types like test:.

Hitting the language server for every key press can overload the server. Setting triggerWords to explicitly invoke custom auto completion is highly recommended. Note that symbols need to be escaped, e.g., \\., because these words will be used to compose a regex directly. See javascript regex for more details.

The following is a complete example:

    dash_ace.DashAceEditor(
        id='input',
        value='test(a: Integer) -> String := \n'
              '    return f"value is {a}"',
        theme='github',
        mode='norm',
        syntaxKeywords=syntaxKeywords,
        syntaxFolds=syntaxFolds,
        tabSize=2,
        enableBasicAutocompletion=True,
        enableLiveAutocompletion=True,
        autocompleter='/autocompleter?prefix=',
        prefixLine=True,
        triggerWords=[':', '\\.', '::'], # consult the completer for types, members and inheritances
        placeholder='Norm code ...'
    ),

Diff View

If the value is provided as an array of two strings, editor splits into two views to show the difference between two pieces of codes.

    dash_ace.DashAceEditor(
        id='input',
        value=['test(a: Integer) -> String := \n return f"value is {a}"',
               'test(a: Integer) -> String := return f"valus is not {a}"']
        theme='github',
        mode='norm',
        syntaxKeywords=syntaxKeywords,
        syntaxFolds=syntaxFolds,
        tabSize=2,
        orientation='below',
        enableBasicAutocompletion=True,
        enableLiveAutocompletion=True,
        autocompleter='/autocompleter?prefix=',
        prefixLine=True,
        triggerWords=[':', '\\.', '::'], # consult the completer for types, members and inheritances
        placeholder='Norm code ...'
    ),

The property orientation sets the comparisons horizontal or vertical.

TODO

1. Support custom modes extended from javascript
2. Support dynamic loading of modes and themes
3. Support code analysis customizations to indicate errors and suggest changes

Contributing

See CONTRIBUTING.md

Developments

Follow these instructions to develop dash ace

Install dependencies

If you have selected install_dependencies during the prompt, you can skip this part.

1. Install npm packages

   $ npm install

2. Create a virtual env and activate.

   $ virtualenv venv
   $ . venv/bin/activate

   Note: venv\Scripts\activate for windows

3. Install python packages required to build components.

   $ pip install -r requirements.txt

4. Install the python packages for testing (optional)

   $ pip install -r tests/requirements.txt

Modify src/lib/components/DashAceEditor.react.js.

• The demo app is in src/demo and you will import your example component code into your demo app.
• Test your code in a Python environment:
  1. Build your code

     $ npm run build

  2. Run javascript demo

     $ npm start

  3. Run and modify the usage.py sample dash app:

     $ python usage.py

• Write tests for your component.
  • A sample test is available in tests/test_usage.py, it will load usage.py and you can then automate interactions with selenium.
  • Run the tests with $ pytest tests.
  • The Dash team uses these types of integration tests extensively. Browse the Dash component code on GitHub for more examples of testing (e.g. https://github.com/plotly/dash-core-components)
• Add custom styles to your component by putting your custom CSS files into your distribution folder (dash_ace_persistent).
  • Make sure that they are referenced in MANIFEST.in so that they get properly included when you're ready to publish your component.
  • Make sure the stylesheets are added to the _css_dist dict in dash_ace_persistent/__init__.py so dash will serve them automatically when the component suite is requested.
• Review your code