1. Create a new Python script in PyCharm with File > New, then select "Python File" and give it an informative name (the example uses "hello_world_1.py").
2. Paste the code below into your script:

   
   import shinybroker as sb
   
   # Create an instance of a ShinyBroker App object using the default ui and server
   app = sb.sb_app(
       host='127.0.0.1',  # localhost TWS is being served on your local machine
       port=7497,         # make this match the port in your API Settings config
       client_id=10742    # picked at random, choose another Client ID if preferred
   )
   
   # Run the app
   app.run()

   Copy Code
3. Run your Python script. There are many ways to do so, but one quick and easy way is to highlight all of the code in your script with "select all", right-click the selection, and choose "Execute Selection in Python Console". It's even faster with keyboard shortcuts, e.g., for a Mac: command-A to select all, then alt-shift-E to execute. You can find those commands, and their shortcuts, by right-clicking on highlighted code in PyCharm.
4. After you execute the code PyCharm will launch a new Python console to run the code you told it to run. Your screen should look something like the below. You can see what the code you ran did: it created a ShinyBroker app object and told it where to find an IBKR connection by specifying host, port, and client_id. By itself, that app object does nothing but sit there in variable space; to make it run, you have to call its run method, which we did in the final line of the sample code when we called app.run(). That command is the one that started the continuously-running Python process that you see in your Console. That process serves your ShinyBroker app at the blue hyperlink appearing in the command line output. The app will continue to run until you tell it to stop (e.g., by clicking the red square in the Python Console in PyCharm).
   
5. To view your app, click the hyperlink in the command line output. Doing so will open your first ShinyBroker App in your default browser! You can also copy-paste the url into a browser of your choice. (And if you're thinking can I serve the app on one computer and access the app via browser from another computer/phone in a different location the answer is "yes, you can", but that's a later topic)

When you navigate a browser to the url at which your app is being served, you should be greeted with an app that looks something like the screen snip below.

Take a few minutes to poke around in the app and try out some of the default tabs & tools provided for tasks involving market data, contract matching, socket messages from IBKR, and so on.

Especially important to note is the section on the home page, which currently reads no ui passed to sb_ui(). That space is special -- it is reserved for you, the trader, to put UI elements and controls for your trading system. Since no ui was specified when we created this simple app object in this hello world example, ShinyBroker is telling you that it's empty.

We'll conclude this tutorial in the next step by injecting a little bit of ui into that space.

First, we'll need the two pieces of UI that will appear on the web page: an input for the user to type into, and an output to see the result. We'll use the input_text and output_code objects made available by the ui object in Shiny, and store them together in a div, with the input on top of the output. All sorts of different components are available both in Shiny and in other packages like shinywidgets, or you can build your own. In this example, however, we'll only need two components: input_text and output_code. In the code below we use these components to create a new piece of ui and assign to it the appropriate name a_piece_of_new_ui.

from shiny import ui

# Some UI to add to the app
a_piece_of_new_ui = ui.div(
    ui.input_text(
        id='sb_example_text_in',
        label='Example Input. Type something!'
    ),
    ui.output_code('sb_example_text_out')
)

Now we need some logic: a function that recognizes the input text box (which we named sb_example_text_in above) as an input that it needs to watch. It should also possess the additional properties such that, whenever the text in the input changes, the function executes, calculates the new string that we want for the text output, and sends that value to the output object that we named sb_example_text_out. ShinyBroker uses the Shiny framework (see the video above) to simplify all of the 'watching and updating' tasks in order to make it easy to write a function that does the job.

In Shiny-speak, what we want to write is called a rendering function, a special type of function that was created for exactly the kind of 'watching and updating' functionality that we need. A suitable rendering function is provided below but if you're new to Shiny, consider the following bullet points to help you understand rendering functions and why the code is written the way it is so that you can be better equipped to write your own.

