pptb-standard-sample-tool 0.0.11 → 0.1.2

package/README.md

@@ -1,141 +1,237 @@
-# PowerPlatform Example Tool
+# HTML Sample Tool
 
-A complete example tool demonstrating the HTML-first architecture with TypeScript for PowerPlatform ToolBox.
+A complete example tool for Power Platform Tool Box built with HTML, CSS, and TypeScript.
 
 ## Features
 
-- ✅ TypeScript with full type safety
-- ✅ HTML+CSS+JS architecture
-- ✅ Access to ToolBox API via `window.toolboxAPI`
-- ✅ Connection URL and access token handling
-- ✅ Event subscription and handling
-- ✅ Interactive UI with notifications, clipboard, and data display
+This sample demonstrates:
+
+- ✅ **ToolBox API Integration**
+  - Connection management and status display
+  - Notifications (success, info, warning, error)
+  - Clipboard operations
+  - File save dialogs
+  - Theme detection
+  - Terminal creation and command execution
+  - Event subscription and handling
+
+- ✅ **Dataverse API Usage**
+  - FetchXML queries
+  - CRUD operations (Create, Read, Update, Delete)
+  - Entity metadata retrieval
+  - Error handling
+
+- ✅ **Best Practices**
+  - TypeScript with full type safety
+  - Event-driven architecture
+  - Proper error handling
+  - Clean, modern UI design
+  - Responsive layout
 
-## Structure
+## Installation
 
-```
-example-tool/
-├── src/
-│   ├── index.html      # Main UI
-│   ├── index.ts        # Tool logic (TypeScript)
-│   └── styles.css      # Styling
-├── dist/               # Compiled output (after build)
-│   ├── index.html
-│   ├── index.js
-│   ├── index.js.map
-│   └── styles.css
-├── package.json
-├── tsconfig.json
-└── README.md
-```
+### Prerequisites
 
-## Installation
+- Node.js 18 or higher
+- Power Platform Tool Box desktop application
 
-Install dependencies:
+### Install Dependencies
 
 ```bash
 npm install
 ```
 
-## Development
-
-Build the tool:
+### Build
 
 ```bash
 npm run build
 ```
 
-Watch mode for development:
+This compiles the TypeScript source in `src/` to JavaScript in `dist/`.
 
-```bash
-npm run watch
+## Project Structure
+
+```
+html-sample/
+├── src/
+│   └── app.ts           # Main application logic (TypeScript)
+├── index.html           # Main HTML file (entry point)
+├── styles.css           # Stylesheet
+├── package.json         # Package configuration
+├── tsconfig.json        # TypeScript configuration
+└── README.md           # This file
 ```
 
-## Usage in ToolBox
+## Usage
 
-1. Install the tool in ToolBox:
-   ```javascript
-   await window.toolboxAPI.installTool('@powerplatform/example-tool');
-   ```
+### Install in Power Platform Tool Box
 
-2. Load the tool:
-   ```javascript
-   await window.toolboxAPI.loadTool('@powerplatform/example-tool');
-   ```
+1. Open Power Platform Tool Box
+2. Go to Tools section
+3. Click "Install Tool"
+4. Enter the path to this directory or publish to npm and use the package name
 
-3. Get the tool's HTML with connection context:
-   ```javascript
-   const html = await window.toolboxAPI.getToolWebviewHtml(
-     '@powerplatform/example-tool',
-     'https://your-env.crm.dynamics.com',
-     'your-access-token'
-   );
-   ```
+### Features Overview
 
-4. Render the HTML in a webview.
+#### Connection Status
+- Shows current Dataverse connection details
+- Displays environment type (Production, Sandbox, Dev)
+- Updates automatically when connection changes
 
-## API Usage
+#### ToolBox API Examples
 
-The tool demonstrates various ToolBox API features:
+**Notifications:**
+- Test different notification types
+- Success, info, warning, and error messages
 
-### Getting Connection Context
+**Utilities:**
+- Copy data to clipboard
+- Get current theme (light/dark)
+- Save data to file with native dialog
 
-```typescript
-const context = await window.toolboxAPI.getToolContext();
-console.log(context.connectionUrl);
-console.log(context.accessToken);
+**Terminal:**
+- Create isolated terminal instances
+- Execute shell commands
+- View command output
+- Close terminal when done
+
+#### Dataverse API Examples
+
+**Query Records:**
+- FetchXML query to retrieve top 10 accounts
+- Display results with formatting
+
+**CRUD Operations:**
+- Create new account records
+- Update existing records
+- Delete records
+- Full error handling
+
+**Metadata:**
+- Retrieve entity metadata
+- Display entity information and attributes
+
+#### Event Log
+- Real-time event logging
+- Color-coded by severity
+- Timestamp for each entry
+- Clear log functionality
+
+## Development
+
+### Watch Mode
+
+During development, you can use watch mode to automatically recompile on changes:
+
+```bash
+npm run watch
 ```
 
