Best practices for manipulating appearances and element presentation

[vickorian]

So i've been working with AgGrid a lot recently and i'm noticing that there are a lot of conflicting posts describing how best to interact with the appearance of said element. Some say use tailwind css, some say to write custom css and pass it via resources, some say to modify the HTML directly via ui.add_head_html().

I'm not asking the developers/maintainers to do this as it would be too onerous a task and they are honestly some of the best devs i've seen about answering questions/concerns. I think as a community, with the facilitation of the maintainers, we start developing more complicated and commented examples of how to modify the appearance of specific elements in Nicegui.

Currently, lots of times we're re-directed by someone via, "Oh, go look at the implementation of x in y documentation and modify your code to fit that standard.", which might work if you have experience with those elements. But nicegui combines so many different elements and there is no guarantee that they will work, essentially making it random chance on if a particular element will work with a particular framework call.

This section originally contained an error as a result of a typo in the underlying test code resulting in the modifications not being output correctly.. I'm restating the section and adding an extra example.

.ag-row-hover .ag-cell {
    background-color: #AAAAAAAA;
}

.ag-theme-balham-dark .ag-row {
    --ag-row-hover-color: #AAAAAAAA;
}

where the color will also accept an rgb(xxx,xxx,xxx,xxx) in place of the hex.

These two will output the same results, where the second one can be directly found from the inspection of the elements.

Another example is something more hidden. When editing an AgGrid cell, the editor inherits the color of the theme. Attempting to pass the color via and other modifications of this line :

.ag-cell-inline-editing {
     color: white;
}

doesn't modify the color of the text in the editor. Thus, mixing the dark theme with custom row colors that need black text ends up with an edit cell that's difficult to see. Instead, when referencing the AgGrid documentation for the editor there is "agLargeTextCellEditor" and a parameter passed called "cellEditorParams" in "colDef". So passing the following:

'defaultColDef': {
        'cellEditor': "agLargeTextCellEditor",
        'cellEditorPopup': True,
        'cellEditorParams': {
            'useFormatter':True,
            'rows': 15,
            'cols': 50,
        },
}

generates an editor separate from the theme, a popout editor with a dark background and white text.

I'm proposing that we create a section on the github, the website, or/and in the examples directory of appearance modifications. At least in the hopes that we can start getting google search re-directs to those areas. I'm sure there are lots of people that aren't frontend developers that would appreciate these types of shows. Additional functionality is what i want the maintainers to keep doing, but at the same time, we might need to start trying to get people to help developing the corpus of information pertinent to nicegui as a visual front end.

edited for clarity and typo

[falkoschindler]

Thanks, @vickorian, for the warm words and the initiative!

We could, indeed, need some help when it comes documenting all these advanced use cases where you want to tweak the look and behavior of existing elements to your liking. These are often things we need to lookup ourselves, since it is far beyond of what we implemented intentionally. Of course, we shouldn't try to copy existing third-party documentation, but covering some general ideas and pointing into the right direction would be a valuable resource.

Regarding the AG Grid specifically, I could imagine extending the ui.aggrid documentation page with more demos and explanatory paragraphs specifically focussing on custom appearance. Later we can also move them onto a separate page.

[vickorian]

@falkoschindler

So something like the following is what i had in mind. If we can get people to start presenting their customizations with comments then eventually we can build up a comprehensive set of functionality. Surprisingly, copilot is pretty adept at finding some of these things, but it's going to take people testing and retesting the appearance changes and then commenting them to really show what everything does and how to manipulate it.

