Angular

Prerequisites

Before you begin, ensure you have the following:

Node.js: Version 14 or higher. Download from Node.js Official Website.
npm or Yarn: Package managers that come with Node.js.
Angular CLI: Install globally using npm install -g @angular/cli.
Code Editor: Such as Visual Studio Code.
Basic Knowledge: Familiarity with JavaScript, TypeScript, and Angular.
Access to TakeProfit Platform: For widget integration and testing.

Set Up Your Angular Project

Create a New Angular App

Use Angular CLI to bootstrap a new Angular project. Open your terminal and run:
```
ng new my-tp-widget
cd my-tp-widget
```
Follow the prompts to set up your project. For this guide, it’s recommended to select the following options:
- Would you like to add Angular routing? Yes
- Which stylesheet format would you like to use? CSS (or your preferred choice)
Start the Development Server

Verify that your Angular app is set up correctly by starting the development server:
```
ng serve
```
This will run your app at http://localhost:4200/.

Install the SDK

Integrate the TakeProfit Widget SDK into your Angular project by installing it via npm or Yarn:
```
npm install takeprofit-widget-sdk@0.2.3
```
Or with Yarn:
```
yarn add takeprofit-widget-sdk@0.2.3
```
Verify Installation

Check your package.json to ensure takeprofit-widget-sdk is listed under dependencies:
```
"dependencies": {
  "takeprofit-widget-sdk": "^0.2.3",
  // other dependencies...
}
```

Configure Security Headers

To ensure that your widget can be embedded securely within the TakeProfit platform, you need to configure specific HTTP headers. Since Angular applications are typically served using static servers, you’ll need to set up a simple Express server to serve your widget with the necessary headers.

Install Express and CORS

Install Express and CORS to create a server that can set custom headers:
```
npm install express cors
```

Create the Server File

Create a new file named server.js in the root of your project:

touch server.js

Open server.js and add the following code:

// server.js

const express = require("express");
const path = require("path");
const cors = require("cors");

const app = express();
const PORT = process.env.PORT || 8080;

// Middleware to set security headers
app.use(
	cors({
		origin: "https://takeprofit.com",
	})
);

app.use((req, res, next) => {
	res.setHeader("X-Frame-Options", "ALLOW-FROM https://takeprofit.com");
	res.setHeader(
		"Content-Security-Policy",
		"frame-ancestors 'self' https://takeprofit.com"
	);
	next();
});

// Serve static files from the Angular app
app.use(express.static(path.join(__dirname, "dist/my-tp-widget")));

// For all GET requests, send back index.html so that PathLocationStrategy can be used
app.get("/*", (req, res) => {
	res.sendFile(path.join(__dirname, "dist/my-tp-widget/index.html"));
});

app.listen(PORT, () => {
	console.log(`Server is running on port ${PORT}`);
});

Explanation:

CORS Middleware: Allows requests only from https://takeprofit.com.
Security Headers: Sets X-Frame-Options and Content-Security-Policy to allow embedding only from https://takeprofit.com.
Static Files: Serves the Angular app from the dist/my-tp-widget directory.
Fallback to index.html: Ensures that Angular’s routing works correctly.

Build the Angular App

Before running the server, build your Angular application:
```
ng build --prod
```
This will generate the production build in the dist/my-tp-widget directory.

Initialize the SDK in Your Project

Create an SDK Initialization Service

Generate a new service to handle SDK initialization and cleanup:
```
ng generate service services/tp-widget-sdk
```
This will create tp-widget-sdk.service.ts in the src/app/services directory.

Implement the Service

Open src/app/services/tp-widget-sdk.service.ts and add the following code:

// src/app/services/tp-widget-sdk.service.ts

import { Injectable } from "@angular/core";
import { TPWidgetSDK } from "takeprofit-widget-sdk";

@Injectable({
	providedIn: "root",
})
export class TpWidgetSdkService {
	constructor() {}

	initializeSDK(): void {
		TPWidgetSDK.connect();
		TPWidgetSDK.hideLoader();
	}