-### Showing Notifications
+### Type Safety
+
+This tool uses TypeScript with the `@pptb/types` package for full type safety:
 
 ```typescript
-await window.toolboxAPI.showNotification({
-  title: 'Success',
-  body: 'Operation completed',
-  type: 'success'
-});
+/// <reference types="@pptb/types" />
+
+// Type-safe API access
+const toolbox: typeof window.toolboxAPI = window.toolboxAPI;
+const dataverse: typeof window.dataverseAPI = window.dataverseAPI;
 ```
 
-### Subscribing to Events
+### Customization
+
+1. **Modify UI:** Edit `index.html` and `styles.css`
+2. **Add Features:** Update `src/app.ts`
+3. **Rebuild:** Run `npm run build`
+4. **Reload Tool:** In Power Platform Tool Box, close and reopen the tool
+
+## API Usage Examples
+
+### ToolBox API
 
 ```typescript
-window.toolboxAPI.onToolboxEvent((event, payload) => {
-  console.log('Event:', payload.event);
-  console.log('Data:', payload.data);
+// Show notification
+await toolbox.utils.showNotification({
+    title: 'Success',
+    body: 'Operation completed',
+    type: 'success',
+    duration: 3000
+});
+
+// Get active connection
+const connection = await toolbox.connections.getActiveConnection();
+
+// Create terminal
+const terminal = await toolbox.terminal.create({
+    name: 'My Terminal'
+});
+
+// Subscribe to events
+toolbox.events.on((event, payload) => {
+    console.log('Event:', payload.event, payload.data);
 });
 ```
 
-### Accessing Connections
+### Dataverse API
 
 ```typescript
-const connections = await window.toolboxAPI.getConnections();
-const active = await window.toolboxAPI.getActiveConnection();
+// Query with FetchXML
+const result = await dataverse.fetchXmlQuery(`
+    <fetch top="10">
+        <entity name="account">
+            <attribute name="name" />
+        </entity>
+    </fetch>
+`);
+
+// Create record
+const account = await dataverse.create('account', {
+    name: 'Contoso Ltd',
+    emailaddress1: 'info@contoso.com'
+});
+
+// Update record
+await dataverse.update('account', accountId, {
+    telephone1: '555-0100'
+});
+
+// Delete record
+await dataverse.delete('account', accountId);
+
+// Get metadata
+const metadata = await dataverse.getEntityMetadata('account');
 ```
 
-## Type Definitions
+## Troubleshooting
+
+### Build Errors
+
+If you encounter TypeScript errors:
+1. Ensure `@pptb/types` is installed: `npm install`
+2. Check TypeScript version: `tsc --version` (should be 5.x)
+3. Clean and rebuild: `rm -rf dist && npm run build`
+
+### API Not Available
 
-This tool includes TypeScript type definitions in the `types/` folder. The type definitions provide:
+If `toolboxAPI` or `dataverseAPI` is undefined:
+- The tool must be loaded within Power Platform Tool Box
+- These APIs are injected by the toolboxAPIBridge
+- They are not available in a standalone browser
 
-- Full ToolBoxAPI interface
-- Event type definitions
-- Connection and Tool interfaces
-- Notification options
-- And more...
+### Connection Issues
 
-## TypeScript Configuration
+If connection is null:
+- Open Power Platform Tool Box
+- Create a connection to a Dataverse environment
+- The tool will automatically detect the connection
 
-The tool uses modern TypeScript configuration:
+## Resources
 
-- **Target**: ES2022
-- **Module**: ES2022
-- **Module Resolution**: bundler (modern strategy)
-- **Strict Mode**: Enabled with additional safety checks:
-  - `noUnusedLocals`: Warns about unused local variables
-  - `noUnusedParameters`: Warns about unused function parameters
-  - `noFallthroughCasesInSwitch`: Ensures all switch cases handle control flow
-  - `useDefineForClassFields`: Modern class field semantics
-  - `moduleDetection`: Force module detection
+- [Tool Development Guide](../../docs/TOOL_DEVELOPMENT.md)
+- [API Reference](../../packages/README.md)
+- [Power Platform Tool Box Repository](https://github.com/PowerPlatform-ToolBox/desktop-app)
 
 ## License
 
-MIT
+GPL-3.0 - See LICENSE file in repository root