spruce up phenogrid docs

README.md

@@ -2,9 +2,10 @@
 
 The Monarch Initiative is an extensive knowledge graph and ecosystem of tools made for the benefit of clinicians, researchers, and scientists. The knowledge graph consists of millions of entities – genes, diseases, phenotypes, and many more – imported from dozens of sources.
 
-We welcome the contributions of the community to help us maintain and improve the knowledge graph and the tools that use it. To help get started on contributing to the Monarch Initiative, please see our CONTRIBUTING.md file.
+We welcome the contributions of the community to help us maintain and improve the knowledge graph and the tools that use it. To help get started on contributing to the Monarch Initiative, please see our [CONTRIBUTING.md](./CONTRIBUTING.md) file.
 
 # Monarch App
+
 [![documentation](https://img.shields.io/badge/-Documentation-purple?logo=read-the-docs&logoColor=white&style=for-the-badge)](https://monarch-initiative.github.io/monarch-documentation/)  
 ![](https://github.com/monarch-initiative/monarch-app/actions/workflows/test-backend.yaml/badge.svg)
 ![](https://github.com/monarch-initiative/monarch-app/actions/workflows/test-frontend.yaml/badge.svg)
@@ -18,9 +19,11 @@ as well as `monarch-py`, a Python library for interacting with the Monarch Initi
 
 If you wish to run Monarch-App as a local web application, please install the requirements below and then follow on to the usage section to start the application. Refer to [Using Local Data](#using-local-data) to see how you can run the full Monarch website locally and use your own data store.
 
+The app also offers a widget called Phenogrid that can be embedded in any website.  
+For more information on how to use the Phenogrid widget, please refer to the [Phenogrid documentation](./frontend/PHENOGRID.md).
 
 ### For developers
 
 The monarch-app repository contains the code to run the Monarch Initiative website in the `frontend` and `backend` directories as well as documentation, helper scripts, Docker files and services to help set up a local environment for development and for deployment.
 
-To start development, please refer to the CONTRIBUTING.md document with this README. If you are planning to only develop the frontend or backend of the application you can refer directly to the README and CONTRIBUTING files in each of those sections.
+To start development, please refer to the [CONTRIBUTING.md](./CONTRIBUTING.md) document with this README. If you are planning to only develop the frontend or backend of the application you can refer directly to the README and CONTRIBUTING files in each of those sections.

frontend/CONTRIBUTING.md

@@ -184,7 +184,7 @@ Defaults to `false`.
 ## Phenogrid
 
 The phenogrid is a custom Vue component that displays a grid of phenotype comparisons.  
-For more information on the phenogrid and now to use it, see the [Phenogrid](./phenogrid.md) documentation.
+For more information on the phenogrid and now to use it, see the [Phenogrid](./PHENOGRID.md) documentation.
 
 ## Style guidelines
 

frontend/phenogrid.md → frontend/PHENOGRID.md

@@ -6,41 +6,48 @@ A widget for visualizing similarity between phenotypes.
 
 Phenogrid displays a visual comparison between sets of phenotypes in a grid arrangement, with calculations of the similarity in various metrics.
 
-Public pages at `monarchinitiative.org/phenogrid-search` and `/phenogrid-multi-compare` provide a widget embeddable on any site via an `<iframe>`, like so:
+Public pages at `monarchinitiative.org/phenogrid-search` and `/phenogrid-multi-compare` provide a widget embeddable on any site via an `<iframe>`, for example:
 
 ```html
 <iframe
-  src="https://monarchinitiative.org/phenogrid?PARAM=VALUE"
+  src="https://monarchinitiative.org/phenogrid-search?PARAM=VALUE&..."
   title="Phenogrid"
   name="some-optional-name"
   frameborder="0"
+  width="75%"
+  height="600px"
 ></iframe>
 ```
 
+You can specify a height and width here, but the widget will emit a `message` event to the parent window with the intrinsic size of its content, so you can dynamically set the dimensions of your iframe container.  
+See the [Events](#events) section for more details.
+
 ## Modes
 
-Phenogrid can operate in several modes, which you can specify via the `src` URL.
+Phenogrid can operate in multiple modes, which you can specify via the `src` URL.
 
 - [`/phenogrid-search`](#search-mode) - Compares a list of enumerated phenotypes (set A) against all the phenotypes from a gene or disease of interest (group B).
 - [`/phenogrid-multi-compare`](#multi-compare-mode) - Compares a list of enumerated phenotypes to _multiple_ enumerated other lists of phenotypes.
 
+For more details on the parameters for each mode, see the respective sections below.
+
 ## Passing Parameters
 
 The widget can accept input parameters in two different ways.
 You can choose to pass them either way, unless specified otherwise.
 
 ### URL Params (simple)
 
-Specify params in the URL like `?some-param=1,2,3&another-param=abc`.
+Specify params in the `src` URL like `?some-param=1,2,3&another-param=abc`.
 This is allows convenient use in cases where the parameters are simple and short.
 
 ### Message Params (detailed)
 
-For more flexible and detailed parameters, you can send the widget a message from JavaScript like this:
+For more flexible and detailed parameters, you can omit params from the URL and instead send the widget a message from JavaScript like this:
 
 ```js
 // get your iframe DOM element somehow
-const iframe = document.querySelector("iframe");
+const iframe = document.querySelector("iframe[name='your-iframe-name']");
 // send it a message
 iframe.contentWindow.postMessage(
   // some parameters
@@ -55,7 +62,7 @@ iframe.contentWindow.postMessage(
 
 You should use this method when your params might be [too long for a URL](https://www.google.com/search?q=max+url+length).
 
-## "Search" Mode
+## "Search" Mode Parameters
 
 As URL params:
 
@@ -72,7 +79,7 @@ As message params:
 }
 ```
 
-## "Multi-Compare" Mode
+## "Multi-Compare" Mode Parameters
 
 As URL params:
 
@@ -108,7 +115,7 @@ You can use the same event listener as the standard Phenogrid widget to set the
 General parameters available regardless of the mode of operation.
 
 - `stylesheet` - URL to a stylesheet that will be applied to the widget, for the purposes of matching its styles to your webpage.
-  If passed as a URL param, make sure it is URI encoded.
+  - If passed as a URL param, make sure it is URI encoded.
 
 ## Events
 
@@ -132,7 +139,7 @@ MessageEvent<{
 
 This can happen when it switches from loading to results, when new phenotypes are loaded, when the grid is flipped/transposed, etc.
 
-This can be useful for setting the dimensions of your iframe container:
+This can be useful for dynamically setting the dimensions of your iframe container:
 
 ```js
 window.addEventListener("message", (event) => {

frontend/fixtures/index.ts

@@ -11,7 +11,7 @@ import nodePublicationAbstract from "./node-publication-abstract.json";
 import nodePublicationSummary from "./node-publication-summary.json";
 import node from "./node.json";
 import phenotypeExplorerCompare from "./phenotype-explorer-compare.json";
-import phenotypeExplorerMulticompare from "./phenotype-explorer-multicompare.json";
+import phenotypeExplorerMulticompare from "./phenotype-explorer-multi-compare.json";
 import phenotypeExplorerSearch from "./phenotype-explorer-search.json";
 import search from "./search.json";
 import textAnnotator from "./text-annotator.json";