sprinkle_fixed_header {pixiedust}

Assign a Fixed Header to an HTML Table

Description

Long tables to be displayed on-screen may benefit by keeping the header fixed in position while scrolling through the body of the table. This allows the user to maintain visual contact between the column name and the data.

Usage

sprinkle_fixed_header(
  x,
  fixed_header = TRUE,
  include_fixed_header_css = TRUE,
  fixed_header_class_name = "pixie-fixed",
  scroll_body_height = 300,
  scroll_body_height_units = "px",
  scroll_body_background_color = "white",
  fixed_header_height = 20,
  fixed_header_height_units = "px",
  fixed_header_text_height = fixed_header_height/2,
  fixed_header_text_height_units = "px",
  fixed_header_background_color = "white",
  ...
)

## Default S3 method:
sprinkle_fixed_header(
  x,
  fixed_header = TRUE,
  include_fixed_header_css = TRUE,
  fixed_header_class_name = "pixie-fixed",
  scroll_body_height = 300,
  scroll_body_height_units = "px",
  scroll_body_background_color = "white",
  fixed_header_height = 20,
  fixed_header_height_units = "px",
  fixed_header_text_height = fixed_header_height/2,
  fixed_header_text_height_units = "px",
  fixed_header_background_color = "white",
  ...
)

## S3 method for class 'dust_list'
sprinkle_fixed_header(
  x,
  fixed_header = TRUE,
  include_fixed_header_css = TRUE,
  fixed_header_class_name = "pixie-fixed",
  scroll_body_height = 300,
  scroll_body_height_units = "px",
  scroll_body_background_color = "white",
  fixed_header_height = 20,
  fixed_header_height_units = "px",
  fixed_header_text_height = fixed_header_height/2,
  fixed_header_text_height_units = "px",
  fixed_header_background_color = "white",
  ...
)

Arguments

x

An object of class dust

fixed_header

logical(1). When TRUE, HTML output will produce a table with a fixed header and a scrollable body.

include_fixed_header_css

logical(1). When TRUE, the CSS code to produce the table is inserted directly ahead of the HTML code for the table. When FALSE, the CSS is omitted and assumed to be provided by the user. This may be beneficial if the user has defined CSS styles for their tables. In this case, the user will need to add CSS classes to their customized CSS to accomodate the fixed headers. See Avoiding CSS Conflicts.

fixed_header_class_name

character(1). When include_fixed_header_css = FALSE, this class name is used to reference CSS classes provided by the user to format the table correctly.

scroll_body_height

integerish(1). Sets the height of the scrollable table body.

scroll_body_height_units

character(1). Determines the units for the height of the scrollable table. Defaults to "px". Must be one of c("px", "pt", "%", "em").

scroll_body_background_color

character(1). The color of the background of the body. Must be a valid color. It defaults to white, which may override CSS settings provided by the user. If this needs to be avoided, you may use the fixed_header_css function to assist in generating CSS code to use to define the CSS. See Avoiding CSS Conflicts.

fixed_header_height

integerish(1). Sets the height of the header row.

fixed_header_height_units

character(1). Determines the units for the height of the header row. Defaults to "px". Must be one of c("px", "pt", "%", "em").

fixed_header_text_height

numeric(1). Sets the height at which the header text appears. By default it is set to half of the header height. This should be approximately centered, but you may alter this to get the precise look you want.

fixed_header_text_height_units

character(1). Determines the units for placing the header text. Defaults to "px". Must be one of c("px", "pt", "%", "em").

fixed_header_background_color

character(1). Sets the background color for the header row. This defaults to white and may override the user's CSS settings. See Avoiding CSS Conflicts.

...

Arguments to pass to other methods.

Details

CSS doesn't make this kind of table natural. The solution to generate the fixed headers used by pixiedust is probably not the best solution in terms of CSS design. It is, however, the most conducive to generating dynamically on the fly.

The fixed header table requires nesting several HTML elements.

1. a div tag is used to control the alignment of the table

2. a section tag is used to set up the header row that remains fixed.

3. a div that sets the height of the scrollable body

4. the table tag establishes the actual table.

5. The th tags inside the table are set to full transparency and the content of the headers is duplicated in a div within the th tag to display the content.

To accomplish these tasks, some CSS is exported with the table and placed in the document immediately before the table. Read further to understand the conflicts that may arise if you are using custom CSS specifications in your documents.

Avoiding CSS Conflicts

Because of all of the shenanigans involved, exporting the CSS with the tables may result in conflicts with your custom CSS. Most importantly, any CSS you have applied to the th or td tags may be overwritten. If you are using custom CSS, you may want to consider using include_fixed_header_css = FALSE and then utilizing fixed_header_css to generate CSS you can include in your CSS file to provide the fixed headers. The code generated by fixed_header_css ought to be placed before your definitions for td and th.

To get the same header design in the fixed table, you will want to modify the .th-pixie-fixed div definition in the CSS to match your desired th definition.

The code produced by fixed_header_css will include comments where there is potential for a CSS conflict.

Functional Requirements

1. Set the fixed_header element of the dust object correctly.

2. Set the include_fixed_header_css element of the dust object correctly.

3. Set the fixed_header_param element of the dust object correctly.

4. Cast an error if x does not inherit class dust

5. Cast an error if scroll_body_height is not integerish(1)

6. Cast an error if scroll_body_height_units is not character(1)

7. Cast an error if scroll_body_background_color is not character(1)

8. Cast an error if scroll_body_background_color is not a valid color.

9. Cast an error if fixed_header_height is not integerish(1)

10. Cast an error if fixed_header_height_units is not character(1)

11. Cast an error if fixed_header_text_height is not numeric(1)

12. Cast an error if fixed_header_text_height_units is not character(1)

13. Cast an error if fixed_header_background_color is not character(1)

14. Cast an error if fixed_header_background_color is not a valid color.

15. Cast an error if include_fixed_header_css is not logical(1)

16. Cast an error if fixed_header_class_name is not character(1)