# page._Page { #powerbpy.page._Page }

```python
page._Page(dashboard, page_id=None)
```

A python class used to model a power BI dashboard page.

You should never initate a page class directly, instead use `Dashboard.new_page()` to create a new page, or `Dashboard.load_page()` to load an existing page. This class is important however because its methods are public. The reason you should never create an instance of the _Page class directly is simple -- it doesn't make sense to have a page not attached to a dashboard.

Here's an example workflow:
```python
from powerbpy import Dashboard

# Create a new dashboard
my_dashboard = Dashboard.create("C:/Users/Russ/PBI_projects/test_dashboard")

# Create a new page
page1 = my_dashboard.new_page("Page 1")

# Add a visual to page 1

page1.add_text_box(text = "Explanatory text in the bottom right corner",
             visual_id = "page1_explain_box",
             height = 200,
               width= 300,
                 x_position = 1000,
                 y_position = 600,
                 font_size = 15)


```

## Methods

| Name | Description |
| --- | --- |
| [add_background_image](#powerbpy.page._Page.add_background_image) | Add a background image to a dashboard page |
| [add_button](#powerbpy.page._Page.add_button) | Add a button to a page |
| [add_card](#powerbpy.page._Page.add_card) | Add a card to a page |
| [add_chart](#powerbpy.page._Page.add_chart) | This function adds a new chart to a page in a power BI dashboard report. |
| [add_sanky_chart](#powerbpy.page._Page.add_sanky_chart) | This function adds a new chart to a page in a power BI dashboard report. |
| [add_shape_map](#powerbpy.page._Page.add_shape_map) | Add a map to a page |
| [add_slicer](#powerbpy.page._Page.add_slicer) | Add a slicer to a page |
| [add_table](#powerbpy.page._Page.add_table) | This function adds a new table to a page in a power BI dashboard report. |
| [add_text_box](#powerbpy.page._Page.add_text_box) | Add a text box to a page |

### add_background_image { #powerbpy.page._Page.add_background_image }

```python
page._Page.add_background_image(img_path, *, alpha=51, scaling_method='Fit')
```

Add a background image to a dashboard page

#### Parameters {.doc-section .doc-section-parameters}

| Name           | Type   | Description                                                                                                                                                                                               | Default    |
|----------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| img_path       |        | The path to the image you want to add. (Can be a relative path because the image is copied to the report folder). Allowed image types are whatever PBI allows manually, so probably at least jpeg and png | _required_ |
| alpha          |        | The transparency of the background image. Must be a whole integer between 1 and 100.                                                                                                                      | `51`       |
| scaling_method |        | The method used to scale the image available options include ["Fit", ]                                                                                                                                    | `'Fit'`    |

#### Notes {.doc-section .doc-section-notes}

Here's how you can add a background image to a page. To add the image, you'll need to provide the following required argument:
    1. `img_path` - This is the path (relative or full) to the image you want to add to the dashboard

There are two additional optional arguments:
    2. `alpha` - This is the image's transparency with 0 is fully transparent and 100 is full non-transparent (defaults to 100 )
    3. `scaling_method` - This tells Power BI how to scale the image (defaults to "Fit" which fits the image to the page)

Here's some example code that adds a new background image to the Bee Colonies page:

```python
    page1.add_background_image(img_path = "examples/data/Taipei_skyline_at_sunset_20150607.jpg",
           alpha = 51,
           scaling_method = "Fit")
```
And here's what the dashboard looks like, now that we've added a background image:
![Background Image Example](https://github.com/Russell-Shean/powerbpy/raw/main/docs/assets/images/background_image_example.png?raw=true "Background Image Example")

### add_button { #powerbpy.page._Page.add_button }

```python
page._Page.add_button(
    label,
    visual_id,
    height,
    width,
    x_position,
    y_position,
    z_position=6000,
    tab_order=-1001,
    fill_color='#3086C3',
    alpha=0,
    url_link=None,
    page_navigation_link=None,
    alt_text='A button',
    background_color=None,
    background_color_alpha=None,
)
```

Add a button to a page

#### Parameters {.doc-section .doc-section-parameters}

| Name                 | Type   | Description                                                                                                                                                                                                                                                                                                                                                    | Default     |
|----------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
| label                | str    | The text you want to display inside the button                                                                                                                                                                                                                                                                                                                 | _required_  |
| visual_id            |        | Please choose a unique id to use to identify the button. PBI defaults to using a UUID, but it'd probably be easier if you choose your own id.                                                                                                                                                                                                                  | _required_  |
| height               |        | Height of text box on the page                                                                                                                                                                                                                                                                                                                                 | _required_  |
| width                |        | Width of text box on the page                                                                                                                                                                                                                                                                                                                                  | _required_  |
| x_position           |        | The x coordinate of where you want to put the text box on the page. Origin is page's top left corner.                                                                                                                                                                                                                                                          | _required_  |
| y_position           |        | The y coordinate of where you want to put the text box on the page. Origin is page's top left corner.                                                                                                                                                                                                                                                          | _required_  |
| z_position           |        | The z index for the visual. (Larger number means more to the front, smaller number means more to the back). Defaults to 6000                                                                                                                                                                                                                                   | `6000`      |
| tab_order            |        | The order which the screen reader reads different elements on the page. Defaults to -1001 for now. (I need to do more to figure out what the numbers correpond to. It should also be possible to create a function to automatically order this left to right top to bottom by looping through all the visuals on a page and comparing their x and y positions) | `-1001`     |
| fill_color           |        | Hex code for the background (fill) color you'd like to use for the button. Defaults to blue (#3086C3)                                                                                                                                                                                                                                                          | `'#3086C3'` |
| alpha                |        | The transparency of the fill color. Must be a whole integer between 1 and 100. Defaults to 0 (100% not transparent)                                                                                                                                                                                                                                            | `0`         |
| url_link             |        | Optional argument. If provided, the button will navigate to this URL. Should be a full, not relative url                                                                                                                                                                                                                                                       | `None`      |
| page_navigation_link |        | Optional argument. If provided the button will navigate to this page in the report. Must be a valid page_id already present in the report.                                                                                                                                                                                                                     | `None`      |

#### Notes {.doc-section .doc-section-notes}

This function creates a new button on a page.

### add_card { #powerbpy.page._Page.add_card }

```python
page._Page.add_card(
    data_source,
    measure_name,
    visual_id,
    height,
    width,
    x_position,
    y_position,
    z_position=6000,
    tab_order=-1001,
    card_title=None,
    font_weight='bold',
    font_size=32,
    font_color='#000000',
    background_color=None,
    background_color_alpha=None,
    parent_group_id=None,
    alt_text='A card',
)
```

Add a card to a page

#### Parameters {.doc-section .doc-section-parameters}

| Name             | Type   | Description                                                                                                                                                                                                                                                                                                                                                    | Default     |
|------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
| data_source      |        | This is the name of the dataset that you want to use to populate the card with                                                                                                                                                                                                                                                                                 | _required_  |
| measure_name     |        | This is the name of the measure (or variable) name you want to use to populate the card with                                                                                                                                                                                                                                                                   | _required_  |
| visual_id        |        | Please choose a unique id to use to identify the card. PBI defaults to using a UUID, but it'd probably be easier if you choose your own id.                                                                                                                                                                                                                    | _required_  |
| height           |        | Height of card on the page                                                                                                                                                                                                                                                                                                                                     | _required_  |
| width            |        | Width of card on the page                                                                                                                                                                                                                                                                                                                                      | _required_  |
| x_position       |        | The x coordinate of where you want to put the card on the page. Origin is page's top left corner.                                                                                                                                                                                                                                                              | _required_  |
| y_position       |        | The y coordinate of where you want to put the card on the page. Origin is page's top left corner.                                                                                                                                                                                                                                                              | _required_  |
| z_position       |        | The z index for the visual. (Larger number means more to the front, smaller number means more to the back). Defaults to 6000                                                                                                                                                                                                                                   | `6000`      |
| tab_order        |        | The order which the screen reader reads different elements on the page. Defaults to -1001 for now. (I need to do more to figure out what the numbers correpond to. It should also be possible to create a function to automatically order this left to right top to bottom by looping through all the visuals on a page and comparing their x and y positions) | `-1001`     |
| card_title       |        | An optional title to add to the card.                                                                                                                                                                                                                                                                                                                          | `None`      |
| font_weight      |        | This is an option to change the font's weight. Defaults to bold. Available options include: ["bold"]                                                                                                                                                                                                                                                           | `'bold'`    |
| font_size        |        | The font size in pts. Must be a whole integer. Defaults to 32 pt                                                                                                                                                                                                                                                                                               | `32`        |
| font_color       |        | Hex code for the font color you'd like to use. Defaults to black (#000000)                                                                                                                                                                                                                                                                                     | `'#000000'` |
| background_color |        | Hex code for the background color of the card. Defaults to None (transparent)                                                                                                                                                                                                                                                                                  | `None`      |
| parent_group_id  |        | This should be a valid id code for another power BI visual. If supplied the current visual will be nested inside the parent group.                                                                                                                                                                                                                             | `None`      |

#### Notes {.doc-section .doc-section-notes}

This function creates a new card on a page.

### add_chart { #powerbpy.page._Page.add_chart }

```python
page._Page.add_chart(
    visual_id,
    data_source,
    chart_title,
    x_axis_title,
    y_axis_title,
    x_axis_var,
    y_axis_var,
    y_axis_var_aggregation_type,
    x_position,
    y_position,
    height,
    width,
    chart_type='columnChart',
    background_color='#FFFFFF',
    background_color_alpha=None,
    tab_order=-1001,
    z_position=6000,
    parent_group_id=None,
    alt_text='A chart',
)
```

This function adds a new chart to a page in a power BI dashboard report.

#### Parameters {.doc-section .doc-section-parameters}

| Name                        | Type   | Description                                                                                                                                                                                                                                                                                                                                                    | Default         |
|-----------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|
| visual_id                   |        | Please choose a unique id to use to identify the chart. PBI defaults to using a UUID, but it'd probably be easier if you choose your own id.                                                                                                                                                                                                                   | _required_      |
| chart_type                  |        | The type of chart to build on the page. Known available types include: ["columnChart","barChart", "clusteredBarChart", ]                                                                                                                                                                                                                                       | `'columnChart'` |
| data_source                 |        | The name of the dataset you want to use to build the chart. This corresponds to the dataset_name field in the add data functions. You must have already loaded the data to the dashboard.                                                                                                                                                                      | _required_      |
| chart_title                 |        | Give your chart an informative title!:D                                                                                                                                                                                                                                                                                                                        | _required_      |
| x_axis_title                |        | Text to display on the x axis                                                                                                                                                                                                                                                                                                                                  | _required_      |
| y_axis_title                |        | Text to display on the y axis                                                                                                                                                                                                                                                                                                                                  | _required_      |
| x_axis_var                  |        | Column name of a column from data_source that you want to use for the x axis of the chart                                                                                                                                                                                                                                                                      | _required_      |
| y_axis_var                  |        | Column name of a column from data_source that you want to use for the y axis of the chart                                                                                                                                                                                                                                                                      | _required_      |
| y_axis_var_aggregation_type |        | Type of aggregation method you want to use to summarize y axis variable. Available options include" ["Sum", "Count", "Average"]                                                                                                                                                                                                                                | _required_      |
| x_position                  |        | The x coordinate of where you want to put the chart on the page. Origin is page's top left corner.                                                                                                                                                                                                                                                             | _required_      |
| y_position                  |        | The y coordinate of where you want to put the chart on the page. Origin is page's top left corner.                                                                                                                                                                                                                                                             | _required_      |
| height                      |        | Height of chart on the page                                                                                                                                                                                                                                                                                                                                    | _required_      |
| width                       |        | Width of chart on the page                                                                                                                                                                                                                                                                                                                                     | _required_      |
| tab_order                   |        | The order which the screen reader reads different elements on the page. Defaults to -1001 for now. (I need to do more to figure out what the numbers correpond to. It should also be possible to create a function to automatically order this left to right top to bottom by looping through all the visuals on a page and comparing their x and y positions) | `-1001`         |
| z_position                  |        | The z index for the visual. (Larger number means more to the front, smaller number means more to the back). Defaults to 6000                                                                                                                                                                                                                                   | `6000`          |

### add_sanky_chart { #powerbpy.page._Page.add_sanky_chart }

```python
page._Page.add_sanky_chart(
    visual_id,
    data_source,
    starting_var,
    starting_var_values,
    ending_var,
    ending_var_values,
    values_from_var,
    x_position,
    y_position,
    height,
    width,
    chart_title,
    link_colors=None,
    alt_text='A sankey chart',
    parent_group_id=None,
    background_color='#FFFFFF',
    background_color_alpha=None,
    chart_title_font_size=17,
    tab_order=-1001,
    z_position=6000,
)
```

This function adds a new chart to a page in a power BI dashboard report.

#### Parameters {.doc-section .doc-section-parameters}

| Name                  | Type   | Description                                                                                                                                                                                                                                                                                                                                                    | Default            |
|-----------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------|
| visual_id             |        | Please choose a unique id to use to identify the chart. PBI defaults to using a UUID, but it'd probably be easier if you choose your own id.                                                                                                                                                                                                                   | _required_         |
| data_source           |        | The name of the dataset you want to use to build the chart. This corresponds to the dataset_name field in the add data functions. You must have already loaded the data to the dashboard.                                                                                                                                                                      | _required_         |
| starting_var          |        | Which variable from the data_source, do you want to use for the left side of the sanky chart?                                                                                                                                                                                                                                                                  | _required_         |
| starting_var_values   |        | Which individual values do you want to use for the left side of the sanky chart? In general, this will probably mean all the unique values in the starting_var column. This function is setup to assume that you already know the structure of your data and can pass a list of unique values.                                                                 | _required_         |
| ending_var            |        | Which variable from the data_source, do you want to use for the right side of the sanky chart?                                                                                                                                                                                                                                                                 | _required_         |
| ending_var_values     |        | Which individual values do you want to use for the right side of the sanky chart? In general, this will probably mean all the unique values in the starting_var column. This function is setup to assume that you already know the structure of your data and can pass a list of unique values.                                                                | _required_         |
| values_from_var       |        | This is the variable that you want to count unique instances of as grouped by starting and ending variables. For now it only counts unique variables, but I'd like to add the option to provide a sum too                                                                                                                                                      | _required_         |
| chart_title           |        | Give your chart an informative title!:D                                                                                                                                                                                                                                                                                                                        | _required_         |
| alt_text              |        | Alternate text for the visualization can be provided as an argument. This is important for screen readers (accesibility) or if the visualization doesn't load properly.                                                                                                                                                                                        | `'A sankey chart'` |
| chart_title_font_size |        | Font size for chart title                                                                                                                                                                                                                                                                                                                                      | `17`               |
| link_colors           |        | Here you can provide a list of Hex code colors for the connections between the different categories in the Sanky chart. In general this should be equal to the length of starting_var_values multiplied by the length of ending_var_values. If an argument is not provided the function assigns default colors.                                                | `None`             |
| x_position            |        | The x coordinate of where you want to put the chart on the page. Origin is page's top left corner.                                                                                                                                                                                                                                                             | _required_         |
| y_position            |        | The y coordinate of where you want to put the chart on the page. Origin is page's top left corner.                                                                                                                                                                                                                                                             | _required_         |
| height                |        | Height of chart on the page                                                                                                                                                                                                                                                                                                                                    | _required_         |
| width                 |        | Width of chart on the page                                                                                                                                                                                                                                                                                                                                     | _required_         |
| tab_order             |        | The order which the screen reader reads different elements on the page. Defaults to -1001 for now. (I need to do more to figure out what the numbers correpond to. It should also be possible to create a function to automatically order this left to right top to bottom by looping through all the visuals on a page and comparing their x and y positions) | `-1001`            |
| z_position            |        | The z index for the visual. (Larger number means more to the front, smaller number means more to the back). Defaults to 6000                                                                                                                                                                                                                                   | `6000`             |

### add_shape_map { #powerbpy.page._Page.add_shape_map }

```python
page._Page.add_shape_map(
    visual_id,
    data_source,
    shape_file_path,
    map_title,
    location_var,
    color_var,
    color_palette,
    height,
    width,
    x_position,
    y_position,
    add_legend=True,
    static_bin_breaks=None,
    percentile_bin_breaks=None,
    filtering_var=None,
    z_position=6000,
    tab_order=-1001,
    parent_group_id=None,
    alt_text='A shape map',
    background_color=None,
    background_color_alpha=None,
)
```

Add a map to a page
![Example of a shape map created by the function](https://github.com/Russell-Shean/powerbpy/raw/main/docs/assets/images/page2.gif?raw=true "Example Shape Map")

#### Parameters {.doc-section .doc-section-parameters}

| Name                  | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Default    |
|-----------------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| visual_id             |        | Please choose a unique id to use to identify the map. PBI defaults to using a UUID, but it'd probably be easier if you choose your own id.                                                                                                                                                                                                                                                                                                                                                                                    | _required_ |
| data_source           |        | The name of the dataset you want to use to build the map. This corresponds to the dataset_name field in the add data functions. You must have already loaded the data to the dashboard.                                                                                                                                                                                                                                                                                                                                       | _required_ |
| shape_file_path       |        | A path to a shapefile that you want to use to build the map. This file can be any valid shapefile accepted by power BI. In this example dashboard I use a geojson, but presumably an Arcgis file with a .shp extension would also work. This shape file will be added to the dashboard's registered resources.                                                                                                                                                                                                                | _required_ |
| map_title             |        | The title you want to put above the map.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | _required_ |
| location_var          |        | The name of the column in data_source that you want to use for the location variable on the map.This should also correspond to the geography of your shape file.                                                                                                                                                                                                                                                                                                                                                              | _required_ |
| color_var             |        | The name of the column in data_source that you want to use for the color variable on the map. This variable should be numeric.                                                                                                                                                                                                                                                                                                                                                                                                | _required_ |
| filtering_var         |        | Optional. The name of a column in data source that you want to use to filter the color variable on the map. This must be supplied if providing percentile_bin_breaks. If you want to use percentiles without filtering (ie on static data), you should calculate the percentiles yourself and pass them to static_bin_breaks. Do not provide both static_bin_breaks and a filtering_var.                                                                                                                                      | `None`     |
| static_bin_breaks     |        | This should be a list of numbers that you want to use to create bins in your data. There should be one more entry in the list than the number of bins you want and therefore the number of colors passed to the color_palette argument. The function will create bins between the first and second number, second and third, third and fourth, etc. A filtering_var cannot be provided if static_bin_breaks is provided. Use percentile bin breaks instead.                                                                   | `None`     |
| color_palette         |        | A list of hex codes to use to color your data. There should be one fewer than the number of bins.                                                                                                                                                                                                                                                                                                                                                                                                                             | _required_ |
| add_legend            |        | True or False, would you like to add the default legend? (By default legend, I mean this function's default, not the Power BI default)                                                                                                                                                                                                                                                                                                                                                                                        | `True`     |
| percentile_bin_breaks |        | This should be a list of percentiles between 0 and 1 that you want to us to create bins in your data. If provided, a filtering_var must also be provided. This will create power BI measures that dynamically update when the data is filtered by things such as slicers. There should be one more entry in the list than the number of bins you want and therefore the number of colors passed to the color_palette argument. Here's an example use case: to create 5 equal sized bins pass this list: [0,0.2,0.4,0.6,0.8,1] | `None`     |
| height                |        | Height of map on the page                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | _required_ |
| width                 |        | Width of map on the page                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | _required_ |
| x_position            |        | The x coordinate of where you want to put the map on the page. Origin is page's top left corner.                                                                                                                                                                                                                                                                                                                                                                                                                              | _required_ |
| y_position            |        | The y coordinate of where you want to put the map on the page. Origin is page's top left corner.                                                                                                                                                                                                                                                                                                                                                                                                                              | _required_ |
| z_position            |        | The z index for the visual. (Larger number means more to the front, smaller number means more to the back). Defaults to 6000                                                                                                                                                                                                                                                                                                                                                                                                  | `6000`     |
| tab_order             |        | The order which the screen reader reads different elements on the page. Defaults to -1001 for now. (I need to do more to figure out what the numbers correpond to. It should also be possible to create a function to automatically order this left to right top to bottom by looping through all the visuals on a page and comparing their x and y positions)                                                                                                                                                                | `-1001`    |

#### Notes {.doc-section .doc-section-notes}

This function creates a new cloropleth map on a page.

### add_slicer { #powerbpy.page._Page.add_slicer }

```python
page._Page.add_slicer(
    data_source,
    column_name,
    visual_id,
    height,
    width,
    x_position,
    y_position,
    z_position=6000,
    tab_order=-1001,
    title=None,
    background_color=None,
    parent_group_id=None,
    alt_text='A slicer',
    background_color_alpha=None,
)
```

Add a slicer to a page

#### Parameters {.doc-section .doc-section-parameters}

| Name             | Type   | Description                                                                                                                                                                                                                                                                                                                                                    | Default    |
|------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| data_source      |        | This is the name of the dataset that you want to use to populate the slicer with                                                                                                                                                                                                                                                                               | _required_ |
| column_name      |        | This is the name of the measure (or variable) name you want to use to populate the slicer with                                                                                                                                                                                                                                                                 | _required_ |
| visual_id        |        | Please choose a unique id to use to identify the slicer. PBI defaults to using a UUID, but it'd probably be easier if you choose your own id.                                                                                                                                                                                                                  | _required_ |
| height           |        | Height of slicer on the page                                                                                                                                                                                                                                                                                                                                   | _required_ |
| width            |        | Width of slicer on the page                                                                                                                                                                                                                                                                                                                                    | _required_ |
| x_position       |        | The x coordinate of where you want to put the slicer on the page. Origin is page's top left corner.                                                                                                                                                                                                                                                            | _required_ |
| y_position       |        | The y coordinate of where you want to put the slicer on the page. Origin is page's top left corner.                                                                                                                                                                                                                                                            | _required_ |
| z_position       |        | The z index for the visual. (Larger number means more to the front, smaller number means more to the back). Defaults to 6000                                                                                                                                                                                                                                   | `6000`     |
| tab_order        |        | The order which the screen reader reads different elements on the page. Defaults to -1001 for now. (I need to do more to figure out what the numbers correpond to. It should also be possible to create a function to automatically order this left to right top to bottom by looping through all the visuals on a page and comparing their x and y positions) | `-1001`    |
| title            |        | An optional title to add to the slicer.                                                                                                                                                                                                                                                                                                                        | `None`     |
| background_color |        | Hex code for the background color of the slicer. Defaults to None (transparent)                                                                                                                                                                                                                                                                                | `None`     |
| parent_group_id  |        | This should be a valid id code for another power BI visual. If supplied the current visual will be nested inside the parent group.                                                                                                                                                                                                                             | `None`     |

#### Notes {.doc-section .doc-section-notes}

This function creates a new slicer on a page.

### add_table { #powerbpy.page._Page.add_table }

```python
page._Page.add_table(
    visual_id,
    data_source,
    variables,
    x_position,
    y_position,
    height,
    width,
    add_totals_row=False,
    table_title=None,
    table_title_font_size=None,
    column_widths=None,
    tab_order=-1001,
    z_position=6000,
    alt_text='A table',
    parent_group_id=None,
    background_color='#FFFFFF',
    background_color_alpha=None,
)
```

This function adds a new table to a page in a power BI dashboard report.

#### Parameters {.doc-section .doc-section-parameters}

| Name                  | Type   | Description                                                                                                                                                                                                                                                                                                                                                    | Default    |
|-----------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| visual_id             |        | Please choose a unique id to use to identify the table. PBI defaults to using a UUID, but it'd probably be easier if you choose your own id.                                                                                                                                                                                                                   | _required_ |
| data_source           |        | The name of the dataset you want to use to display in the table. This corresponds to the dataset_name field in the add data functions. You must have already loaded the data to the dashboard.                                                                                                                                                                 | _required_ |
| variables             |        | The variables from the table that you want to include                                                                                                                                                                                                                                                                                                          | _required_ |
| table_title           |        | Optional. Give your table an informative title!:D                                                                                                                                                                                                                                                                                                              | `None`     |
| table_title_font_size |        | Optional. The font size of the table's title. Should be a valid font size number.                                                                                                                                                                                                                                                                              | `None`     |
| column_widths         |        | Optional. Provide the width of columns. Provide the widths as a dictionary with column names as keys and widths as values.                                                                                                                                                                                                                                     | `None`     |
| x_position            |        | The x coordinate of where you want to put the table on the page. Origin is page's top left corner.                                                                                                                                                                                                                                                             | _required_ |
| y_position            |        | The y coordinate of where you want to put the table on the page. Origin is page's top left corner.                                                                                                                                                                                                                                                             | _required_ |
| height                |        | Height of table on the page                                                                                                                                                                                                                                                                                                                                    | _required_ |
| width                 |        | Width of table on the page                                                                                                                                                                                                                                                                                                                                     | _required_ |
| tab_order             |        | The order which the screen reader reads different elements on the page. Defaults to -1001 for now. (I need to do more to figure out what the numbers correpond to. It should also be possible to create a function to automatically order this left to right top to bottom by looping through all the visuals on a page and comparing their x and y positions) | `-1001`    |
| z_position            |        | The z index for the visual. (Larger number means more to the front, smaller number means more to the back). Defaults to 6000                                                                                                                                                                                                                                   | `6000`     |

### add_text_box { #powerbpy.page._Page.add_text_box }

```python
page._Page.add_text_box(
    text,
    visual_id,
    height,
    width,
    x_position,
    y_position,
    z_position=6000,
    tab_order=-1001,
    parent_group_id=None,
    alt_text='A text box',
    font_weight='bold',
    font_size=32,
    font_color='#000000',
    background_color=None,
    background_color_alpha=None,
)
```

Add a text box to a page

#### Parameters {.doc-section .doc-section-parameters}

| Name             | Type   | Description                                                                                                                                                                                                                                                                                                                                                    | Default     |
|------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
| text             |        | The text you want to display in the box                                                                                                                                                                                                                                                                                                                        | _required_  |
| visual_id        |        | Please choose a unique id to use to identify the text box. PBI defaults to using a UUID, but it'd probably be easier if you choose your own id.                                                                                                                                                                                                                | _required_  |
| height           |        | Height of text box on the page                                                                                                                                                                                                                                                                                                                                 | _required_  |
| width            |        | Width of text box on the page                                                                                                                                                                                                                                                                                                                                  | _required_  |
| x_position       |        | The x coordinate of where you want to put the text box on the page. Origin is page's top left corner.                                                                                                                                                                                                                                                          | _required_  |
| y_position       |        | The y coordinate of where you want to put the text box on the page. Origin is page's top left corner.                                                                                                                                                                                                                                                          | _required_  |
| z_position       |        | The z index for the visual. (Larger number means more to the front, smaller number means more to the back). Defaults to 6000                                                                                                                                                                                                                                   | `6000`      |
| tab_order        |        | The order which the screen reader reads different elements on the page. Defaults to -1001 for now. (I need to do more to figure out what the numbers correpond to. It should also be possible to create a function to automatically order this left to right top to bottom by looping through all the visuals on a page and comparing their x and y positions) | `-1001`     |
| font_weight      |        | This is an option to change the font's weight. Defaults to bold. Available options include: ["bold"]                                                                                                                                                                                                                                                           | `'bold'`    |
| font_size        |        | The font size in pts. Must be a whole integer. Defaults to 32 pt                                                                                                                                                                                                                                                                                               | `32`        |
| font_color       |        | Hex code for the font color you'd like to use. Defaults to black (#000000)                                                                                                                                                                                                                                                                                     | `'#000000'` |
| background_color |        | Hex code for the background color of the text box. Defaults to None (transparent)                                                                                                                                                                                                                                                                              | `None`      |
| parent_group_id  |        | This should be a valid id code for another power BI visual. If supplied the current visual will be nested inside the parent group.                                                                                                                                                                                                                             | `None`      |

#### Notes {.doc-section .doc-section-notes}

This function creates a new text box on a page.