	cleanupSDK(): void {
		TPWidgetSDK.disconnect();
	}

	subscribeWidgetChange(
		callback: (newState: WidgetStateInfo | null) => void
	): void {
		TPWidgetSDK.subscribeWidgetChange(callback);
	}

	unsubscribeWidgetChange(
		callback: (newState: WidgetStateInfo | null) => void
	): void {
		TPWidgetSDK.unsubscribeWidgetChange(callback);
	}

	subscribeChannelChange(
		callback: (newChannel: Channel | null) => void
	): void {
		TPWidgetSDK.subscribeChannelChange(callback);
	}

	unsubscribeChannelChange(
		callback: (newChannel: Channel | null) => void
	): void {
		TPWidgetSDK.unsubscribeChannelChange(callback);
	}

	requestChangeSecurity(
		securityID: SecurityID,
		callback: (result: { payload: ResultPayload }) => void
	): void {
		TPWidgetSDK.requestChangeSecurity(securityID, callback);
	}

	async addMenuItem(
		label: string,
		action: () => void,
		isPermanent: boolean
	): Promise<number> {
		return await TPWidgetSDK.addMenuItem(label, action, isPermanent);
	}

	async updateMenuItem(
		menuItemId: number,
		isPermanent: boolean,
		label: string
	): Promise<boolean> {
		return await TPWidgetSDK.updateMenuItem(menuItemId, isPermanent, label);
	}

	async removeMenuItem(menuItemId: number): Promise<boolean> {
		return await TPWidgetSDK.removeMenuItem(menuItemId);
	}
}

// Define necessary interfaces
export type SecurityID = `${string};${string}`;

export interface WidgetStateInfo {
	widgetID: string;
	channelID: string | null;
	active: boolean;
	fullscreen: boolean;
}

export interface Channel {
	ID: string;
	securityID: SecurityID | null;
	security: Security | null;
}

export interface Security {
	ID: SecurityID;
	ticker: string;
	precision: number;
	name: string;
	exchangeCode?: string;
	iconURL?: string;
	iconBase64?: string;
	iconBackgroundColor?: string;
	className?: string;
	classNameTopLevel?: string;
	companyName?: string;
	countryCode?: string;
	exchangeAlias?: string;
	industryName?: string;
}

export interface ResultPayload {
	isSuccessful: boolean;
	error?: string;
}

Explanation:

TpWidgetSdkService: Provides methods to initialize, cleanup, and interact with the TakeProfit Widget SDK.
Type Definitions: Defines necessary TypeScript interfaces for type safety.

Provide the Service Globally

The service is already provided in the root injector via the @Injectable decorator, so no additional configuration is needed.

Generate a New Component

Create a new component for your widget:
```
ng generate component components/widget
```
This will create widget.component.ts, widget.component.html, and related files in the src/app/components/widget directory.

Implement the Widget Component

Open src/app/components/widget/widget.component.ts and add the following code:

// src/app/components/widget/widget.component.ts

import { Component, OnInit, OnDestroy } from "@angular/core";
import {
	TpWidgetSdkService,
	WidgetStateInfo,
	Channel,
	SecurityID,
	ResultPayload,
} from "../../services/tp-widget-sdk.service";

@Component({
	selector: "app-widget",
	templateUrl: "./widget.component.html",
	styleUrls: ["./widget.component.css"],
})
export class WidgetComponent implements OnInit, OnDestroy {
	menuItemId: number | null = null;

	constructor(private tpWidgetSdk: TpWidgetSdkService) {}

	ngOnInit(): void {
		// Initialize the SDK
		this.tpWidgetSdk.initializeSDK();

		// Subscribe to widget state changes
		this.tpWidgetSdk.subscribeWidgetChange(
			this.handleWidgetChange.bind(this)
		);

		// Subscribe to channel state changes
		this.tpWidgetSdk.subscribeChannelChange(
			this.handleChannelChange.bind(this)
		);
	}