ui.add_head_html(
        """
<style>


/*These modifications will change the header of the AgGrid. They are specific to the theme
and so you'll need to  modify them for every theme. For example, if you aren't using the dark theme
then you'll need to create a separate block that starts with .ag-theme-balham instea of 
.ag-theme-balham-dark. Most of the variables are self explanatory but the border radius is responsible for
curving the ends of the bars to give a softer appearance*/


.ag-theme-balham-dark .ag-header {
    --ag-header-height: 30px;
    --ag-header-foreground-color: white;
    border-radius: 10px;
    --ag-header-cell-hover-background-color: rgb(100, 50, 168, .9);
    --ag-header-cell-moving-background-color: rgb(100, 50, 168,.9);
}



/*This section of the code changes the color of the cells when you are hovering over them. This is
distinct from the header and is only related to the rows where data is stored. You can use a few different
types of color here. Currently it's in hex, but you can also pass rgb(xxx,xxx,xxx,xxx) for red, green, blue, and alpha.
The hex code can be alpha sensitive with the XX values pertaining to the alpha channel:#AAAAAAXX
*/
.ag-theme-balham-dark .ag-row{
    --ag-row-hover-color: #5542AA66;
}


/* The paging panel is the bottom row of the AgGrid that is contains the pagination navigation. You can modify the
color, shape, etc in a similar way to the others (needs to be expanded to cover those functionalities) */


.ag-theme-balham-dark .ag-paging-panel {
    border-radius: 10px
}


/*You can control the color of odd and even rows individually instead of just changing the color of every row.
The next two sections show this. Again, the border radius allows us to round the edges of individual rows to make them
have a softer appearance. You can also individually control the text color of each row by passing the "color variable.*/
.ag-theme-balham-dark .ag-row-odd {
    background-color: rgb(238, 241, 238);
    border-radius: 10px;
}
.ag-theme-balham-dark .ag-row-even {
    background-color: white;
    border-radius: 10px;
}
</style>
"""
)

Doing this will also help clean up some of the documentation for you guys as well since you can point directly to where tailwind CSS works and where it's best to use style.

The following is a perfect example. Trying to pass tailwind CSS to adjust the height is fidgety where passing CSS directly from style makes the process significantly less painful and provides a bit more control of the appearance. But, in a lot of the documentation we see that the tailwind CSS is passed when controlling the height of an AgGrid.

grid = ui.aggrid({
    'columnDefs': c_defs,
    'rowData': row_data,
    'rowSelection': 'multiple', # Optional: Set row selection mode
    'pagination': True,
    'paginationPageSize':25,
    'enableFilter':True,
},auto_size_columns=True, theme='balham-dark').classes('w-full').style('height: 500px')

[falkoschindler]

