The JavaScript code

First things first: to use a custom JavaScript library we need to write… some JavaScript.

To do this we will create a new folder calledtabulator/ that has the following structure:

tabulator/  tabulator_esm.min.js  tabulator.min.css  tableComponent.js

Bothtabulator_esm.min.js andtabulator.min.css are downloaded fromtabulator’s website.tableComponent.js is the script that we will write that contains the code for rendering the table to our Shiny app.

To create an output binding in Shiny, we create a new instance of theShiny.OutputBinding class.

tableComponent.js

class TabulatorOutputBindingextends Shiny.OutputBinding {// Find element to render infind(scope) {... }// Render output element in the found elementrenderValue(el, payload) {... }}// Register the bindingShiny.outputBindings.register(newTabulatorOutputBinding(),"shiny-tabulator-output");

This class has two methods that we need to implement:find() andrenderValue(). Thefind() method is used to identify the element that will contain the rendered table. TherenderValue() method is used to render the table in the element. After making that class we need to register it with Shiny so it can find and send data to instances of our output.

tableComponent.js

class TabulatorOutputBindingextends Shiny.OutputBinding {find(scope) {return scope.find(".shiny-tabulator-output");    }renderValue(el, payload) {...}}Shiny.outputBindings.register(...);

tableComponent.js

// Import the Tabulator libraryimport { Tabulator }from"./tabulator_esm.min.js";class TabulatorOutputBindingextends Shiny.OutputBinding {find(scope) {... }renderValue(el, payload) {// Unpack the info we get from the associated render functionconst { columns, data, type_hints }= payload;// Convert the column names to a format that Tabulator expectsconst columnsDef= columns.map((col, i)=> {return {title: col,field: col,hozAlign: type_hints[i]==="numeric"?"right":"left",        };      });// Data comes in as a series of rows with each row having as many elements// as there are columns in the data. We need to map this to a series of// objects with keys corresponding to the column names.functionzipRowWithColumns(row) {const obj= {};        row.forEach((val, i)=> {          obj[columns[i]]= val;        });return obj;      }// Instantiate a new Tabulator table in the element.// This will also destroy any existing table in the element// so we don't have to worry about adding and removing tables.newTabulator(el, {data: data.map(zipRowWithColumns),layout:"fitColumns",columns: columnsDef,      });    }}Shiny.outputBindings.register(...);

tableComponent.js

if (Shiny) {class TabulatorOutputBindingextends Shiny.OutputBinding {... }    Shiny.outputBindings.register(...);}

Theoutput_tabulator() function

Next we need an HTML element to target with our JavaScript code. When we set upthe find method for our binding, we chose the classshiny-tabulator-output as the mark of a tabualtor output, so we need to add that class. We also need to allow the user to set the ID of the element so that Shiny knows which element to target with which output. By wrapping theid argument inresolve_id() we make sure it will work in the context of modules. We’ll also add a height argument so that the user can set the height of the table.

app.py

from shinyimport App, Inputs, uifrom shiny.moduleimport resolve_idfrom htmltoolsimport HTMLDependencytabulator_dep= HTMLDependency("tabulator","5.5.2",    source={"subdir":"tabulator"},    script={"src":"tableComponent.js","type":"module"},    stylesheet={"href":"tabulator.min.css"},    all_files=True,)def output_tabulator(id, height="200px"):return ui.div(        tabulator_dep,# Use resolve_id so that our component will work in a moduleid=resolve_id(id),        class_="shiny-tabulator-output",        style=f"height:{height}",    )

Now, theoutput_tabulator() function can be called anywhere we want to render a table in our app.

Therender_tabulator() decorator

Now we’ve got the client-side logic finished, we need to write a custom render decorator that sends our data into the component.

A render function’s job is to take the result of calling the decorated function, transform it into the format our client-side code wants (in many cases this may be as simple as just returning the object unchanged), and then returning that client-side friendly data which will be passed to our client’srenderValue() method.

To do this we can leverage some tools provided by Shiny in theshiny.render.renderer subpackage.

app.py

from shiny.render.rendererimport Jsonifiable, Rendererclass render_tabulator(Renderer[pd.DataFrame]):"""    Render a pandas dataframe as a tabulator table.    """def auto_output_ui(self):"""        Express UI for the tabulator renderer        """return ui.output_tabulator(self.output_name)asyncdef transform(self, value: pd.DataFrame)-> Jsonifiable:"""        Transform a pandas dataframe into a JSONifiable object that can be        passed to the tabulator HTML dependency.        """ifnotisinstance(value, pd.DataFrame):# Throw an error if the value is not a dataframeraiseTypeError(f"Expected a pandas.DataFrame, got{type(value)}. ")# Get data from dataframe as a list of lists where each inner list is a# row, column names as array of strings and types of each column as an# array of stringsreturn {"data": value.values.tolist(),"columns": value.columns.tolist(),"type_hints": value.dtypes.astype(str).tolist(),        }

An implementation ofRenderer produces a class which is intended to be used as a decorator, which is why arender_* naming convention is recommended. An implementation requires at least 3 things: (1)auto_output_ui, (2) either atransform orrender function, and (3) an value type for theRenderer class.

Here, the value type we’ve used ispd.DataFrame, which helps users know if they’ve returned a suitable object in their render function.

Theauto_output_ui() method is used to generate the UI for the output if the renderer were to be used in Express mode. In this case we just use theoutput_tabulator() function we wrote earlier.

Finally, renderers use either thetransform(self, value: IT) orrender(self) methods to retrieve and transform the result of an output value function into an object that can be sent to the client.render_tabulator’stransform method returns a dictionary of data (which is JSON-like, e.g. Jsonifiable) to be passed to the client side. Thetransform method is called when the output value function returns a non-None value. If the value isNone, therender method quits early, returningNone.

When first transforming an output value, we check to make sure that the value returned by the function is a dataframe. If it’s not, we throw an error. This is not required, but it’s good practice to do so.

...ifnotisinstance(value, pd.DataFrame):# Throw an error if the value is not a dataframeraiseTypeError(f"Expected a pandas.DataFrame, got{type(value)}. ")...

Finally, we return a dictionary of data that we want to pass to the client side. In this case we return the data as a list of lists, the column names as an array of strings, and the types of each column as an array of strings using methods provided by pandas.

...return {"data": value.values.tolist(),"columns": value.columns.tolist(),"type_hints": value.dtypes.astype(str).tolist(),}...

This returned value is then what gets sent to the client side and is available in thepayload argument of therenderValue() method of ourTabulatorOutputBinding class.