	ngOnDestroy(): void {
		// Unsubscribe from widget and channel changes
		this.tpWidgetSdk.unsubscribeWidgetChange(
			this.handleWidgetChange.bind(this)
		);
		this.tpWidgetSdk.unsubscribeChannelChange(
			this.handleChannelChange.bind(this)
		);

		// Cleanup the SDK
		this.tpWidgetSdk.cleanupSDK();
	}

	handleWidgetChange(newState: WidgetStateInfo | null): void {
		console.log("Widget state updated:", newState);
	}

	handleChannelChange(newChannel: Channel | null): void {
		console.log("Channel state updated:", newChannel);
	}

	changeSecurity(securityID: SecurityID): void {
		this.tpWidgetSdk.requestChangeSecurity(securityID, (result) => {
			if (result.payload.isSuccessful) {
				console.log(`Security successfully changed to ${securityID}.`);
			} else {
				console.error(`Failed to change security: ${result.payload.error}`);
			}
		});
	}

	async addMenuItem(): Promise<void> {
		try {
			const id = await this.tpWidgetSdk.addMenuItem(
				"Refresh Data",
				() => {
					console.log("Refresh Data menu item clicked.");
					// Implement refresh logic here
				},
				false
			);
			this.menuItemId = id;
			console.log(`Menu item added with ID: ${id}`);
		} catch (error) {
			console.error("Failed to add menu item:", error);
		}
	}

	async updateMenuItem(): Promise<void> {
		if (!this.menuItemId) return;
		try {
			const success = await this.tpWidgetSdk.updateMenuItem(
				this.menuItemId,
				false,
				"Refresh Data (Updated)"
			);
			if (success) {
				console.log("Menu item updated successfully.");
			}
		} catch (error) {
			console.error("Failed to update menu item:", error);
		}
	}

	async removeMenuItem(): Promise<void> {
		if (!this.menuItemId) return;
		try {
			const success = await this.tpWidgetSdk.removeMenuItem(this.menuItemId);
			if (success) {
				console.log("Menu item removed successfully.");
				this.menuItemId = null;
			}
		} catch (error) {
			console.error("Failed to remove menu item:", error);
		}
	}
}

Important Corrections:

Conditional Checks: Updated if (result.isSuccessful) to if (result.payload.isSuccessful) to correctly access the isSuccessful property within the payload.
Error Messages: Updated ${result.error} to ${result.payload.error} to correctly access the error message within the payload.

Explanation:

Lifecycle Hooks:
- ngOnInit: Initializes the SDK and subscribes to widget and channel state changes.
- ngOnDestroy: Unsubscribes from state changes and cleans up the SDK.
Methods:
- handleWidgetChange: Logs widget state updates.
- handleChannelChange: Logs channel state updates.
- changeSecurity: Requests a security change and handles the response.
- addMenuItem: Adds a new menu item labeled “Refresh Data”.
- updateMenuItem: Updates the existing menu item’s label to “Refresh Data (Updated)”.
- removeMenuItem: Removes the menu item and resets menuItemId.

Design the Widget Template

Open src/app/components/widget/widget.component.html and add the following code:

<!-- src/app/components/widget/widget.component.html -->

<div class="widget">
	<h1>TakeProfit Widget</h1>
	<p>Welcome to your first TakeProfit widget!</p>
	<button
		(click)="changeSecurity('AAPL;BATS')"
		class="btn"
	>
		Set Security to AAPL
	</button>
	<button
		(click)="changeSecurity('META;BATS')"
		class="btn"
	>
		Set Security to META
	</button>
	<div class="menu-actions">
		<button
			(click)="addMenuItem()"
			class="btn"
		>
			Add Refresh Data Menu Item
		</button>
		<button
			(click)="updateMenuItem()"
			class="btn"
			[disabled]="!menuItemId"
		>
			Update Menu Item
		</button>
		<button
			(click)="removeMenuItem()"
			class="btn"
			[disabled]="!menuItemId"
		>
			Remove Menu Item
		</button>
	</div>