• Shiny takes into consideration the names you give to your server functions and uses them to figure out where the return values should be passed. In most use cases, including the current tutorial, that's a lot simpler than it sounds because it boils down to: when you write your function, just give it the same name as the output you want it to update. That simple 'rule' will get you through 95% of your use cases. In our case, we want to update the output object named sb_example_text_out, so that's the name we'll assign to our function.
• We want the function to run every time the value of the input box sb_example_text_in changes, so somewhere within the function's body we'll need to call input.sb_example_text_in() to fetch the contents of the input box. Shiny handles the rest, which is extremely convenient because it allows you to treat input .sb_example_text_in() almost like a variable that you can always trust to contain "whatever is currently in the input box". Note that calling an input function to get its value carries with it a computational expense, so if you find yourself making calls to the same input more than once within the same render function, it's probably bad code. You're most likely better off if you just make the call once, store the input's value as a local variable, and then use that variable in the rest of your function code.
• Finally, we want to communicate to Shiny that our function is indeed a rendering function, which we can do by decorating it with a @render decorator. All sorts of render decorators are available, and of course you can write your own, but we'll be using @render.code so that the output text looks cool and monospaced-formatted like computer code. You can try stopping and re-running your app with other decorators like @render.text to see what happens with other sorts of decorators.

Taking all that into account, a render function that suits our purposes might look like the one below:

    @render.code
    def sb_example_text_out():
        return f"You entered '{input.sb_example_text_in()}'."

All that's left is to put that function into an app! Fortunately, ShinyBroker makes that easy. In practice, when making a real trading app, you will probably have tons of different functions required to make the app work, perhaps stored in different files, doing tasks like calculating your models, updating your charts, outputs, and so on. No matter how many you have, you can include all your functions in your app simply by wrapping them into one overall server function that you can pass to sb.sb_app() when you build your ShinyBroker app. It does not matter what you name your server function; the only requirement is that its signature contains the five parameters input: Inputs, output: Outputs, session: Session, ib_socket, sb_rvs. The part of your app that you, the the trader, will write will not always, or even usually, make use all five parameters explicitly, but they need to be there in your server function so that ShinyBroker can keep track of session information in its internals.

Below, we do exactly that: wrap the render function we just wrote into a new server function named a_server_function.

from shiny import Inputs, Outputs, Session, ui, render

# Server to support the new UI
# Signature must always contain the following five parameters:
#   input, output, session, ib_socket, and sb_rvs
def a_server_function(
        input: Inputs, output: Outputs, session: Session, ib_socket, sb_rvs
):
    @render.code
    def sb_example_text_out():
        return f"You entered '{input.sb_example_text_in()}'."

And finally... here comes the magic of ShinyBroker. We can create a new ShinyBroker app by passing our ui and server functions as arguments to sb_app:

import shinybroker as sb

# Create a ShinyBroker app with the new ui and server
app = sb.sb_app(
    a_piece_of_new_ui,
    a_server_function,
    host='127.0.0.1',
    port=7497,
    client_id=10742
)

And that's it! Altogether, the fully completed code example, including app.run(), can be found below:

import shinybroker as sb
from shiny import Inputs, Outputs, Session, ui, render


# Some UI to add to the app
a_piece_of_new_ui = ui.div(
    ui.input_text(
        id='sb_example_text_in',
        label='Example Input. Type something!'
    ),
    ui.output_code('sb_example_text_out')
)


# Server to support the new UI
# Signature must always contain the following five parameters:
#   input, output, session, ib_socket, and sb_rvs
def a_server_function(
        input: Inputs, output: Outputs, session: Session, ib_socket, sb_rvs
):
    @render.code
    def sb_example_text_out():
        return f"You entered '{input.sb_example_text_in()}'."


# Create a ShinyBroker app with the new ui and server
app = sb.sb_app(
    a_piece_of_new_ui,
    a_server_function,
    host='127.0.0.1',
    port=7497,
    client_id=10742
)

app.run()
                        

Run your app and view it in a browser like you did in Step 4. You should see something like the below in your Home tab, and the output should update with whatever you type into the input: