@cloudmosaic/quickstarts

Quickstarts

Demo https://quickstarts.netlify.app/

Install

Note: These instructions can change over time as the module gets more refined

`yarn add @cloudmosaic/quickstarts @patternfly/patternfly`
or
`npm install @cloudmosaic/quickstarts @patternfly/patternfly`

The package currently has these peer dependencies:

"react": ">=16.8.0",
"react-dom": ">=16.8.0",
"@patternfly/patternfly": ">=4.87.3",
"@patternfly/react-core": ">=4.97.2"

Additionally for styles the package depends on (might bundle these up as vendor.css in the future):

@patternfly/patternfly
@patternfly/react-catalog-view-extension

In your web-apps entry point, add this (these should be imported before modules from the package are imported):

import "@patternfly/patternfly/base/patternfly-shield-inheritable.css";
import "@patternfly/patternfly/patternfly.min.css";
import "@patternfly/patternfly/utilities/Accessibility/accessibility.css";
import "@patternfly/react-catalog-view-extension/dist/css/react-catalog-view-extension.css";
import "@cloudmosaic/quickstarts/dist/quickstarts.css";

Usage

In your main app file wrap your application:

import {
  QuickStartDrawer,
  QuickStartContext,
  QuickStartCatalogPage,
  useValuesForQuickStartContext,
  useLocalStorage,
  QuickStartContextValues,
  QuickStartContext,
} from "@cloudmosaic/quickstarts";
// for how these yaml files should look see below
import quickstartOne from ".yamls/quickstart-one.yaml";
import quickstartTwo from ".yamls/quickstart-two.yaml";

const App = () => {
  const allQuickStarts = [quickstartOne, quickstartTwo];
  const [activeQuickStartID, setActiveQuickStartID] = useLocalStorage(
    "quickstartId",
    ""
  );
  const [allQuickStartStates, setAllQuickStartStates] = useLocalStorage(
    "quickstarts",
    {}
  );
  const { pathname: currentPath } = window.location;
  const quickStartPath = "/quickstarts";
  const valuesForQuickstartContext = useValuesForQuickStartContext({
    allQuickStarts,
    activeQuickStartID,
    setActiveQuickStartID,
    allQuickStartStates,
    setAllQuickStartStates,
    footer: {
      showAllLink: currentPath !== quickStartPath,
      onShowAllLinkClick: () => history.push(quickStartPath),
    },
  });

  return (
    <QuickStartContext.Provider value={valuesForQuickstartContext}>
      <QuickStartDrawer>
        <div>
          <h1>My app</h1>
          <button
            onClick={() =>
              valuesForQuickstartContext.setActiveQuickStart("a quickstart id")
            }
          >
            Open a quickstart
          </button>
          <QuickStartCatalogPage />
        </div>
        <SomeNestedComponent />
      </QuickStartDrawer>
    </QuickStartContext.Provider>
  );
};

const SomeNestedComponent = () => {
  const qsContext = React.useContext<QuickStartContextValues>(
    QuickStartContext
  );
  return (
    <button
      onClick={() =>
        qsContext.setActiveQuickStart("a quickstart id")
      }
    >
      Open a quickstart from a nested component
    </button>
  );
};

Features

Highlighting elements in yaml+markdown

You can highlight an element on the page from the quick start. The element that should be highlightable needs an attribute like this: data-quickstart-id="highlight-me"

In the quickstart .yaml file, you can add this type of markdown text to target this element: Highlight [my element]{{highlight highlight-me}}

Highlighting elements in asciidoc/adoc

. To highlight items from a quick start, first the target item needs to have a data attribute: data-quickstart-id="something" . Then in asciidoc, the trigger element needs to have the data-highlight__something class/role, where the part after data-highlight__ matches the data-quickstart-id of the target Here are some examples:

• link:[Click me to highlight the logo, role="data-highlight__logo"]
• link:[Click me to highlight the Home nav item, role="data-highlight__home"]

Webpack

You can reduce the size of your CSS bundle by using clean-css-loader and null-loader: yarn add -D clean-css-loader null-loader or npm install --save-dev clean-css-loader null-loader In the webpack config:

const isProd = argv.mode === "production";
const cssLoaders = ["style-loader", "css-loader"];
if (isProd) {
  // push loader for production mode only
  cssLoaders.push("clean-css-loader");
}

In the rules array:

{
    test: /\.css$/,
    use: cssLoaders,
},
{
    test: /\.css$/,
    include: stylesheet => stylesheet.includes('@patternfly/react-styles/css/'),
    use: ["null-loader"]
},

yaml

This section will get more info in the future. For now you can view sample yamls here: https://github.com/cloudmosaic/quickstarts/tree/main/packages/dev/src/quickstarts-data/mocks/yamls