🚀 Revel Digital Gadgetizer

A command-line tool for integrating the Revel Digital client SDK into existing Angular, Vue, React, or vanilla JavaScript projects. This tool automates the setup process and generates the necessary configuration files for deploying your application as a Revel Digital gadget.

📦 Installation

Install globally via npm:

npm install -g @reveldigital/gadgetizer

Or use directly with npx:

npx @reveldigital/gadgetizer

🎯 Usage

Navigate to your existing project directory and run:

gadgetizer

The tool will guide you through the setup process with interactive prompts.

Command Options

• --help, -h - Show help message
• --build-only - Run only the XML build step (skips SDK installation)

Examples

Basic usage:

cd my-react-app
gadgetizer

Build XML only (useful for CI/CD):

gadgetizer --build-only

Show help:

gadgetizer --help

⚡ What It Does

The Gadgetizer tool performs the following actions based on your project type:

For Angular Projects

• Installs @reveldigital/player-client@latest
• Runs the Angular schematic: ng add @reveldigital/player-client@latest

For React, Vue, and Vanilla JavaScript Projects

• Copies gadget.yaml configuration file to your project root (if not already present)
• Prompts for deployment URL configuration
• Installs the following dependencies:
  • @reveldigital/client-sdk
  • @reveldigital/gadget-types
• Adds a build:gadget script to your package.json
• Generates XML gadget configuration file in your build directory

📁 Project Structure

After running the tool, your project will have:

• 📄 gadget.yaml - Gadget configuration file
• 📄 deploy-to-pages.yml (optional) - GitHub Actions workflow for automatic deployment to GitHub Pages
• 📦 Updated package.json with Revel Digital dependencies
• 🛠️ build:gadget npm script for regenerating the gadget XML
• 🗂️ Generated XML file in your build/dist directory

⚙️ Configuration

The gadget.yaml file contains metadata about your gadget:

title: My Gadget
title_url: https://mysupporturl.org
description: Describe the purpose of your gadget here
author: My Organization
background: transparent

requirements:
  - reveldigital
  - offline
  - webfont

prefs:
  - name: myStringPref
    display_name: Sample string preference
    datatype: string
    default_value: test string
    required: true

Edit this file to customize your gadget's properties and user preferences.

Working with Preferences

Preferences defined in the prefs section become configurable options in the Revel Digital CMS, allowing end users to customize your gadget's behavior and appearance. You can access these preferences in your application code using the Revel Digital client SDK.

For detailed information about accessing preferences and using the client SDK in your gadget, see the client SDK documentation.

🚀 GitHub Pages Deployment (Optional)

The deploy-to-pages.yml file is an optional GitHub Actions workflow that provides automated building and deployment of your gadget to GitHub Pages. When placed in your project's .github/workflows/ directory, this workflow will:

• Automatically trigger on pushes to your main branch
• Build your project using your existing build commands
• Run the Gadgetizer to generate the XML configuration
• Deploy the result to GitHub Pages for easy hosting and testing

To use this feature:

1. Copy deploy-to-pages.yml to .github/workflows/ in your project
2. Customize the build commands for your specific project type
3. Ensure GitHub Pages is enabled in your repository settings
4. Push changes to your main branch to trigger automatic deployment

This makes it easy to share and test your gadgets with others by providing a publicly accessible URL.

🛠️ Supported Frameworks

• Angular - Uses the official Revel Digital Angular schematic.
• React - Instruments with client SDK and generates gadget configuration. Sample Project
• Vue - Instruments with client SDK and generates gadget configuration. Sample Project
• Vanilla JavaScript - Instruments with client SDK and generates gadget configuration. Sample Project

📚 Revel Digital Client SDK

For more information about the Revel Digital client SDK, including API documentation and examples, visit: https://www.npmjs.com/package/@reveldigital/client-sdk

📜 License

ISC

🤝 Support

For issues and questions:

• File an issue on this repository
• Visit the Revel Digital documentation at https://developer.reveldigital.com
• Check the client SDK documentation at https://www.npmjs.com/package/@reveldigital/client-sdk