Dev Walkthru: add a new Panel to the Dashboard

docs/walkthrough/README.md

@@ -7,6 +7,7 @@ The following walkthroughs are available to help customize this application.
 1. [Adding a New Service](addNewService.md)
 1. [Adding a New Grid](addNewGrid.md)
 1. [Adding a New Flyout](addNewFlyout.md)
+1. [Adding a New Panel to the Dashboard](addNewDashboardPanel.md)
 
 
 ### Show the walkthrough examples in the running application

docs/walkthrough/addNewDashboardPanel.md

@@ -0,0 +1,78 @@
+Walkthrough: Adding a New Panel to the Dashboard
+================================================
+
+The following is for creating a new panel called "**examplePanel**."
+
+1. Create a folder named `examplePanel` inside the `components/pages/dashboard/panels` folder.
+1. Create 3 files in the new folder. See the individual example files for more details and comments inline.
+    - [examplePanel.js](/src/components/pages/dashboard/panels/_examplePanel/examplePanel.js) - main component for the panel
+    - [examplePanel.scss](/src/components/pages/dashboard/panels/_examplePanel/examplePanel.scss) - styles for the new panel
+    - [index.js](/src/components/pages/dashboard/panels/_examplePanel/index.js) - exports for the new panel
+1. Add the new panel to the main panel export file: [dashboard/panels/index.js](/src/components/pages/dashboard/panels/index.js).
+    ```js
+    export * from './examplePanel';
+    ```
+1. Add the panel header to the translations file, [translations.json](../../public/locales/en/translations.json). [i18next][i18next] is used for internationalization.
+    ```json
+    "examplePanel": {
+      "header": "Example Panel",
+    },
+    ```
+1. In the [examplePanel.js](/src/components/pages/dashboard/panels/_examplePanel/examplePanel.js), import the `Panel` components.
+    ```js
+    import {
+      Panel,
+      PanelHeader,
+      PanelHeaderLabel,
+      PanelContent,
+    } from 'components/pages/dashboard/panel';
+    ```
+1. In the render method, use the various `Panel` components to ensure consistency with others. Then, add whatever components are needed inside `PanelContent`.
+    ```jsx
+    <Panel>
+      <PanelHeader>
+        <PanelHeaderLabel>{t('examples.panel.header')}</PanelHeaderLabel>
+      </PanelHeader>
+      <PanelContent className="example-panel-container">
+        {t('examples.panel.panelBody')}
+      </PanelContent>
+    </Panel>
+    ```
+1. Add your panel to the [dashboard.js](/src/components/pages/dashboard/dashboard.js) page. Size the `Cell` for the panel according to how much space it will need. See [grid.scss](/src/components/pages/dashboard/grid/grid.scss) for the available grid-cell styles.
+    ```jsx
+    <Cell className="col-4">
+      <ExamplePanel t={t} />
+    </Cell>
+    ```
+1. **Congratulations!** Run the application and navigate to the Dashboard page.  You should see your new panel in action.
+
+1. Now, you can edit the panel to do what you want. Send props with any data you need. If mapping data and actions from a reducer, consider using the "container" approach described in the [Adding a New Grid](addNewGrid.md) walkthrough.
+
+1. Optional customizations:
+    1. Add an `Indicator` to the header to show pending state.
+        ```jsx
+        { isPending && <Indicator size="small" /> }
+        ```
+    1. Use a `PanelOverlay` to show pending state. This example uses an `Indicator`, but other components or messages could be placed here.
+        ```jsx
+        { isPending && <PanelOverlay><Indicator /></PanelOverlay> }
+        ```
+    1. Use `PanelError` and `AjaxError` to show error state.
+        ```jsx
+        { error && <PanelError><AjaxError t={t} error={error} /></PanelError> }
+        ```
+
+### More Information
+
+- Explore the other remote monitoring [walkthroughs](README.md).
+- Technology reference:
+    - [react][react]
+    - [i18next][i18next]
+
+
+
+[ag-grid]: https://www.ag-grid.com/react-getting-started/
+[i18next]: https://www.i18next.com/
+[react]: https://reactjs.org/
+[redux]: https://redux.js.org/
+[redux-obs]: https://redux-observable.js.org

