Migrate Customization User Guide content

doc/how_to/components/add_remove.md

@@ -8,7 +8,7 @@ To start, we will declare a ``Column`` and populate it with some text and a widg
 
 ```{pyodide}
 import panel as pn
-pn.extension()
+pn.extension() # for notebook
 
 column = pn.Column('# some text', pn.widgets.FloatSlider())
 

doc/how_to/components/align.md

@@ -0,0 +1,27 @@
+# Align Components
+
+The `align` parameter controls how components align vertically and horizontally. It supports 'start', 'center', and 'end' values and can be set for both horizontal and vertical directions at once or for each separately by passing in a tuple of the form `(horizontal, vertical)`.
+
+One common use-case where alignment is important is when placing multiple items with different heights in a `Row`. Let's create a big button and align a slider to the center of the button using `align=center`:
+
+
+```{pyodide}
+import panel as pn
+pn.extension() # for notebook
+
+button = pn.widgets.Button(name='Test', height=100)
+slider = pn.widgets.IntSlider(align='center')
+
+pn.Row(button, slider, background='lightgrey')
+```
+
+Now, let's look at aligning components in a grid with an instance of passing in `(horizontal, vertical)`:
+
+```{pyodide}
+pn.GridBox(
+    pn.widgets.Button(name='Test', height=100),
+    pn.widgets.IntSlider(align='center'),
+    pn.widgets.TextInput(name='Test', height=100, width=100, align=('center')),
+    pn.widgets.TextInput(width=150, align=('start', 'end')),
+    ncols=2)
+```

doc/how_to/components/apply_css.md

@@ -0,0 +1,53 @@
+# Apply CSS
+
+CSS styles can be embedded in raw form or by referencing an external .css file. All that is needed is to provide a list to the ``pn.config.raw_css`` or ``pn.config.js_files`` config parameters, respectively. Then, the ``css_classes`` parameter can be used to apply this CSS styling to a Panel component.
+
+First, we define custom CSS classes:
+
+```{pyodide}
+import panel as pn
+
+css_border = '''
+.bk.panel-widget-box {
+  border-radius: 5px;
+  border: 1px black solid;
+}
+'''
+
+css_bg = '''
+.bk.panel-widget-background {
+  background: #00aa41;
+}
+'''
+```
+Next, we pass the custom CSS classes to the panel config using the `raw_css` parameter:
+
+```{pyodide}
+pn.config.raw_css = [css_border, css_bg]
+
+```
+
+If we are working in a notebook, we can now activate the panel extension after having set the config parameters. Alternatively, we could have added the CSS using `pn.extension(raw_css=[])` for raw CSS or `pn.extension(css_files=[])` for external CSS files.
+
+```{pyodide}
+
+pn.extension() # for notebook
+
+```
+
+Finally, we can apply our custom CSS class to components using the `css_classes` parameter:
+
+```{pyodide}
+pn.Column(
+    pn.widgets.FloatSlider(name='Number', margin=(10, 5, 5, 10)),
+    pn.widgets.Select(name='Fruit', options=['Apple', 'Orange', 'Pear'], margin=(0, 5, 5, 10)),
+    pn.widgets.Button(name='Run', margin=(5, 10, 10, 10)),
+css_classes=['panel-widget-box', 'panel-widget-background'])
+```
+
+:::{admonition} Attention
+:class: attention
+
+Custom CSS styling may not appear to function properly on this page due to incompatibility with the tooling specific to the documentation.
+
+:::

doc/how_to/components/change_background.md

@@ -0,0 +1,20 @@
+# Change Background
+
+Many components have a `background` argument that can take a color either as a hex string or color name. See the list of available color names for modern browsers in the [bokeh docs](https://docs.bokeh.org/en/latest/docs/reference/colors.html#bokeh-colors-groups).
+
+First, define a simple HTML pane, set the width and height, and then change the background color to '#f307eb'.
+
+```{pyodide}
+import panel as pn
+pn.extension() # for notebook
+
+block1 = pn.pane.HTML(width=100, height=100)
+block1.background='#f307eb'
+block1
+```
+
+Now, create another block with the color of 'mediumseagreen':
+
+```{pyodide}
+pn.pane.HTML(background='mediumseagreen', width=200, height=100)
+```

doc/how_to/components/construct_panes.md

@@ -6,7 +6,7 @@ To explicitly construct a pane, use one of the pane types listed in the [referen
 
 ```{pyodide}
 import panel as pn
