Merge pull request #13 from ChartIQ/26868-security-finder-documentation

additional docs for the SecurityFinder example and preload's ready event

docs/README.md

@@ -1,6 +1,6 @@
-[Finsemble-Bloomberg](README.md) › [Globals](globals.md)
+[finsemble-bloomberg](README.md) › [Globals](globals.md)
 
-# Finsemble Bloomberg Integration
+# finsemble-bloomberg
 
 [![Finsemble Logo](https://documentation.chartiq.com/finsemble/styles/img/Finsemble_Logo_Dark.svg)](https://documentation.chartiq.com/finsemble/)
 
@@ -49,7 +49,7 @@ A number of examples of using the integration are provided:
 - **[testBloomberg](../src/components/testBloomberg)**: A test component demonstrating use of all API functions.
 - **[Bloomberg Terminal](../src/components/Bloomberg%20Terminal)**: An example configuration for launching the Bloomberg terminal itself
 - **[Coming Soon: Desktop service for FDC3 integration](#)**: An example service that works with the FDC3 channel matcher service to facilitate context sharing with FDC3 system channels in Finsemble and provides an example of instrument/security translation that may be required. See the [Finsemble FDC3 Implementation](https://github.com/ChartIQ/finsemble-fdc3) project for more details on the FDC3 channel matcher service.
-- **[Coming Soon: Security finder example](#)**: An example that demonstrates the use of the SecurityLookup function of the Bloomberg Bridge to implement a search with typeahead for Bloomberg sercurities, which may be used to set the context of launchpad groups.
+- **[Security finder example](../src/components/SecurityFinder)**: An example that demonstrates the use of the SecurityLookup function of the Bloomberg Bridge to implement a search with typeahead for Bloomberg securities, which may be used to set the context of launchpad groups, perform commands or add to worksheets. It can also receive context via the Finsemble Linker and help you resolve it to Bloomberg Security
 
 ## Installation
 This project contains:
@@ -64,7 +64,7 @@ In order to use the Javascript and Typescript examples, you can either copy the
 
 ### Files
 ```
-finsmble-bloomberg
+finsemble-bloomberg
 |   .gitignore                   - gitignore file configured for both javascript and .Net projects
 |   BloombergIntegration.sln     - Visual studio solution for building the .Net Bloomberg Bridge app  
 |   finsemble.config.json        - Watch script config and Finsemble examples config imports 
@@ -100,10 +100,10 @@ finsmble-bloomberg
     |           BloombergBridgeClient.ts - Typescript client class and preload for use with BloombergBridge
     |
     └───components
-    |   └───Bloomberg Bridge         - Congfigs for launching the Bloomberg Bridge
+    |   └───Bloomberg Bridge         - Configs for launching the Bloomberg Bridge
     |   └───Bloomberg Terminal       - Example config for launching the Bloomberg terminal
+    |   └───SecurityFinder           - Security lookup example, demonstrating a realistic use-case
     |   └───testBloomberg            - Test component demonstrating use of all API functions
-    |   └───SecurityFinder           - Coming soon!
     |
     └───services                     
         └───BloombergFDC3Service     - Coming soon!
@@ -121,14 +121,14 @@ To use the watch script:
 
 3) If you clone in a different location, open [finsemble.config.json](../finsemble.config.json) and update `seedProjectDirectory` with the path to your local Finsemble Seed Project. If you intend to build an debug the \(.Net\) BloombergBridge, also set the value of the `$bloombergBridgeFolder` variable to point to the [BloombergBridge folder](../BloombergBridge) in this project \(see the [Finsemble config documentation](https://documentation.chartiq.com/finsemble/tutorial-Configuration.html#configuration-variables) for more details on setting variables\).
 
-4) To use the SecurityFinder example, you will also need to install a dependency in your seed project by running:
-```
-npm install react-autosuggest
-```
-
-5) Run `npm install` then run `npm run watch` in the _finsemble-bloomberg_ project's directory
+4) Run `npm install` then run `npm run watch` in the _finsemble-bloomberg_ project's directory
 **this will continue to watch for file changes and will copy across updated files as needed, this can be stopped once all the files have been copied to the seed project approx. 30 seconds*
 
+5) To build and run the SecurityFinder example, you will also need to install dependencies in your seed project by running:
+    ```
+	npm install react-tabs react-select react-autosuggest
+	```
+
 6) Your seed project directory has now been updated with the source files from the integration, run `npm run dev` in your Finsemble seed project's directory to build and run locally.
 
 ### Manual installation
@@ -165,10 +165,10 @@ To manually install the integration into your Finsemble project:
     ```Javascript
     import BloombergBridgeClient from "../../clients/BloombergBridgeClient/BloombergBridgeClient";
     ```
-    
-	**Note:** To use the SecurityFinder example, you will also need to install a dependency in your seed project by running:
-	```
-	npm install react-autosuggest
+
+6) To build and run the SecurityFinder example, you will also need to install dependencies in your project by running:
+    ```
+	npm install react-tabs react-select react-autosuggest
 	```
 
 ## Building and Deploying the Bloomberg Bridge
@@ -246,6 +246,20 @@ For the purposes of the following examples you can create a reference to it as f
 let bbg = FSBL.Clients.BloombergBridgeClient;
 ```
 
+As setup of the client occurs when the Finsemble clients are themselves ready (on the FSBLReady event), the preload will dispatch its own event when the BloombergBridgeClient is ready: `BloombergBridgeClientReady`. To avoid race conditions, you should wait on this event, rather than `FSBLReady`, in your components, e.g.:
+
+```Javascript
+window.addEventListener("BloombergBridgeClientReady", BBGReady);
+
+function BBGReady() {
+	//Do your setup, which can assume both FSBL and the BloombergBridgeClient are ready e.g.:
+	ReactDOM.render(
+		<SecurityFinder />,
+		document.getElementById('root')
+	);
+}
+```
+
 #### Instantiating the BloombergBridgeClient
 If you are not using the BloombergBridgeClient as a preload in a component (when it will instantiate itself using the RouterClient and Logger instance already preloaded into the window) you must instantiate by passing a Finsemble RouterClient and Logger, e.g. in a componet:
 ```Javascript

docs/classes/_bloombergbridgeclient_.bloombergbridgeclient.md

@@ -52,7 +52,7 @@ via instances of the RouterClient and Logger referenced from `FSBL.Clients`.
 
 \+ **new BloombergBridgeClient**(`routerClient?`: IRouterClient, `logger?`: ILogger): *[BloombergBridgeClient](_bloombergbridgeclient_.bloombergbridgeclient.md)*
 
-*Defined in [BloombergBridgeClient.ts:80](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L80)*
+*Defined in [BloombergBridgeClient.ts:80](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L80)*
 
 BloombergBridgeClient constructor.
 
@@ -84,39 +84,39 @@ Name | Type | Description |
 
 • **connectionEventListener**: *[BBGConnectionEventListener](../interfaces/_bloombergbridgeclient_.bbgconnectioneventlistener.md)* = null
 
-*Defined in [BloombergBridgeClient.ts:77](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L77)*
+*Defined in [BloombergBridgeClient.ts:77](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L77)*
 
 ___
 
 ### `Private` groupEventListener
 
 • **groupEventListener**: *[BBGGroupEventListener](../interfaces/_bloombergbridgeclient_.bbggroupeventlistener.md)* = null
 
-*Defined in [BloombergBridgeClient.ts:78](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L78)*
+*Defined in [BloombergBridgeClient.ts:78](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L78)*
 
 ___
 
 ### `Private` logger
 
 • **logger**: *ILogger* = null
 
-*Defined in [BloombergBridgeClient.ts:80](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L80)*
+*Defined in [BloombergBridgeClient.ts:80](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L80)*
 
 ___
 
 ### `Private` routerClient
 
 • **routerClient**: *IRouterClient* = null
 
-*Defined in [BloombergBridgeClient.ts:79](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L79)*
+*Defined in [BloombergBridgeClient.ts:79](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L79)*
 
 ## Methods
 
 ### `Private` apiResponseHandler
 
 ▸ **apiResponseHandler**(`cb`: function): *(Anonymous function)*
 
-*Defined in [BloombergBridgeClient.ts:294](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L294)*
+*Defined in [BloombergBridgeClient.ts:294](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L294)*
 
 Internal function used to return a call back that will wrap the supplied callback and log all
 responses
@@ -148,7 +148,7 @@ ___
 
 ▸ **checkConnection**(`cb`: function): *void*
 
-*Defined in [BloombergBridgeClient.ts:243](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L243)*
+*Defined in [BloombergBridgeClient.ts:243](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L243)*
 
 Check that Bloomberg bridge is connected to the Bloomberg Terminal and that a user is
 logged in.
@@ -189,7 +189,7 @@ ___
 
 ▸ **queryBloombergBridge**(`message`: object, `cb`: function): *void*
 
-*Defined in [BloombergBridgeClient.ts:278](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L278)*
+*Defined in [BloombergBridgeClient.ts:278](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L278)*
 
 Internal function used to send a Query to the BBG_run_terminal_function responder of
 BloombergBridge,
@@ -226,7 +226,7 @@ ___
 
 ▸ **removeConnectionEventListener**(): *void*
 
-*Defined in [BloombergBridgeClient.ts:162](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L162)*
+*Defined in [BloombergBridgeClient.ts:162](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L162)*
 
 Remove the current connection event handler.
 
@@ -243,7 +243,7 @@ ___
 
 ▸ **removeGroupEventListener**(): *void*
 
-*Defined in [BloombergBridgeClient.ts:217](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L217)*
+*Defined in [BloombergBridgeClient.ts:217](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L217)*
 
 Remove the current group context changed event handler.
 
@@ -260,7 +260,7 @@ ___
 
 ▸ **runBBGCommand**(`mnemonic`: string, `securities`: string[], `panel`: string, `tails`: string, `cb`: function): *void*
 
-*Defined in [BloombergBridgeClient.ts:340](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L340)*
+*Defined in [BloombergBridgeClient.ts:340](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L340)*
 
 Run a function in one of the 4 Bloomberg panel windows.
 
@@ -323,7 +323,7 @@ ___
 
 ▸ **runCreateWorksheet**(`worksheetName`: string, `securities`: string[], `cb`: function): *void*
 
-*Defined in [BloombergBridgeClient.ts:382](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L382)*
+*Defined in [BloombergBridgeClient.ts:382](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L382)*
 
 Create a new worksheet with the specified securities and name.
 
@@ -381,7 +381,7 @@ ___
 
 ▸ **runGetAllGroups**(`cb`: function): *void*
 
-*Defined in [BloombergBridgeClient.ts:528](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L528)*
+*Defined in [BloombergBridgeClient.ts:528](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L528)*
 
 Gets a list of all available Launchpad component groups.
 
@@ -433,7 +433,7 @@ ___
 
 ▸ **runGetAllWorksheets**(`cb`: function): *void*
 
-*Defined in [BloombergBridgeClient.ts:419](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L419)*
+*Defined in [BloombergBridgeClient.ts:419](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L419)*
 
 Retrieve all worksheets for the user.
 
@@ -483,7 +483,7 @@ ___
 
 ▸ **runGetGroupContext**(`groupName`: string, `cb`: function): *void*
 
-*Defined in [BloombergBridgeClient.ts:560](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L560)*
+*Defined in [BloombergBridgeClient.ts:560](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L560)*
 
 Returns details of a Launchpad component group by name.
 
@@ -536,7 +536,7 @@ ___
 
 ▸ **runGetWorksheet**(`worksheetId`: string, `cb`: function): *void*
 
-*Defined in [BloombergBridgeClient.ts:454](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L454)*
+*Defined in [BloombergBridgeClient.ts:454](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L454)*
 
 Retrieve a specific worksheet by id.
 
@@ -589,7 +589,7 @@ ___
 
 ▸ **runReplaceWorksheet**(`worksheetId`: string, `securities`: string[], `cb`: function): *void*
 
-*Defined in [BloombergBridgeClient.ts:490](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L490)*
+*Defined in [BloombergBridgeClient.ts:490](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L490)*
 
 Replaces a specific worksheet by ID with a new list of securities.
 
@@ -646,7 +646,7 @@ ___
 
 ▸ **runSecurityLookup**(`security`: string, `cb`: function): *void*
 
-*Defined in [BloombergBridgeClient.ts:638](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L638)*
+*Defined in [BloombergBridgeClient.ts:638](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L638)*
 
 Search for Bloomberg securities via the Bloomberg Bridge and BLP API, which will return
 results in around ~120-150ms and maybe used, for example, to power an autocomplete or
@@ -702,7 +702,7 @@ ___
 
 ▸ **runSetGroupContext**(`groupName`: string, `value`: string, `cookie`: string | null, `cb`: function): *void*
 
-*Defined in [BloombergBridgeClient.ts:594](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L594)*
+*Defined in [BloombergBridgeClient.ts:594](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L594)*
 
 Set the context value of a Launchpad group by name.
 
@@ -760,7 +760,7 @@ ___
 
 ▸ **setConnectionEventListener**(`cb`: [BBGConnectionEventListener](../interfaces/_bloombergbridgeclient_.bbgconnectioneventlistener.md)): *void*
 
-*Defined in [BloombergBridgeClient.ts:138](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L138)*
+*Defined in [BloombergBridgeClient.ts:138](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L138)*
 
 Set a handler function for connection events.
 
@@ -793,7 +793,7 @@ ___
 
 ▸ **setGroupEventListener**(`cb`: [BBGGroupEventListener](../interfaces/_bloombergbridgeclient_.bbggroupeventlistener.md)): *void*
 
-*Defined in [BloombergBridgeClient.ts:194](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L194)*
+*Defined in [BloombergBridgeClient.ts:194](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L194)*
 
 Set a handler function for Launchpad group context changed events, which
 are fired when a group's context changes or a new group is created.

docs/interfaces/_bloombergbridgeclient_.bbgconnectioneventlistener.md

@@ -13,7 +13,7 @@ when the BloombergBridge connects or disconnects from the terminal.
 
 ▸ (`err`: string | Error, `response`: RouterMessage‹object›): *void*
 
-*Defined in [BloombergBridgeClient.ts:13](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L13)*
+*Defined in [BloombergBridgeClient.ts:13](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L13)*
 
 Interface representing an event handler for connection events, which are fired
 when the BloombergBridge connects or disconnects from the terminal.

docs/interfaces/_bloombergbridgeclient_.bbggroup.md

@@ -27,20 +27,20 @@ the form 'Group-A'.
 
 • **name**: *string*
 
-*Defined in [BloombergBridgeClient.ts:63](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L63)*
+*Defined in [BloombergBridgeClient.ts:63](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L63)*
 
 ___
 
 ###  type
 
 • **type**: *string*
 
-*Defined in [BloombergBridgeClient.ts:62](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L62)*
+*Defined in [BloombergBridgeClient.ts:62](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L62)*
 
 ___
 
 ###  value
 
 • **value**: *string*
 
-*Defined in [BloombergBridgeClient.ts:64](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L64)*
+*Defined in [BloombergBridgeClient.ts:64](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L64)*

docs/interfaces/_bloombergbridgeclient_.bbggroupeventlistener.md

@@ -12,7 +12,7 @@ Interface representing an event handler for Bloomberg group events.
 
 ▸ (`err`: string | Error, `response`: RouterMessage‹object›): *void*
 
-*Defined in [BloombergBridgeClient.ts:30](https://github.com/ChartIQ/finsemble-bloomberg/blob/a77c7be/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L30)*
+*Defined in [BloombergBridgeClient.ts:30](https://github.com/ChartIQ/finsemble-bloomberg/blob/ea40ce4/src/clients/BloombergBridgeClient/BloombergBridgeClient.ts#L30)*
 
 Interface representing an event handler for Bloomberg group events.