public/locales/en/translations.json

@@ -566,6 +566,10 @@
           "close": "Close"
         }
       }
+    },
+    "panel": {
+      "header": "Example Panel",
+      "panelBody": "This is a new panel."
     }
   }
 }

src/components/app/app.js

@@ -44,6 +44,23 @@ if (Config.showWalkthroughExamples) {
   tabConfigs.push(gridExampleTab);
 }
 
+class WalkthroughExampleRoute extends Component {
+  render() {
+    const { component: Component, ...props } = this.props
+
+    return (
+      <Route
+        {...props}
+        render={props => (
+          Config.showWalkthroughExamples ?
+            <Component {...props} /> :
+            <Redirect to='/' />
+        )}
+      />
+    )
+  }
+}
+
 /** The base component for the app */
 class App extends Component {
 
@@ -76,9 +93,9 @@ class App extends Component {
               <Route exact path={devicesTab.to} component={DevicesPage} />
               <Route exact path={rulesTab.to} component={RulesPage} />
               <Route path={maintenanceTab.to} component={MaintenancePage} />
-              <Route path={exampleTab.to} component={ExamplePage} />
-              <Route path={flyoutExampleTab.to} component={FlyoutExamplePage} />
-              <Route path={gridExampleTab.to} component={GridExamplePage} />
+              <WalkthroughExampleRoute path={exampleTab.to} component={ExamplePage} />
+              <WalkthroughExampleRoute path={flyoutExampleTab.to} component={FlyoutExamplePage} />
+              <WalkthroughExampleRoute path={gridExampleTab.to} component={GridExamplePage} />
               <Route component={PageNotFound} />
             </Switch>
             { this.props.deviceGroupFlyoutIsOpen && <ManageDeviceGroupsContainer /> }

src/components/pages/dashboard/dashboard.js

@@ -18,6 +18,7 @@ import {
   TelemetryPanel,
   AnalyticsPanel,
   MapPanel,
+  ExamplePanel,
   transformTelemetryResponse,
   chartColorObjects
 } from './panels';
@@ -407,6 +408,11 @@ export class Dashboard extends Component {
               colors={chartColorObjects}
               t={t} />
           </Cell>
+          { Config.showWalkthroughExamples &&
+            <Cell className="col-4">
+              <ExamplePanel t={t} />
+            </Cell>
+          }
         </Grid>
       </PageContent>
     ];

src/components/pages/dashboard/panels/_examplePanel/examplePanel.js

@@ -0,0 +1,35 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+import React, { Component } from 'react';
+
+import {
+  Panel,
+  PanelHeader,
+  PanelHeaderLabel,
+  PanelContent,
+} from 'components/pages/dashboard/panel';
+
+import './examplePanel.css';
+
+export class ExamplePanel extends Component {
+  constructor(props) {
+    super(props);
+
+    this.state = { isPending: true };
+  }
+
+  render() {
+    const { t } = this.props;
+
+    return (
+      <Panel>
+        <PanelHeader>
+          <PanelHeaderLabel>{t('examples.panel.header')}</PanelHeaderLabel>
+        </PanelHeader>
+        <PanelContent className="example-panel-container">
+          {t('examples.panel.panelBody')}
+        </PanelContent>
+      </Panel>
+    );
+  }
+}

src/components/pages/dashboard/panels/_examplePanel/examplePanel.scss

@@ -0,0 +1,14 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+@import 'src/styles/mixins';
+@import 'src/styles/themes';
+
+.example-panel-container {
+  display: flex;
+  flex-flow: column nowrap;
+  padding: 0 !important;
+
+  @include themify($themes) {
+    color: themed('colorContentTextDim');
+  }
+}

src/components/pages/dashboard/panels/_examplePanel/index.js

@@ -0,0 +1,3 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+export * from './examplePanel';

src/components/pages/dashboard/panels/index.js

@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+export * from './_examplePanel';
 export * from './alerts';
 export * from './overview';
 export * from './map';