==============
Presto Console
==============

Presto comes with a built-in dashboard where you can check the cluster’s information such as running SQL queries,
query details, and resource group information. Presto Console comprises a series of HTML pages and JavaScript
files which invokes the Presto APIs served by the coordinator. The UI components are written in
`React JS <https://react.dev/>`_ and built by `webpack <https://webpack.js.org/>`_. Here are the guidances
for Presto Console development.

Code
----

The Presto Console code is in the ``presto-ui/src`` directory in the root of the
Presto source tree. This directory is referred to as ``Presto Console root`` in this document and contains:

- HTML files: the static pages for the Presto Console.
- ``src/static`` folder: contains static assets such as the Presto favicon, logo, and Presto CSS file.
- ``src/static/dev`` directory: contains ``Query Viewer`` page and its JS file.
- ``src/static/vendor`` directory: contains third-party JS/CSS libraries that are used by UI components.
- ``src/`` directory: contains the UI components and webpack config file.

Prerequisites
-------------

- `yarn <https://yarnpkg.com/>`_: A package manager for the Node.js project. Yarn is used to manage the packages
  used by the UI components and the scripts to compile and generate the JavaScript files.

UI components
-------------

All of the UI components are in the ``src`` folder under the ``Presto Console root`` directory.  These components are
written in `JSX <https://react.dev/learn/writing-markup-with-jsx>`_ using React JS and named with the ``.jsx``
file extension.

Please follow these rules for composing UI components:

- Define components as JavaScript functions instead of classes: Some old components are written in classes and
  must be refactored into functions. For new components, please use function components. Check
  `Defining a component  <https://react.dev/learn/your-first-component#defining-a-component>`_ for detailed information.
- Bootstrap: the current code base is using Bootstrap v3.3.5. You can find the CSS and components it provides
  in the `Bootstrap Getting Started <https://bootstrapdocs.com/v3.3.5/docs/getting-started/>`_.
- Use `flow <https://flow.org/>`_ as the static type checker:  Add ``//@flow`` at the beginning of the ``.jsx`` file
  to enable the type checker and use ``yarn run flow`` to run the flow checker.

Web Dev Server
--------------

To speed up the UI development, use the web dev server that webpack provides to verify new UI components or updates
that you are working on.

- First, you need a Presto server that serves all the API calls needed by the Presto Console. For example, you can run the
  Presto coordinator + worker locally.
- Run ``yarn serve`` to spin up the web dev server on the ``src`` directory. By default, it proxies the API calls to
  ``localhost:8080``. If your Presto server is listening on a different IP address or port, you can specify the IP address
  and port number by adding ``--env=apiHost=<IP address>`` and ``--env=apiPort=<port number>`` arguments to the yarn command.
  Pay attention to the output messages and look for messages like ``[webpack-dev-server] Loopback: http://localhost:8081/``.
  It tells you where to access the web dev server.

The web dev server watches the entries listed in ``webpack.config.js``, compiles, and serves the HTML pages in the ``Presto Console root``
directory.

Add a New Page
--------------

To add a new page:

1. Add a new HTML page to the ``Presto Console root`` directory. Inside the HTML page, add the necessary ``<link>`` tags to include
   the needed CSS and JavaScript libraries from the ``vendor`` directory or external public CDN URIs. Inside the ``<body>`` element,
   add an ``<div>`` element with the ``id`` attribute as the placeholder for the UI component you are going to create
   followed by a ``<script>`` tag to point to the new JavaScript file that would be generated by the webpack at the ``dist`` directory.
   Check ``query.html`` as an example.
2. Add a new ``.jsx`` file under the ``src`` directory and a corresponding entry in the ``webpack.config.js``. This ``.jsx`` file is
   compiled into a ``.js`` file and stored under the ``dist`` directory. It is used by the HTML file you created in the previous step and
   serves as the root component for the new UI components. Check ``src/query.jsx`` as an example.
3. Add new components and store them in the ``src/components`` directory. Check ``src/components/QueryDetail.jsx`` as an example.
4. Use the web dev server to test and verify the new page and components.
5. Use the ``yarn run flow`` command to run the static type checker.
6. Use the ``yarn install`` command to generate the JavaScript files to the ``dist`` directory.
