No Preview

Sorry, but you either have no stories or none are selected somehow.

If the problem persists, check the browser console, or the terminal you've run Storybook from.

The component failed to render properly, likely due to a configuration issue in Storybook. Here are some common causes and how you can address them:

  1. Missing Context/Providers: You can use decorators to supply specific contexts or providers, which are sometimes necessary for components to render correctly. For detailed instructions on using decorators, please visit the Decorators documentation.
  2. Misconfigured Webpack or Vite: Verify that Storybook picks up all necessary settings for loaders, plugins, and other relevant parameters. You can find step-by-step guides for configuring Webpack or Vite with Storybook.
  3. Missing Environment Variables: Your Storybook may require specific environment variables to function as intended. You can set up custom environment variables as outlined in the Environment Variables documentation.

Introduction

Why Web Components?

HTML custom elements are now widely supported across browsers, and building encapsulated web components allows us to package logic and styles for the defined field types within Disciple.Tools. By doing this, the main theme doesn't need other javascript dependencies and initialization scripts, and PHP developers can stick to writing PHP instead of also needing to figure out complex javascript interactions.

Main Concepts

This web components library was built with a few main concepts in mind that drive the initial and future development:

  • HTML/Framework Support: Components should work in a standard HTML form, via events and API requests, and by including in other javascript frameworks. Whatever method developers want to use the components should be supported.
  • Loose Coupling: Components do not implement specific Disciple.Tools APIs directly within their functionality. Events are dispatched for coupling to APIs or other data sources, and the ComponentService provides coupling to standard APIs when needed.
  • Javascript Events: Communication outside the components happens by dispatching javascript events
  • CSS Customization: Styles default to the main Disciple.Tools styles, but can be customized at various layers via CSS variables/properties. Change styles for all components or for a single component. Styling should be versatile.

Getting Started

Install

NPM

The easiest way to include the web components is to use NPM. If your project will make use of NPM, you can run:

npm i @disciple.tools/web-components

You can then include the library based on the type of project you're working on:

Manual Build

See git repo for details on how to manually build the components to include in a project without NPM.

Include Scripts

Javascript Projects (React, Vue, etc.)

import '@disciple.tools/web-components';

Your framework may need a wrapper component to make these components work, so see the specific documentation for your framework.

Standard HTML

See HTML Sample Documentation

CDN

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@disciple.tools/web-components@0.7.0/styles/light.css" type="text/css" media="all">
<script src="https://cdn.jsdelivr.net/npm/@disciple.tools/web-components@0.7.0/dist/index.js"></script>

Local Include

<link rel="stylesheet" href="/path/to/@disciple.tools/web-components/src/styles/light.css" type="text/css" media="all">
<script src="/path/to/@disciple.tools/web-components/dist/index.js"></script>

WordPress

If you're using the Disciple.Tools theme, the components are all included (only in the next branch releases for now) and can be used without explicitly including scripts.

If you are writing a Magic Link or other plugin for WordPress that doesn't include the theme files, you'll need to include the script files.

CDN

$dtwc_version = '0.7.0';
wp_enqueue_style( 'dt-web-components-css', "https://cdn.jsdelivr.net/npm/@disciple.tools/web-components@$dtwc_version/styles/light.css", [], $dtwc_version );
wp_enqueue_script( 'dt-web-components-js', "https://cdn.jsdelivr.net/npm/@disciple.tools/web-components@$dtwc_version/dist/index.js", $dtwc_version );

Local Include

$path = '../path/to/components/dist/index.js';
wp_enqueue_script( 'dt-web-components-js',
  plugin_dir_url( __FILE__ ) . $path,
  null,
  filemtime( plugin_dir_path( __FILE__ ) . $path )
);

$css_path = '../path/to/components/src/styles/light.css';
wp_enqueue_style( 'dt-web-components-css',
  plugin_dir_url( __FILE__ ) . $css_path,
  null,
  filemtime( plugin_dir_path( __FILE__ ) . $css_path )
);

Render Components

Once your scripts are included, you can use the components like you would any other standard HTML elements when you render your page.

<html>
<head>...</head>
<body>
  <main>
    <h1>My Page</h1>
    <div>
      <dt-text id='textField' name='textField' label="My Text Field"></dt-text>
    </div>
  </main>
</body>
</html>

Next Steps

Learn about the Component Architecture in case you want to extend or contribute to the components.

View All Components to learn about how each component works.