</div>

Style the Widget

Open src/app/components/widget/widget.component.css and add the following styles:

/* src/app/components/widget/widget.component.css */

.widget {
	padding: 20px;
	font-family: Arial, sans-serif;
	text-align: center;
	background-color: #f0f2f5;
	border-radius: 8px;
	box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
	max-width: 400px;
	margin: auto;
}

.btn {
	margin: 10px;
	padding: 10px 20px;
	font-size: 16px;
	cursor: pointer;
	border: none;
	border-radius: 4px;
	background-color: #007bff;
	color: #fff;
	transition: background-color 0.3s ease;
}

.btn:hover {
	background-color: #0056b3;
}

.btn:disabled {
	background-color: #cccccc;
	cursor: not-allowed;
}

.menu-actions {
	margin-top: 20px;
}

Explanation:

Centers the widget with padding, background color, and box shadow.
Styles buttons for better user experience.
Disables buttons appropriately when no menu item is present.

Include the Widget Component in Your App

Open src/app/app.component.html and replace its content with the widget component selector:
```


<app-widget></app-widget>
```

Handle Widget and Channel State Changes

The widget component (widget.component.ts) already includes methods to handle widget and channel state changes (handleWidgetChange and handleChannelChange). These methods log the updated states to the console. You can expand these methods to perform additional actions based on state changes as needed.
Implement Additional Interactions

Depending on your widget’s requirements, you can add more functionalities such as updating menu items, handling user inputs, and integrating real-time data feeds. The current implementation includes buttons to change security and manage menu items, demonstrating basic interactions with the SDK.

Enhance your widget by adding custom menu items to the widget header.

Implement Menu Item Functions in widget.component.ts

The menu item functions are already implemented in Step 5. Here’s a recap:

Add Menu Item

async addMenuItem(): Promise<void> {
  try {
    const id = await this.tpWidgetSdk.addMenuItem('Refresh Data', () => {
      console.log('Refresh Data menu item clicked.');
      // Implement refresh logic here
    }, false);
    this.menuItemId = id;
    console.log(`Menu item added with ID: ${id}`);
  } catch (error) {
    console.error('Failed to add menu item:', error);
  }
}

Update Menu Item

async updateMenuItem(): Promise<void> {
  if (!this.menuItemId) return;
  try {
    const success = await this.tpWidgetSdk.updateMenuItem(this.menuItemId, false, 'Refresh Data (Updated)');
    if (success) {
      console.log('Menu item updated successfully.');
    }
  } catch (error) {
    console.error('Failed to update menu item:', error);
  }
}

Remove Menu Item

async removeMenuItem(): Promise<void> {
  if (!this.menuItemId) return;
  try {
    const success = await this.tpWidgetSdk.removeMenuItem(this.menuItemId);
    if (success) {
      console.log('Menu item removed successfully.');
      this.menuItemId = null;
    }
  } catch (error) {
    console.error('Failed to remove menu item:', error);
  }
}

Explanation:

Add Menu Item: Adds a new menu item labeled “Refresh Data” to the widget header. Upon successful addition, stores the menuItemId.
Update Menu Item: Updates the existing menu item’s label to “Refresh Data (Updated)”.
Remove Menu Item: Removes the menu item using the stored menuItemId and resets it.

Ensure Unique Menu Item IDs

When adding multiple menu items, ensure each has a unique menuItemId to prevent conflicts. In this example, we’re managing a single menu item, but you can extend this logic to handle multiple items as needed.

Start the Server

Ensure your Express server is running to serve the widget with the configured headers:
```
node server.js
```
Your widget will be accessible at http://localhost:8080.
Configure Local Storage for Testing