-pn.extension()
+pn.extension() # for notebook
 
 pn.pane.Markdown('''
 # H1

doc/how_to/components/index.md

@@ -1,35 +1,100 @@
-# Components
+# Create Components
 
-Panel components are the building blocks and visual layouts of your app or dashboard. These How-to pages provide solutions for common component tasks.
+Panel components are the building blocks and visual layouts of your app or dashboard. These How-to pages provide solutions for common tasks related to creating and customizing components.
+
+## Initialize Components
 
 ::::{grid} 1 2 2 3
 :gutter: 1 1 1 2
 
-:::{grid-item-card} Construct Panes
+:::{grid-item-card} {octicon}`rocket;2.5em;sd-mr-1` Construct Panes
 :link: construct_panes
 :link-type: doc
 
 How to construct Pane objects for displaying visible components.
 :::
 
-:::{grid-item-card} Access Pane Type
+:::{grid-item-card} {octicon}`unverified;2.5em;sd-mr-1` Access Pane Type
 :link: pane_type
 :link-type: doc
 
 How to access Pane Type.
 :::
 
-:::{grid-item-card} Access and Set Widget Values
+:::{grid-item-card} {octicon}`telescope;2.5em;sd-mr-1` Access Widget Values
 :link: widget_values
 :link-type: doc
 
 How to access and set widget values.
 :::
 
-:::{grid-item-card} Add or Remove Components
+:::{grid-item-card} {octicon}`file-diff;2.5em;sd-mr-1` Add or Remove Components
 :link: add_remove
 :link-type: doc
 
 How to add or remove components from a panel.
 :::
 ::::
+
+## Style Components
+
+::::{grid} 1 2 2 3
+:gutter: 1 1 1 2
+
+:::{grid-item-card} {octicon}`gift;2.5em;sd-mr-1` Apply CSS
+:link: apply_css
+:link-type: doc
+
+How to apply custom CSS styling.
+:::
+
+:::{grid-item-card} {octicon}`star-fill;2.5em;sd-mr-1` Change Background
+:link: change_background
+:link-type: doc
+
+How to change the background color for most components.
+:::
+
+:::{grid-item-card} {octicon}`hourglass;2.5em;sd-mr-1` Customize Loading Icon
+:link: load_icon
+:link-type: doc
+
+How to customize the loading icon.
+:::
+
+:::{grid-item-card} {octicon}`eye;2.5em;sd-mr-1` Control Visibility
+:link: visibility
+:link-type: doc
+
+How to control the visibility of a component.
+:::
+
+::::
+
+## Arrange and Size Components
+
+::::{grid} 1 2 2 3
+:gutter: 1 1 1 2
+
+:::{grid-item-card} {octicon}`mirror;2.5em;sd-mr-1` Customize Spacing
+:link: spacing
+:link-type: doc
+
+How to customize the spacing between elements.
+:::
+
+:::{grid-item-card} {octicon}`project;2.5em;sd-mr-1` Align Components
+:link: align
+:link-type: doc
+
+How to customize the alignment between components.
+:::
+
+:::{grid-item-card} {octicon}`filter;2.5em;sd-mr-1` Control Size
+:link: size
+:link-type: doc
+
+How to control the size of components.
+:::
+
+::::

doc/how_to/components/load_icon.md

@@ -0,0 +1,40 @@
+# Customize Loading Icon
+
+All components also have a `loading` parameter which indicates that they are currently processing some event. Setting the parameter will display the global `loading_spinner` on top of the component.
+
+First, let's configure the style and color of loading spinner:
+
+* `pn.config.loading_spinner`: The style of the global loading indicator, e.g. 'arc', 'arcs', 'bar', 'dots', 'petal'.
+* `pn.config.loading_color`: The color of the global loading indicator as a hex color or color name, e.g. '#6a6a6a', 'black'.
+
+```{pyodide}
+
+import panel as pn
+
+pn.config.loading_spinner = 'petal'
+pn.config.loading_color = 'black'
+
+```
+
+If we are working in a notebook, we can now activate the panel extension after having set the config parameters. Alternatively, we could have set the config with `pn.extension(loading_spinner='petal', loading_color='black')`
+
+```{pyodide}
+
+pn.extension() # for notebook
+
+```
+
+Next, let's display a simple component and set `loading=True`:
+
+```{pyodide}
+
+pn.pane.HTML(background='#00aa41', width=100, height=100, loading=True)
+
+```
+
+:::{admonition} Attention
+:class: attention
+
+Setting the loading icon may not appear to function properly on this page due to incompatibility with the tooling specific to the documentation.
+
+:::

doc/how_to/components/pane_type.md

@@ -1,10 +1,10 @@
 # Access Pane Type
 
-To access the type for a given component, use the ``pprint`` method. This can come in handy when a component was created in such a way where the type was not explicitly specified, such as with ``pn.panel``, as described on the [How to construct panes page](construct_panes.md).
+To access the type for a given component, use the ``pprint`` method. This can come in handy when a component was created in such a way where the type was not explicitly specified, such as with ``pn.panel`` as described on the [How to construct panes page](construct_panes.md).
 
 ```{pyodide}
 import panel as pn
-pn.extension()
+pn.extension() # for notebook
 
 example_pane = pn.panel('https://upload.wikimedia.org/wikipedia/commons/b/b1/Loading_icon.gif', width=500)
 

doc/how_to/components/size.md

@@ -0,0 +1,75 @@
+# Control Size
+
+Components can use either one of the responsive sizing modes or absolute sizing.
+
+:::{admonition} Important
+:class: important
+
+Unlike other components, the size of a plot component is usually determined by the underlying plotting library, so it may be necessary to ensure that you set the size and aspect when declaring the plot.
+
+:::
+
+## Absolute Sizing
+
+To set a fixed size on a component, it is usually sufficient to set a `width` or `height`, but in certain cases setting ``sizing_mode='fixed'`` explicitly may also be required.
+
+Let's create a simple example that fixes the height or width of several components:
+
+```{pyodide}
+import panel as pn
+pn.extension() # for notebook
+
+pn.Row(
+    pn.pane.Markdown('ABCDE', background='#f0f0f0', width=75, height=100),
+    pn.widgets.FloatSlider(width=200, background='#f0f0f0'),
+    pn.pane.PNG('https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png', width=300, background='#f0f0f0'),
+)
+```
+
+Now let's use ``sizing_mode='fixed'`` to create a fixed-size component. This will retain the object's original width and height regardless of any subsequent browser window resize events. This is usually the default behavior and simply respects the provided width and height.
+
+```{pyodide}
+pn.pane.PNG('https://upload.wikimedia.org/wikipedia/commons/8/89/PNG-Gradient.png', sizing_mode='fixed')
+```
+
+## Responsive Sizing
+
+Most panel objects support reactive sizing which adjusts depending on the size of the visible area of a web page. Responsive sizing modes can be controlled using the ``sizing_mode`` parameter with the following options:
+
+* **"stretch_width"**: Component will responsively resize to stretch to the available width, without maintaining any aspect ratio. The height of the component depends on the type of the component and may be fixed or fit to component's contents. To demonstrate this behavior we create a Row with a fixed height and responsive width to fill:
+
+```{pyodide}
+pn.Row(
+    pn.pane.Str(background='#f0f0f0', height=100, sizing_mode='stretch_width'),
+    width_policy='max', height=200
+)
+```
+
+* **"stretch_height"**: Component will responsively resize to stretch to the available height, without maintaining any aspect ratio. The width of the component depends on the type of the component and may be fixed or fit to component's contents. To demonstrate the filling behavior in a document we declare a Column with a fixed height for the component to fill:
+
+```{pyodide}
+pn.Column(
+    pn.pane.Str(background='#f0f0f0', sizing_mode='stretch_height', width=200),
+    height=200
+)
+```
+
+* **"stretch_both"**: Component is completely responsive, independently in width and height, and will occupy all the available horizontal and vertical space, even if this changes the aspect ratio of the component. To demonstrate this behavior we will declare a Column with a fixed height and responsive width for the component to fill:
+
+```{pyodide}
+pn.Column(
+    pn.pane.Str(background='#f0f0f0', sizing_mode='stretch_both'),
+    height=200, width_policy='max'
+)
+```
+
+* **"scale_height"**: Component will responsively resize to stretch to the available height, while maintaining the original or provided aspect ratio.
+* **"scale_width"**: Component will responsively resize to stretch to the available width, while maintaining the original or provided aspect ratio.
+* **"scale_both"**: Component will responsively resize to both the available width and height, while maintaining the original or provided aspect ratio. For example:
+
+
+```{pyodide}
+pn.Column(
+    pn.pane.PNG('https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png', sizing_mode='scale_both'),
+    height=400, width=500, background='#f0f0f0')
+```