Skip to content

Commit

Permalink
- Added doc for style parameter of Page classes
Browse files Browse the repository at this point in the history
- Added dynamic styling example
- Release Notes update
  • Loading branch information
FabienLelaquais committed Sep 23, 2024
1 parent 1d89d27 commit 7316e50
Show file tree
Hide file tree
Showing 13 changed files with 315 additions and 118 deletions.
4 changes: 2 additions & 2 deletions docs/refmans/gui/viselements/generic/progress.md_template
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ This is how the control now looks:
<figcaption>Linear progress indicator</figcaption>
</figure>

## Adding a title {data-source="gui:doc/examples/controls/progress-title.py"}
## Adding a title {data-source="gui:doc/examples/controls/progress-texts.py"}

The control can show the percentage as a numerical value by setting the
[*show_value*](#p-show_value) property to True.</br>
Expand All @@ -73,7 +73,7 @@ With the same variable as above, this is the control definition of a progress in
title above the gauge:
!!! taipy-element
value={value}
title=Loading...
title=Processing...
title_anchor=top
show_value:b=True

Expand Down
Binary file modified docs/refmans/gui/viselements/generic/table-rowstyle-d.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/refmans/gui/viselements/generic/table-rowstyle-l.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
211 changes: 106 additions & 105 deletions docs/refmans/gui/viselements/generic/table.md_template
Original file line number Diff line number Diff line change
Expand Up @@ -526,57 +526,6 @@ refresh was needed.
Make sure, when you are using the [*rebuild*](#p-rebuild) property, that no performance impact is
so bad that it would ruin the user experience.

# Styling

All the table controls are generated with the "taipy-table" CSS class. You can use this class
name to select the tables on your page and apply style.

## [Stylekit](../../../../userman/gui/styling/stylekit.md) support

The [Stylekit](../../../../userman/gui/styling/stylekit.md) provides a CSS custom property:

- *--table-stripe-opacity*<br/>
This property contains the opacity applied to odd lines of tables.<br/>
The default value is 0.5.

The [Stylekit](../../../../userman/gui/styling/stylekit.md) also provides specific CSS classes that you can use to style
tables:

- *header-plain*<br/>
Adds a plain and contrasting background color to the table header.
- *rows-bordered*<br/>
Adds a bottom border to each row.
- *rows-similar*<br/>
Removes the even-odd striped background so all rows have the same background.

## Dynamic styling

You can modify the style of entire rows or specific table cells based on any criteria, including
the table data itself.

When Taipy creates the rows and the cells, it can add a specific CSS class to the generated
elements. This class name is the string returned by the function set to the [*style*](#p-style)
property for entire rows, or [*style[column_name]*](#p-style[column_name]) for specific cells.

The signature of this function depends on which *style* property you use:

- [*style*](#p-style): this applies to entire rows.<br/>
The given function expects three optional parameters:
- *state*: the current state
- *index*: the index of the row in this table
- *row*: all the values for this row
- [*style[column_name]*](#p-style[column_name]): this applies to a specific cell.<br/>
The given function expects five optional parameters:
- *state*: the current state
- *value*: the value of the cell
- *index*: the index of the row in this table
- *row*: all the values for this row
- *column_name*: the name of the column for this cell

Based on these parameters, the function must return a string that defines a CSS class name that will
be added to the CSS classes for this table row or this specific cell.<br/>
The [example](#styling-rows) below shows how this works.

# Usage

## Show tabular data
Expand Down Expand Up @@ -746,6 +695,104 @@ The resulting display reflects what is requested:
<figcaption>Formatted columns</figcaption>
</figure>

## Aggregation

To get the aggregation functionality in your table, you must indicate which columns can be aggregated
and how to perform the aggregation.

This is done using the indexed [*group_by*](#p-group_by[column_name]) and
[*apply*](#p-apply[column_name]) properties.

The [*group_by[column_name]*](#p-group_by[column_name]) property, when set to True indicates that the
column *column_name* can be aggregated.

The function provided in the [*apply[column_name]*](#p-apply[column_name]) property indicates how to
perform this aggregation. The value of this property, which is a string, can be:

- A built-in function. Available predefined functions are the following: `count`, `sum`, `mean`, `median`,
`min`, `max`, `std`, `first` (the default value), and `last`.
- The name of a user-defined function or a lambda function.<br/>
This function receives a single parameter which is the series to aggregate, and it must return a scalar
value that would result from the aggregation.

This control definition is all it takes to add aggregation functionality to the table:
!!! taipy-element
default={data}
group_by[Group column]:b=True
apply[Apply column]=count

## Cell tooltips

You can specify a tooltip for specific table cells.

When Taipy creates the cells, it can add a specific tooltip that you would have set as the
return value of the function set to the [*tooltip*](#p-tooltip) or
[*tooltip[column_name]*](#p-tooltip[column_name]) properties.

The signature of this function expects five optional parameters:
- *state*: the current state.
- *value*: the value of the cell.
- *index*: the index of the row in this table.
- *row*: all the values for this row.
- *column_name*: the name of the column for this cell.

Based on these parameters, the function must return a string that defines a tooltip used as the
cell's tooltip text.
!!! taipy-element
default={data}
tooltip={lambda state, val, idx: "A tooltip" if idx % 2 == 0 else "Another tooltip"}

# Styling

All the table controls are generated with the "taipy-table" CSS class. You can use this class
name to select the tables on your page and apply style.

## [Stylekit](../../../../userman/gui/styling/stylekit.md) support

The [Stylekit](../../../../userman/gui/styling/stylekit.md) provides a CSS custom property:

- *--table-stripe-opacity*<br/>
This property contains the opacity applied to odd lines of tables.<br/>
The default value is 0.5.

The [Stylekit](../../../../userman/gui/styling/stylekit.md) also provides specific CSS classes that
you can use to style tables:

- *header-plain*<br/>
Adds a plain and contrasting background color to the table header.
- *rows-bordered*<br/>
Adds a bottom border to each row.
- *rows-similar*<br/>
Removes the even-odd striped background so all rows have the same background.

## Dynamic styling

You can modify the style of entire rows or specific table cells based on any criteria, including
the table data itself.

When Taipy creates the rows and the cells, it can add a specific CSS class to the generated
elements. This class name is the string returned by the function set to the [*style*](#p-style)
property for entire rows, or [*style[column_name]*](#p-style[column_name]) for specific cells.

The signature of this function depends on which *style* property you use:

- [*style*](#p-style): this applies to entire rows.<br/>
The given function expects three optional parameters:
- *state*: the current state
- *index*: the index of the row in this table
- *row*: all the values for this row
- [*style[column_name]*](#p-style[column_name]): this applies to a specific cell.<br/>
The given function expects five optional parameters:
- *state*: the current state
- *value*: the value of the cell
- *index*: the index of the row in this table
- *row*: all the values for this row
- *column_name*: the name of the column for this cell

Based on these parameters, the function must return a string that defines a CSS class name that will
be added to the CSS classes for this table row or this specific cell.<br/>
The [example](#styling-rows) below shows how this works.

## Styling rows

To give a specific style to a table row, you will use the [*style*](#p-style) property (note that
Expand All @@ -757,11 +804,11 @@ the name of a style, defined in CSS.
Here is how a row styling function can be defined:

```python
def even_odd_style(_1, index, _2):
if index % 2:
return "blue-cell"
def even_odd_style(_1, row, _2):
if row % 2:
return "blue-row"
else:
return "red-cell"
return "red-row"
```

We only use the second parameter since, in this straightforward case, we do not need the application
Expand All @@ -773,11 +820,11 @@ We need to define what these style names mean. This is done in a CSS stylesheet,
CSS content would appear:

```css
.blue-cell>td {
.blue-row>td {
color: white;
background-color: blue;
}
.red-cell>td {
.red-row>td {
color: yellow;
background-color: red;
}
Expand All @@ -793,8 +840,8 @@ To use this style, we can adjust the control definition used above so it looks l

The resulting display will be what we expected:
<figure class="tp-center">
<img src="../table-rowstyle-d.png" class="visible-dark" width="50%"/>
<img src="../table-rowstyle-l.png" class="visible-light" width="50%"/>
<img src="../table-rowstyle-d.png" class="visible-dark" width="75%"/>
<img src="../table-rowstyle-l.png" class="visible-light" width="75%"/>
<figcaption>Styling the rows</figcaption>
</figure>

Expand Down Expand Up @@ -856,49 +903,3 @@ As expected, the result is a table where the style of the columns changes depend
<figcaption>Styling the column</figcaption>
</figure>

## Aggregation

To get the aggregation functionality in your table, you must indicate which columns can be aggregated
and how to perform the aggregation.

This is done using the indexed [*group_by*](#p-group_by[column_name]) and
[*apply*](#p-apply[column_name]) properties.

The [*group_by[column_name]*](#p-group_by[column_name]) property, when set to True indicates that the
column *column_name* can be aggregated.

The function provided in the [*apply[column_name]*](#p-apply[column_name]) property indicates how to
perform this aggregation. The value of this property, which is a string, can be:

- A built-in function. Available predefined functions are the following: `count`, `sum`, `mean`, `median`,
`min`, `max`, `std`, `first` (the default value), and `last`.
- The name of a user-defined function or a lambda function.<br/>
This function receives a single parameter which is the series to aggregate, and it must return a scalar
value that would result from the aggregation.

This control definition is all it takes to add aggregation functionality to the table:
!!! taipy-element
default={data}
group_by[Group column]:b=True
apply[Apply column]=count

## Cell tooltips

You can specify a tooltip for specific table cells.

When Taipy creates the cells, it can add a specific tooltip that you would have set as the
return value of the function set to the [*tooltip*](#p-tooltip) or
[*tooltip[column_name]*](#p-tooltip[column_name]) properties.

The signature of this function expects five optional parameters:
- *state*: the current state.
- *value*: the value of the cell.
- *index*: the index of the row in this table.
- *row*: all the values for this row.
- *column_name*: the name of the column for this cell.

Based on these parameters, the function must return a string that defines a tooltip used as the
cell's tooltip text.
!!! taipy-element
default={data}
tooltip={lambda state, val, idx: "A tooltip" if idx % 2 == 0 else "Another tooltip"}
42 changes: 33 additions & 9 deletions docs/release-notes/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,10 @@ This is the list of changes to Taipy releases as they were published.
to represent significant numerical information such as an industrial KPI.
- A new control called [`chat`](../refmans/gui/viselements/generic/chat.md) was added
to simplify the creation of chatting applications.
- You can define CSS rules for a specific page using the new *style* parameter of the `Page^`
class or using the `Page.set_style()^` method.<br/>
See the [section on Styling](../userman/gui/styling/index.md#style-sheets) for more
information.

<h4><strong><code>taipy-core</code></strong> 4.0.0 </h4>

Expand All @@ -65,24 +69,38 @@ This is the list of changes to Taipy releases as they were published.

<h4><strong><code>taipy-gui</code></strong> 4.0.0</h4>

- Setting up styling: if a file called `taipy.css` sits next to the Python script (`<app>.py`) that
runs a Taipy GUI application, and if there is no file called `<app>.css` at the same location,
then this CSS file is loaded and applied to all pages. This feature allows you to share styles
across different Taipy GUI applications.<br/>
See the [Styling section](../userman/gui/styling/index.md#style-sheets) for more
information.<br/>
- Setting up styling:<br/>
If a file called `taipy.css` sits next to the Python script (`<app>.py`) that runs a Taipy GUI
application, and if there is no file called `<app>.css` at the same location, then this CSS file
is loaded and applied to all pages. This feature allows you to share styles across different Taipy
GUI applications.<br/>
See [issue #1597](https://github.com/Avaiga/taipy/issues/1597) for a description of this
functionality.
functionality and the [section on Styling](../userman/gui/styling/index.md#style-sheets) for more
information.
- Most visual elements now implement the *width* property to simplify page layout.<br/>
See [issue #1720](https://github.com/Avaiga/taipy/issues/1720).
- The [`pane`](../refmans/gui/viselements/generic/pane.md) block has a new property called
[*show_button*](../refmans/gui/viselements/generic/pane.md#p-show_button). If set to True,
a persistent *open* button renders on the page when the pane is closed so you don't need an
a persistent *open* button appears on the page when the pane is closed so you don't need an
external control to let users open the pane.
- In the [`chart`](../refmans/gui/viselements/generic/chart.md) control, the Modebar (that
appears when the cart is hovered on) no longer has the Plotly logo button by default.
You can bring it back by setting the chart's
[*plot_config* property](../refmans/gui/viselements/generic/chart.md#p-plot_config)
to a dictionary with a property called "displaylogo" set to True.<br/>
See [issue #1600](https://github.com/Avaiga/taipy/issues/1600).
- The [`input`](../refmans/gui/viselements/generic/input.md) control has a new *type* property that
allows the type of input data the user can enter (such as an email address or a URL) to be set.
- The [`login`](../refmans/gui/viselements/generic/login.md) control has a new toggle button
to show or hide the entered password.
- Controls defined with the Page Builder API have an additional property called *inline* which,
when set to True, will not generate a line skip, to facilitate layout.<br/>
See [issue #1725](https://github.com/Avaiga/taipy/issues/1725).
- Properties that expect a function can now be set to a lambda function in the Page Builder
API.<br/>
See [issue #1379](https://github.com/Avaiga/taipy/issues/1379).
- The *decimator* property of the [`chart`](../refmans/gui/viselements/generic/chart.md) control
now applies to traces that are only "lines" or "markers".

<h4><strong><code>taipy-core</code></strong> 4.0.0 </h4>

Expand Down Expand Up @@ -118,7 +136,13 @@ This is the list of changes to Taipy releases as they were published.

- The value of multiline [`input`](../refmans/gui/viselements/generic/pane.md) controls is
cleared when the ENTER key is pressed.<br/>
See [issue #1762](https://github.com/Avaiga/taipy/issues/1292).
See [issue #1762](https://github.com/Avaiga/taipy/issues/1762).
- The [`chart`](../refmans/gui/viselements/generic/chart.md) control properly handles its
*selected* property in the case it uses the *figure* property.<br/>
See [issue #1786](https://github.com/Avaiga/taipy/issues/1786).
- Indexed properties can be used in the Page Builder API as described in the information box in
[this](../userman/gui/pages/builder.md#setting-property-values) section.<br/>
See [issue #1715](https://github.com/Avaiga/taipy/issues/1715).

<h4><strong><code>taipy-core</code></strong> 4.0.0</h4>

Expand Down
4 changes: 4 additions & 0 deletions docs/userman/gui/pages/builder.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,10 @@ The impact of this change is reflected in the page:

Compared to the previous example, you can see that the label uses a bold font weight.

!!! note "Setting functions"
If a property expects a function, you can use a lambda function directly expressed as Python
code.

!!! warning "Indexed properties"
Some elements of Taipy GUI (such as [`chart`](../../../refmans/gui/viselements/generic/chart.md),
[`table`](../../../refmans/gui/viselements/generic/table.md), or
Expand Down
Binary file added docs/userman/gui/styling/dynamic1-d.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/userman/gui/styling/dynamic1-l.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/userman/gui/styling/dynamic2-d.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/userman/gui/styling/dynamic2-l.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/userman/gui/styling/dynamic3-d.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/userman/gui/styling/dynamic3-l.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit 7316e50

Please sign in to comment.