To simulate the widget’s presence on the TakeProfit platform, configure local storage in your browser:
- Open the TakeProfit Platform: Navigate to the TakeProfit platform in your browser.
- Open Developer Console: Press F12 or Ctrl+Shift+I to open the developer tools.
- Set Local Storage Entry:
  localStorage.setItem( "takeprofit.integrations.third_party_widget_options", JSON.stringify([ { iframeUrl: "http://localhost:8080", // Your widget's URL enableChannelSupport: false, // Set to true if your widget supports channels title: "Angular Widget", imageUrl: "https://example.com/icon.png", // Replace with your widget icon URL }, ]) );
  Note:
  - Replace 'http://localhost:8080' with your actual widget URL if different.
  - Provide a valid imageUrl for the widget icon.
Reload the TakeProfit Platform

Refresh the TakeProfit platform page. Your Angular widget should now appear in the widget panel, allowing you to add it to the dashboard and interact with its functionalities.
Verify Functionality
- Security Change: Click on the “Set Security” buttons and observe the console logs for successful changes.
- Menu Items: Add the “Refresh Data” menu item and click it to see the corresponding console log. Test updating and removing the menu item to ensure they function as expected.

Once testing is successful, deploy your widget to a live environment.

Choose a Hosting Service

Select a hosting service that can serve Angular applications and supports custom HTTP headers. Some popular options include:
- Vercel
- Netlify
- AWS Amplify
- Heroku
Prepare Your Files for Deployment

Ensure all your files (dist/my-tp-widget, server.js, etc.) are correctly set up and that your server configuration (server.js) is compatible with your hosting service.
Deploy to Heroku (Example)

Here’s how to deploy your widget to Heroku with the necessary headers:
- Install Heroku CLI
  npm install -g heroku
- Log in to Heroku
  heroku login
- Create a New Heroku App
  heroku create your-app-name
  Replace your-app-name with your desired app name.
- Set Buildpacks
  
  Heroku needs to know how to build your app. Set the Node.js buildpack:
  heroku buildpacks:set heroku/nodejs
- Add a Procfile
  
  Create a Procfile in the root of your project to specify how to run your app:
  touch Procfile
  Add the following line to Procfile:
  web: node server.js
- Commit Your Changes
  git init git add . git commit -m "Initial commit"
- Deploy to Heroku
  git push heroku master
  Note: If you’re using the main branch, use git push heroku main instead.

Update Local Storage Configuration

After deployment, update the iframeUrl in the TakeProfit platform’s local storage to point to your deployed widget’s URL:

localStorage.setItem(
	"takeprofit.integrations.third_party_widget_options",
	JSON.stringify([
		{
			iframeUrl: "https://your-app-name.herokuapp.com", // Your deployed widget's URL
			enableChannelSupport: false,
			title: "Angular Widget",
			imageUrl: "https://yourdomain.com/icon.png", // Your widget's icon URL
		},
	])
);

Final Testing

Reload the TakeProfit platform and verify that your deployed widget functions correctly in the live environment. Test all functionalities, including security changes and menu item interactions, to ensure seamless integration.

Best Practices

Secure Communication: Always serve your widget over HTTPS to ensure secure communication with the TakeProfit platform.
Unique Identifiers: Ensure that requestId and menuItemId are unique to prevent conflicts.

Subscription Management: Always unsubscribe from state changes when they’re no longer needed to prevent memory leaks.

ngOnDestroy(): void {
  this.tpWidgetSdk.unsubscribeWidgetChange(this.handleWidgetChange.bind(this));
  this.tpWidgetSdk.unsubscribeChannelChange(this.handleChannelChange.bind(this));
  this.tpWidgetSdk.cleanupSDK();
}

Error Handling: Implement robust error handling for all asynchronous operations to enhance user experience.

async addMenuItem(): Promise<void> {
  try {
    const id = await this.tpWidgetSdk.addMenuItem('Refresh Data', () => {
      console.log('Refresh Data menu item clicked.');
      // Implement refresh logic here
    }, false);
    this.menuItemId = id;
    console.log(`Menu item added with ID: ${id}`);
  } catch (error) {
    console.error('Failed to add menu item:', error);
  }
}

Performance Optimization: Limit the number of active subscriptions and avoid unnecessary state updates to maintain optimal performance.
Code Documentation: Keep your code well-documented to facilitate maintenance and future enhancements.
Responsive Design: Ensure your widget is responsive and functions seamlessly across different devices and screen sizes.

Next Steps

Congratulations! You’ve successfully created and integrated your first widget using Angular and the TakeProfit Widget SDK (version 0.2.3). To further enhance your widget, consider the following:

Explore Advanced SDK Features: Refer to the SDK Reference to utilize all available methods and message types.
Implement Real-Time Data: Integrate real-time data feeds to provide dynamic and up-to-date information within your widget.
Customize the UI: Enhance the user interface with additional Angular components and styling to improve user engagement.
Add More Interactions: Implement more interactive features like custom events, notifications, and user preferences.
Optimize: Ensure your widget is responsive and functions seamlessly across different devices and screen sizes.
Security Enhancements: Implement additional security measures to safeguard data and ensure secure communication.

For comprehensive details, refer to the SDK Reference and other documentation resources provided by the TakeProfit Widget SDK.

Troubleshooting

If you encounter issues while setting up or using the TakeProfit Widget SDK, consider the following solutions:

SDK Not Connecting
- Check Origins: Ensure that your widget’s domain is allowed and matches the trusted origins (takeprofit.com).
- Network Issues: Verify that there are no network restrictions or firewall rules blocking communication.
Menu Items Not Appearing
- Local Storage Configuration: Double-check the iframeUrl and ensure it points to the correct widget URL.
- SDK Initialization: Ensure that TPWidgetSDK.connect() and TPWidgetSDK.hideLoader() are called successfully.
Security Change Fails
- Valid Security ID: Ensure that the securityID you are requesting is valid and recognized by the platform.
- Error Handling: Check the console for error messages to understand why the request failed.
Unhandled Promise Rejections
- Implement .catch Blocks: Ensure that all asynchronous SDK methods have proper error handling using .catch to manage rejected promises.
Performance Issues
- Optimize Subscriptions: Limit the number of active subscriptions and avoid unnecessary state updates.
- Efficient Rendering: Ensure that your Angular components are optimized to prevent unnecessary re-renders.

For persistent issues, refer to the Support and Resources section or contact the support team for assistance.

Additional Resources

Installation Guide: Detailed instructions for installing the SDK.
SDK Reference: Comprehensive documentation of all available methods, interfaces, and message types.
Creating Your First Widget: A practical guide to building and testing a basic widget.
Angular Documentation: Official Angular documentation for deeper understanding.
TypeScript Documentation: Learn more about TypeScript for enhanced type safety.
Express Documentation: Official Express documentation for server setup.
Content Security Policy (CSP) Documentation: Learn more about CSP for enhancing security.
HTTP Headers Documentation: Understand various HTTP headers for better configuration.

Getting Started

Guides

Reference

Prerequisites

Set Up Your Angular Project

Install the TakeProfit Widget SDK

Configure Security Headers

Initialize the SDK in Your Project

Create Your First Widget Component

Manage Widget State and Interactions

Add Menu Items

Test Your Widget Locally

Deploy Your Widget

Best Practices

Next Steps

Troubleshooting

Additional Resources

Getting Started

Guides

Reference

​Prerequisites

​Set Up Your Angular Project

​Install the TakeProfit Widget SDK

​Configure Security Headers

​Initialize the SDK in Your Project

​Create Your First Widget Component

​Manage Widget State and Interactions

​Add Menu Items

​Test Your Widget Locally

​Deploy Your Widget

​Best Practices

​Next Steps

​Troubleshooting

​Additional Resources

Prerequisites

Set Up Your Angular Project

Install the TakeProfit Widget SDK

Configure Security Headers

Initialize the SDK in Your Project

Create Your First Widget Component

Manage Widget State and Interactions

Add Menu Items

Test Your Widget Locally

Deploy Your Widget

Best Practices

Next Steps

Troubleshooting

Additional Resources