Tweak best practices

doc/how_to/best_practices/dev_experience.md

@@ -46,11 +46,13 @@ clicks = pn.bind(show_clicks, button.clicks) # not button.clicks!
 pn.Row(button, clicks)
 ```
 
-## Inherit from `pn.viewer.Viewer`
+## Inherit from `pn.viewer.Viewer` or `pn.custom.PyComponent`
 
 ### Good
 
-`param.Parameterized` is a very general class that can be used separately from Panel for working with Parameters. But if you want a Parameterized class to use with Panel, it is usually appropriate to inherit from the Panel-specific class `pn.viewable.Viewer` instead, because `Viewer` allows direct invocation of the class, resembling a native Panel object.
+`param.Parameterized` is a very general class that can be used separately from Panel for working with Parameters.
+
+But if you want a Parameterized class to use with Panel, it is usually appropriate to inherit from the Panel-specific class `pn.viewable.Viewer` instead, because `Viewer` allows direct instantiation of the `Viewer` class, resembling a native Panel object.
 
 For example, it's possible to use `ExampleApp().servable()` instead of `ExampleApp().view().servable()`.
 
@@ -68,6 +70,17 @@ class ExampleApp(pn.viewable.Viewer):
 ExampleApp().servable();
 ```
 
+`Viewer` is ideal if you're building a class with some fairly specific business logic, *but* if you are building a reusable component assembled from other Panel components use [`PyComponent`](https://panel.holoviz.org/reference/custom_components/PyComponent.html) instead.
+
+```python
+class MultipleChildren(PyComponent):
+
+ objects = Children()
+
+ def __panel__(self):
+ return pn.Column(objects=self.param['objects'], styles={"background": "silver"})
+```
+
 ### Okay
 
 Inheriting from `param.Parameterized` also works, but should be reserved for cases where there's no Panel output.

doc/how_to/best_practices/user_experience.md

@@ -150,6 +150,19 @@ pn.state.onload(onload)
 
 ### Good
 
+Set `loading=pn.state.param.busy` to overlay a spinner while processing to let the user know it's working.
+
+```{pyodide}
+def process_load(event):
+ time.sleep(3)
+
+button = pn.widgets.Button(name="Click me", on_click=process_load)
+widget_box = pn.WidgetBox(button, loading=pn.state.param.busy, height=300, width=300)
+widget_box
+```
+
+### Good
+
 Set `loading=True` to show a spinner while processing to let the user know it's working.
 
 ```{pyodide}
@@ -193,8 +206,6 @@ Use:
 - `finally` block to update values regardless
 
 ```{pyodide}
-import time
-
 def compute(divisor):
  try:
  busy.value = True