Yes, such examples would be a great addition to the documentation. (That's what you meant, right?)
I would, however, split them up in smaller demos like "Styling the header", "Cell color when hovering", "Styling the pagination panel", and "Color odd and even rows", each with a short Markdown introduction and a corresponding code snippet showing off the CSS with a ui.aggrid element.

[aabrodskiy]

Just wanted to add for someone, who is looking for customizing the AGGrid in NiceGUI and found this page.
You generally don't need to specify sub-components of the theme (e.g. .ag-theme.balham .ag-row {}).

Most of the customization can just stay at the theme level, here are few examples from my theme customization.
Full list of AGGrid theme parameters lives here:

    ui.add_css('''
        .ag-theme-balham {
            --ag-background-color: var(--q--c28-surface) !important;
            --ag-foreground-color: var(--q-c23-h1-h2-h3-h4-text) !important;
            --ag-secondary-foreground-color: var(--q-c24-h5-p1-text) !important;
            --ag-data-color: var(--q-c23-h1-h2-h3-h4-text) !important;
            --ag-header-background-color: var(--q-c36-surface-variant) !important;
            --ag-header-foreground-color: var(--q-c23-h1-h2-h3-h4-text) !important;
            --ag-header-column-separator-color: var(--q-c30-separation-line) !important;
            --ag-odd-row-background-color: var(--q-c33-background) !important;
            --ag-selected-row-background-color: var(--q-c35-primary-container) !important;
            --ag-selected-row-foreground-color: var(--q-c23-h1-h2-h3-h4-text) !important;
            --ag-row-hover-color: var(--q-c37-surface-hover) !important;
            --ag-row-hover-background-color: var(--q-c35-primary-container) !important;
            --ag-balham-active-color: var(--q-c1-brand) !important;
        }
    ''')

And I define my custom branding colors globally with ui.colors at the top cascading theme function that I call as @asynccontextmanager as follows. Also define them for both themes - dark and light - and apply them dynamically when a user changes from dark to light or system.

async def apply_theme(theme):
    if theme == 'dark':
        ui.dark_mode().enable()
        is_dark = True
    elif theme == 'light':
        ui.dark_mode().disable()
        is_dark = False
    elif theme == 'system':
        ui.dark_mode(value=None)
        is_dark = await is_dark_mode()

    if is_dark:
        # dark theme
        background = '#1A243B'  
        brand = '#51B503'
        ui.colors(
            primary = brand,
            secondary = '#0B90D5',
            accent = '#111B1E',
            positive = '#53B689',
            negative = '#ea4335',
            info = '#31ccec',
            warning =	'#F2C037',
            dark =	'#29344B',
            dark_page =	background,
            background = background,
            c1_brand = '#51B503',
            c2_group = '#35AFEF',
            c3_kpis = '#00A4BA',
            c4_charts = '#7F60E0',
            c5_tables = '#6464E5',
            c6_high_high_high = '#BD2B11',
            c7_high_high = '#D95034',
            c8_high = '#E18C3F',
            c9_good = '#3E9641',
            c10_low = '#26A7B8',
            c11_low_low = '#266CA3',
            c12_low_low_low = '#4962CD',
            c13_not_applicable = '#B5277C',
            c14_out_of_range = '#B1941F',
            c15_not_in_service = '#A56043',
            c16_stale = '#A1A1A1',
            c17_actual = '#3757D7',
            c18_target = '#EAF1E0',
            c19_alert_count = '#967F5E',
            c20_fixed = '#1BA020',
            c21_in_progress = '#EA5436',
            c22_not_started = '#DC802D',
            c23_h1_h2_h3_h4_text = '#CDDBF6',
            c24_h5_p1_text = '#8CA0C9',
            c25_secondary_icon = '#8CA0C9',
            c26_tertiary_line_icon = '#A6B9AD',
            c27_secondary_filled_icon = '#8CA0C9',
            c28_surface = '#29344B',
            c29_group_stroke_line = '#8CA0C9',
            c30_separation_line = '#374768',
            c31_dotted_separation_line = '#4D5B79',
            c32_textfield_line = '#546077',
            c33_background = '#1A243B',
            c34_status_background = '#432F38',
            c35_primary_container = '#28343D',
            c36_surface_variant = '#546077',
            c37_surface_hover = '#404E69',
            c38_link = '#4182DF',
        )
    else:
        # light theme
        background = '#E4E9E6'
        brand =  '#51B503'
        ui.colors(
            primary = brand,
            secondary = '#0B90D5',
            accent = '#111B1E',
            positive = '#53B689',
            negative = '#ea4335',
            info = '#31ccec',
            warning =	'#F2C037',
            dark =	'#FFFFFF',
            dark_page =	background,  
            background = background,
            c1_brand = '#51B503',
            c2_group = '#0B90D5',
            c3_kpis = '#00A4BA',
            c4_charts = '#7F60E0',
            c5_tables = '#6464E5',
            c4_high_high_high = '#E93212',
            c7_high_high = '#FF5533',
            c8_high = '#FFA04B',    
            c9_good = '#57B65A',
            c10_low = '#2FC5D8',
            c11_low_low = '#3180BD',
            c12_low_low_low = '#506CE3',
            c13_not_applicable = '#3DD3DD',
            c14_out_of_range = '#B1941F',
            c15_not_in_service = '#3F3F3F',
            c16_stale = '#A1A1A1',
            c17_actual = '#3757D7',
            c18_target = '#1C1F18',
            c19_alert_count = '#967F5E',
            c20_fixed = '#1BA020',
            c21_in_progress = '#EA5436',
            c22_not_started = '#DC802D',
            c23_h1_h2_h3_h4_text = '#2E3C32',
            c24_h5_p1_text = '#53685A',
            c25_secondary_icon = '#354D3E',
            c26_tertiary_line_icon = '#A6B9AD',
            c27_secondary_filled_icon = '#758A7D',
            c28_surface = '#FFFFFF',
            c29_group_stroke_line = '#DBE5DF',
            c30_separation_line = '#E8F0EB',
            c31_dotted_separation_line = '#CADBD0',
            c32_textfield_line = '#CDD9D1',
            c33_background = background,
            c34_status_background = '#FDEBE7',
            c35_primary_container = '#F0F5EC',
            c36_surface_variant = '#F3F6F5',
            c37_surface_hover = '#F6F7F5',
            c38_link = '#4182DF',
        )

    ui.query('body').style(f'background-color: {background}') 

    return is_dark

async def is_dark_mode():
    is_dark = await ui.run_javascript('Quasar.Dark.isActive')
    logger.info(f"is_dark_mode: {is_dark}")
    return is_dark