---
title: "twbparser-intro"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{twbparser-intro}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(twbparser)
ok <- FALSE
twb_path <- system.file("extdata", "test_for_wenjie.twb", package = "twbparser")
if (nzchar(twb_path) && file.exists(twb_path)) {
parser <- TwbParser$new(twb_path)
ok <- TRUE
} else {
cat("> Demo .twb not found in installed package. Skipping executable examples.\n")
}


```

# Introduction

`twbparser` parses Tableau `.twb` and `.twbx` workbooks and exposes datasources,
relationships, joins, fields, calculated fields, and TWBX assets. It also
provides page-centric insights — dashboards, worksheets, stories, their
composition, filter positions, chart types, and colors/palettes — as well as
per-worksheet shelf/filter/axis/sort details and per-dashboard zone layout and
actions. This vignette demonstrates common use cases.

# Parse a Tableau Workbook

```{r parse-twb, eval=exists("parser")}
parser$summary
parser$overview
```

# Extracting Datasources and Parameters

```{r datasources, eval=exists("parser")}
datasources <- parser$get_datasources()
parameters <- parser$get_parameters()

print(head(datasources))
print(head(parameters))
```

# Fields and calculated fields

Parameters are excluded by default from calculated fields; opt-in via `include_parameters = TRUE`.

```{r calculated_fields, eval=exists("parser")}
head(parser$get_fields())
head(parser$get_calculated_fields(pretty = TRUE, wrap = 120))

```

# Page insights

List all pages and summarize each page

```{r insights_1, eval=ok}
twb_pages(parser)
twb_pages_summary(parser)


```

Inspect what a specific page contains

```{r insight_2, eval=ok}


pg <- twb_pages(parser)
nm <- if (nrow(pg)) pg$name[[1]] else NA_character_
if (!is.na(nm)) {
  parser$get_page_composition(nm)
}


```

Filters and their positions across dashboards

```{r insights_3, eval=ok}
twb_dashboard_filters(parser)

```

Chart (mark) types per worksheet and colors/palettes

```{r insights_4, eval=ok}
twb_charts(parser)
twb_colors(parser)

```

# Worksheet intelligence

Each of the four functions below accepts an optional `sheet` argument to
restrict output to a single worksheet.

## Shelves — what fields are on rows, cols, and encodings?

```{r sheet-shelves, eval=ok}
shelves <- twb_sheet_shelves(parser)
head(shelves)
```

The `shelf` column distinguishes `"rows"`, `"cols"`, `"color"`, `"size"`,
`"label"`, `"detail"`, and `"tooltip"`.

## Filters

```{r sheet-filters, eval=ok}
filters <- twb_sheet_filters(parser)
head(filters)
```

Categorical filters include a comma-separated `members` column;
range filters populate `range_min` / `range_max`.

## Axis configuration

```{r sheet-axes, eval=ok}
axes <- twb_sheet_axes(parser)
head(axes)
```

## Sort directives

```{r sheet-sorts, eval=ok}
sorts <- twb_sheet_sorts(parser)
head(sorts)
```

# Dashboard intelligence

## Sheet positions

```{r dashboard-sheets, eval=ok}
db_sheets <- twb_dashboard_sheets(parser)
head(db_sheets)
```

`x`, `y`, `w`, `h` are pixel coordinates within the dashboard canvas.

## Zone layout tree

```{r dashboard-layout, eval=ok}
layout <- twb_dashboard_layout(parser)
head(layout)
```

`parent_zone_id` links child zones to their container; root zones have `NA`.
`component_type` is one of `"worksheet"`, `"filter"`, `"container"`,
`"legend"`, `"parameter_control"`, `"text"`, `"image"`, or `"blank"`.

## Actions

```{r dashboard-actions, eval=ok}
actions <- twb_dashboard_actions(parser)
head(actions)
```

`action_type` is `"filter"`, `"url"`, `"highlight"`, or `"parameter"`.
`source_sheets` is a comma-separated list; `url` is populated for URL actions.

# Relationships and Joins

```{r relationships-joins, eval=exists("parser")}
relations <- parser$get_relationships()

head(relations)
```

# Working with TWBX Files (if applicable)

```{r twbx, eval=exists("parser") && !is.null(parser$twbx_path)}
parser$get_twbx_manifest()
parser$get_twbx_extracts()
parser$get_twbx_images()

```

# Validation of Relationships

```{r validate, eval=exists("parser")}
v <- parser$validate()
if (isTRUE(v$ok)) {
cat("Relationships validated successfully.\n")
} else {
print(v$issues)
}

```

# Summary

This vignette overviewed how to use the `twbparser` package for detailed inspection and extraction of Tableau workbook internals to assist in analysis, replication, or integration workflows.