diff --git a/astro.config.mjs b/astro.config.mjs index 956de25..9a7dab6 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -20,63 +20,4 @@ export default defineConfig({ }, integrations: [sitemap()], - redirects: { - '/tuts0101-getting-started': '/tutorial/tuts0101-getting-started', - '/tutorial/tuts0102-creating-a-module': '/tutorial/tuts0102-building-your-first-analysis', - '/tutorial/tuts0103-creating-an-analysis': '/tutorial/tuts0102-building-your-first-analysis', - '/tutorial/tuts0104-implementing-an-analysis': '/tutorial/tuts0103-implementing-an-analysis', - '/tutorial/tuts0105-debugging-an-analysis': '/tutorial/tuts0104-input-checks', - '/tutorial/tuts0204-debugging-an-analysis': '/tutorial/tuts0104-input-checks', - '/tutorial/tuts0107-distributing-modules': '/tutorial/tuts0110-distributing-modules', - '/tutorial/tuts0111-summary': '/tutorial/tuts0108-getting-started-summary', - '/tutorial/tuts0104-results-mental-model': '/tutorial/tuts0105-results-mental-model', - '/tutorial/tuts0105-creating-rich-results': '/tutorial/tuts0106-creating-rich-results', - '/tutorial/tuts0106-adding-plots': '/tutorial/tuts0107-adding-plots', - '/tutorial/tuts0107-getting-started-summary': '/tutorial/tuts0108-getting-started-summary', - '/tutorial/tuts0108-unit-testing': '/tutorial/tuts0109-unit-testing', - '/tutorial/tuts0109-distributing-modules': '/tutorial/tuts0110-distributing-modules', - '/tutorial/tuts0110-additional-notes': '/tutorial/tuts0111-additional-notes', - '/tutorial/tuts0108-additional-notes': '/tutorial/tuts0111-additional-notes', - '/tuts0201-dynamic-tables': '/tutorial/tuts0201-dynamic-tables', - '/tuts0201-data-binding': '/tutorial/tuts0201-dynamic-tables', - '/tuts0202-handling-data': '/tutorial/tuts0202-handling-data', - '/tuts0203-state': '/tutorial/tuts0203-state', - '/tutorial/tuts0204-advanced-plots': '/tutorial/tuts0301-image-state-performance', - '/tutorial/tuts0205-plot-themes': '/tutorial/tuts0302-plot-themes', - '/api_actions': '/api/actions', - '/api_analysis-definition': '/api/analysis-definition', - '/api_i18n': '/api/i18n', - '/api_image-sizing': '/tutorial/tuts0303-responsive-image-sizing', - '/api/image-sizing': '/tutorial/tuts0303-responsive-image-sizing', - '/api_module-definition': '/api/module-definition', - '/api_notices': '/api/notices', - '/api_results-definition': '/api/results-definition', - '/api_results-elements': '/api/results-elements', - '/api_table': '/api/table', - '/api_ui-definition': '/api/ui-definition', - '/ui-basecontrol': '/ui/basecontrol', - '/ui-basic-design': '/ui/basic-design', - '/ui-advanced-design': '/ui/advanced-design', - '/ui-advanced-customisation': '/ui/advanced-customisation', - '/ui-checkbox': '/ui/checkbox', - '/ui-collapsebox': '/ui/collapsebox', - '/ui-combobox': '/ui/combobox', - '/ui-custom-format': '/ui/custom-format', - '/ui-label': '/ui/label', - '/ui-layoutbox': '/ui/layoutbox', - '/ui-listbox': '/ui/listbox', - '/ui-optioncontrol': '/ui/optioncontrol', - '/ui-parentcontrol': '/ui/parentcontrol', - '/ui-radiobutton': '/ui/radiobutton', - '/ui-standard-formats': '/ui/standard-formats', - '/ui-supplier': '/ui/supplier', - '/ui-targetlayoutbox': '/ui/targetlayoutbox', - '/ui-termlabel': '/ui/termlabel', - '/ui-textbox': '/ui/textbox', - '/ui-variablelabel': '/ui/variablelabel', - '/ui-variablesupplier': '/ui/variablesupplier', - '/api_updates': '/misc/updates', - '/misc-library': '/tutorial/tuts0110-distributing-modules', - '/info_project-structure': '/misc/project-structure', - }, }); diff --git a/src/content/docs/learn/tutorial/tuts0101-getting-started.md b/src/content/docs/learn/tutorial/tuts0101-getting-started.md index 827b332..cb2f2f3 100644 --- a/src/content/docs/learn/tutorial/tuts0101-getting-started.md +++ b/src/content/docs/learn/tutorial/tuts0101-getting-started.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: "Getting Started" +type: article description: "Learn how to set up your environment and install your first jamovi module using jmvtools." --- diff --git a/src/content/docs/learn/tutorial/tuts0102-building-your-first-analysis.md b/src/content/docs/learn/tutorial/tuts0102-building-your-first-analysis.md index bc1c4f9..9a86259 100644 --- a/src/content/docs/learn/tutorial/tuts0102-building-your-first-analysis.md +++ b/src/content/docs/learn/tutorial/tuts0102-building-your-first-analysis.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: "Building Your First Analysis" +type: article description: "Scaffold a jamovi module and define your first statistical analysis UI using YAML." --- diff --git a/src/content/docs/learn/tutorial/tuts0103-implementing-an-analysis.md b/src/content/docs/learn/tutorial/tuts0103-implementing-an-analysis.md index e30cdd0..960d85d 100644 --- a/src/content/docs/learn/tutorial/tuts0103-implementing-an-analysis.md +++ b/src/content/docs/learn/tutorial/tuts0103-implementing-an-analysis.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: "Implementing an Analysis" +type: article description: "Write the R logic for your jamovi analysis using R6 classes and the jmvcore package." --- diff --git a/src/content/docs/learn/tutorial/tuts0104-input-checks.md b/src/content/docs/learn/tutorial/tuts0104-input-checks.md index d143bda..8bd4494 100644 --- a/src/content/docs/learn/tutorial/tuts0104-input-checks.md +++ b/src/content/docs/learn/tutorial/tuts0104-input-checks.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: "Input Checks" +type: article description: "Learn how to prevent errors when users haven't finished setting up their analysis using guard clauses." --- diff --git a/src/content/docs/learn/tutorial/tuts0105-results-mental-model.md b/src/content/docs/learn/tutorial/tuts0105-results-mental-model.md index fba2d87..43c4ffd 100644 --- a/src/content/docs/learn/tutorial/tuts0105-results-mental-model.md +++ b/src/content/docs/learn/tutorial/tuts0105-results-mental-model.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: "The jamovi Results Model" +type: article description: "Understand the hierarchical relationship between your R code and the jamovi results panel." --- diff --git a/src/content/docs/learn/tutorial/tuts0106-creating-rich-results.md b/src/content/docs/learn/tutorial/tuts0106-creating-rich-results.md index 361fba3..50ad218 100644 --- a/src/content/docs/learn/tutorial/tuts0106-creating-rich-results.md +++ b/src/content/docs/learn/tutorial/tuts0106-creating-rich-results.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: "Creating Rich Results" +type: article description: "Learn how to define and populate APA-formatted tables in your jamovi analysis results." --- diff --git a/src/content/docs/learn/tutorial/tuts0107-adding-plots.md b/src/content/docs/learn/tutorial/tuts0107-adding-plots.md index b834f08..51a6220 100644 --- a/src/content/docs/learn/tutorial/tuts0107-adding-plots.md +++ b/src/content/docs/learn/tutorial/tuts0107-adding-plots.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: "Adding Plots" +type: article description: "Learn how to integrate ggplot2 into your jamovi analysis using the State/Render model." --- diff --git a/src/content/docs/learn/tutorial/tuts0108-getting-started-summary.md b/src/content/docs/learn/tutorial/tuts0108-getting-started-summary.md index 6dfb99d..380c210 100644 --- a/src/content/docs/learn/tutorial/tuts0108-getting-started-summary.md +++ b/src/content/docs/learn/tutorial/tuts0108-getting-started-summary.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: "Summary & Next Steps" +type: article description: "Review what you've learned in the Getting Started series and discover your next steps for building jamovi modules." --- diff --git a/src/content/docs/learn/tutorial/tuts0109-unit-testing.md b/src/content/docs/learn/tutorial/tuts0109-unit-testing.md index 3880d03..1845087 100644 --- a/src/content/docs/learn/tutorial/tuts0109-unit-testing.md +++ b/src/content/docs/learn/tutorial/tuts0109-unit-testing.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: "Unit Testing your Analysis" +type: article description: "Ensure your jamovi analysis is robust and accurate by writing automated tests using testthat." --- diff --git a/src/content/docs/learn/tutorial/tuts0110-distributing-modules.md b/src/content/docs/learn/tutorial/tuts0110-distributing-modules.md index b8c2b2f..a070598 100644 --- a/src/content/docs/learn/tutorial/tuts0110-distributing-modules.md +++ b/src/content/docs/learn/tutorial/tuts0110-distributing-modules.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: "Distributing Modules" +type: article description: "Share your jamovi module with others by side-loading .jmo files or submitting to the jamovi library." --- diff --git a/src/content/docs/learn/tutorial/tuts0111-additional-notes.md b/src/content/docs/learn/tutorial/tuts0111-additional-notes.md index 33c126c..f64640e 100644 --- a/src/content/docs/learn/tutorial/tuts0111-additional-notes.md +++ b/src/content/docs/learn/tutorial/tuts0111-additional-notes.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: "Additional Notes" +type: article description: "Advanced tips on dependency management, performance optimization, and R namespace best practices." --- diff --git a/src/content/docs/learn/tutorial/tuts0200-analysis-lifecycle.md b/src/content/docs/learn/tutorial/tuts0200-analysis-lifecycle.md index 6937136..a9a7d92 100644 --- a/src/content/docs/learn/tutorial/tuts0200-analysis-lifecycle.md +++ b/src/content/docs/learn/tutorial/tuts0200-analysis-lifecycle.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: "The Analysis Lifecycle" +type: article description: "Master the two-stage execution model of jamovi: .init() and .run()." --- diff --git a/src/content/docs/learn/tutorial/tuts0201-dynamic-tables.md b/src/content/docs/learn/tutorial/tuts0201-dynamic-tables.md index e269e49..4d66817 100644 --- a/src/content/docs/learn/tutorial/tuts0201-dynamic-tables.md +++ b/src/content/docs/learn/tutorial/tuts0201-dynamic-tables.md @@ -1,9 +1,11 @@ --- layout: ../layouts/BaseLayout.astro title: "Dynamic Tables" +type: article +description: "Learn how to create jamovi tables with a dynamic number of rows using data-binding to user options." --- -In the previous tutorial series, we looked at [constructing and populating tables](/tutorial/tuts0105-creating-rich-results). The .r.yaml file contained: +In the previous tutorial series, we looked at [constructing and populating tables](/tutorial/tuts0106-creating-rich-results). The .r.yaml file contained: ```yaml ... diff --git a/src/content/docs/learn/tutorial/tuts0201a-advanced-table-techniques.md b/src/content/docs/learn/tutorial/tuts0201a-advanced-table-techniques.md index 4cb731c..e4d5bf8 100644 --- a/src/content/docs/learn/tutorial/tuts0201a-advanced-table-techniques.md +++ b/src/content/docs/learn/tutorial/tuts0201a-advanced-table-techniques.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: "Advanced Table Techniques" +type: article description: "Master complex results using the Three Levels of Table Initialization, Grouped Results, and Table Folding." --- diff --git a/src/content/docs/learn/tutorial/tuts0202-handling-data.md b/src/content/docs/learn/tutorial/tuts0202-handling-data.md index f2cc88d..785e989 100644 --- a/src/content/docs/learn/tutorial/tuts0202-handling-data.md +++ b/src/content/docs/learn/tutorial/tuts0202-handling-data.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: Handling Data +type: article description: "Master the Dual Nature of jamovi variables and learn how to correctly convert data for your R analyses." --- diff --git a/src/content/docs/learn/tutorial/tuts0203-state.md b/src/content/docs/learn/tutorial/tuts0203-state.md index 1911398..63a463d 100644 --- a/src/content/docs/learn/tutorial/tuts0203-state.md +++ b/src/content/docs/learn/tutorial/tuts0203-state.md @@ -1,6 +1,8 @@ --- layout: ../layouts/BaseLayout.astro title: State +type: article +description: "Learn how to use state and the clearWith property in jamovi to improve performance by avoiding redundant calculations." --- The analyses demonstrated in the tutorial series so far, have been completely *state*-less. This means that each time an analysis is run, (for example, in response to a user checking a checkbox) it runs the analysis from beginning to end. In many cases, this isn't very efficient. A user may run a t-test, and then select a checkbox requesting descriptives. Without *state*, an analysis will recalculate the t-test results every time the analysis is changed, even when the changed option has no impact on the t-test results. diff --git a/src/content/docs/learn/tutorial/tuts0204-translation.md b/src/content/docs/learn/tutorial/tuts0204-translation.md new file mode 100644 index 0000000..eb53d69 --- /dev/null +++ b/src/content/docs/learn/tutorial/tuts0204-translation.md @@ -0,0 +1,99 @@ +--- +layout: ../layouts/BaseLayout.astro +title: Module Translation +description: Learn how to enable multi-language support in your jamovi module. +type: article +--- + +jamovi supports the translation of modules. Although R does provide a rudimentary translation system, it's unfortunately limited in several significant ways. Perhaps the most significant limitation is that an R process cannot change the language it is using 'on the fly'. As a result, jamovi has had to provide its own translation system. + +## Enabling translations + +By default, all strings in the `.a.yaml`, `.r.yaml`, and `.u.yaml` are available to be translated, and don't require any special treatment by module developers. As such, the main task for module developers in enabling translation in modules is to ensure strings used in `.R` source files can be translated accordingly. The most common strings that need to be translated typically error messages and warnings. + +Strings are marked as translateable using the `.()` function from `jmvcore`. In order to use this without the `jmvcore::` prefix (i.e. allowing the more terse `.('Too few samples')`, rather than having to write `jmvcore::.('Too few samples')`), it's necessary to include the relevant import in the modules `NAMESPACE` file as follows: + +```r +importFrom(jmvcore,.) +``` + +This done, it's simply a matter of wrapping strings that need to be translated in calls to `.()`. Wrapping strings with `.()` performs two roles: +1. It indicates to the `jamovi-compiler` or `jmvtools` that the surrounded string needs translating. This allows the compiler (or jmvtools) to extract the string and place it in a 'database' of strings to translate. +2. It performs the translation at runtime. The `.()` function looks up a database of translated strings at runtime, and if it finds one suitable for the present language, it will return that to the calling function. + +### Recommendations + +Translatable strings should not have trailing or leading spaces. Translators might not understand why they are there and may accidentally trim them off, leading to formatting issues in the UI. + +**Avoid:** +```r +resids <- format(.('{}Residuals'), ifelse(std, .('Standardized '), '')) +``` + +**Recommended:** +```r +if (std) { + resids <- .('Standardized Residuals') +} else { + resids <- .('Residuals') +} +``` + +## Limitations: Accessing `self` + +The `.()` function requires access to the analysis object (i.e. the `self` in `self$results$...`). In order to access the current analysis, the `.()` function looks for a variable named `self` in the calling function's environment. + +For the most part, this happens transparently. If you call `.()` inside a member function of the analysis R6 class (like `.run()`), `self` is defined and it works perfectly. + +### Auxiliary Functions + +The exception is where the analysis calls auxiliary functions which are **not** members of the analysis R6 class. In these cases, you must pass `self` into the function explicitly. + +**BAD (Will Fail):** +```r +makeSSString <- function(sstype) { + if (sstype == 1) { + # Error: .() cannot find 'self' + return(.('Type 1 Sum of Squares is not suitable for this data set')) + } + NULL +} + +# R6 Class +.run=function() { + message <- makeSSString(sstype) +} +``` + +**GOOD:** +```r +makeSSString <- function(sstype, self) { + if (sstype == 1) { + # Success: 'self' is passed in explicitly + return(.('Type 1 Sum of Squares is not suitable for this data set')) + } + NULL +} + +# R6 Class +.run=function() { + message <- makeSSString(sstype, self) +} +``` + +## Creating Translation Files + +You can manage the translation catalogs using `jmvtools` from the R console: + +```r +# Create the base catalog (POT file) +jmvtools::i18nCreate('catalog') + +# Create a specific language file (e.g., 'de' for German) +jmvtools::i18nCreate('de') + +# Update existing files after adding new strings to your code +jmvtools::i18nUpdate() +``` + +The jamovi library is also able to take care of much of this process for you. Feel free to reach out to the jamovi team to participate in the community translation efforts. diff --git a/src/content/docs/learn/tutorial/tuts0301-image-state-performance.md b/src/content/docs/learn/tutorial/tuts0301-image-state-performance.md index fc4e490..27f3abb 100644 --- a/src/content/docs/learn/tutorial/tuts0301-image-state-performance.md +++ b/src/content/docs/learn/tutorial/tuts0301-image-state-performance.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: "Image State Performance" +type: article description: "Optimize your jamovi module by avoiding the \"State\" anti-pattern and using data-driven rendering correctly." --- diff --git a/src/content/docs/learn/tutorial/tuts0302-plot-themes.md b/src/content/docs/learn/tutorial/tuts0302-plot-themes.md index f9e9a5b..a393833 100644 --- a/src/content/docs/learn/tutorial/tuts0302-plot-themes.md +++ b/src/content/docs/learn/tutorial/tuts0302-plot-themes.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: "Plot Themes" +type: article description: "Learn how jamovi automatically applies themes to your plots for a native look and feel." --- diff --git a/src/content/docs/learn/tutorial/tuts0303-responsive-image-sizing.md b/src/content/docs/learn/tutorial/tuts0303-responsive-image-sizing.md index 79784c1..8046415 100644 --- a/src/content/docs/learn/tutorial/tuts0303-responsive-image-sizing.md +++ b/src/content/docs/learn/tutorial/tuts0303-responsive-image-sizing.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: Responsive Image Sizing +type: article description: Master the "Fixed vs. Stretchable" mental model to create plots that scale beautifully in jamovi. --- @@ -95,4 +96,4 @@ if ( ! is.null(image[["setSize2"]])) { - [ ] **Is my math dynamic?** Base your `heightM` or `widthM` on the number of variables or groups selected. - [ ] **Did I account for both axes?** Remember that both width and height usually have fixed components. -**Next Step:** Once your analysis is visual and responsive, it's time to ensure it is robust with **[Unit Testing](/tutorial/tuts0108-unit-testing)**. +**Next Step:** Once your analysis is visual and responsive, it's time to ensure it is robust with **[Unit Testing](/tutorial/tuts0109-unit-testing)**. diff --git a/src/content/docs/learn/ui/advanced-customisation.md b/src/content/docs/learn/ui/advanced-customisation.md index 8b817f2..ceca5d9 100644 --- a/src/content/docs/learn/ui/advanced-customisation.md +++ b/src/content/docs/learn/ui/advanced-customisation.md @@ -1,6 +1,8 @@ --- layout: ../layouts/BaseLayout.astro title: "Advanced customisation of the options UI" +type: article +description: "Learn how to use JavaScript to create dynamic and complex user interfaces for jamovi analyses, including custom event handlers and DOM manipulation." output: html_document --- diff --git a/src/content/docs/learn/ui/advanced-design.md b/src/content/docs/learn/ui/advanced-design.md index 77bce2c..1f45f6d 100644 --- a/src/content/docs/learn/ui/advanced-design.md +++ b/src/content/docs/learn/ui/advanced-design.md @@ -1,6 +1,8 @@ --- layout: ../layouts/BaseLayout.astro title: "Advanced UI Design" +type: article +description: "Explore advanced UI design in jamovi, including detailed mappings between option types and their corresponding UI controls." output: html_document --- diff --git a/src/content/docs/learn/ui/basic-design.md b/src/content/docs/learn/ui/basic-design.md index 7bfaacf..8884856 100644 --- a/src/content/docs/learn/ui/basic-design.md +++ b/src/content/docs/learn/ui/basic-design.md @@ -1,10 +1,12 @@ --- layout: ../layouts/BaseLayout.astro title: "UI Design" +type: article +description: "Learn the fundamentals of designing user interfaces for jamovi analyses, including compiler modes, best practices, and layout controls." output: html_document --- -UIs for jamovi analyses are defined in the .u.yaml file (A refresher on the files and the relationship between them is described [here](/tutorial/tuts0103-creating-an-analysis)). This describes what sort of control each option is represented by (i.e. a dropdown list, or some radio buttons), and the order and the layout in which they will appear. +UIs for jamovi analyses are defined in the .u.yaml file (A refresher on the files and the relationship between them is described [here](/tutorial/tuts0102-building-your-first-analysis)). This describes what sort of control each option is represented by (i.e. a dropdown list, or some radio buttons), and the order and the layout in which they will appear. ### `aggressive` vs `tame` compiler mode diff --git a/src/content/docs/reference/api/actions.md b/src/content/docs/reference/api/actions.md deleted file mode 100644 index d8f9b02..0000000 --- a/src/content/docs/reference/api/actions.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -layout: ../layouts/BaseLayout.astro -title: Actions ---- - -Actions allow an analysis to open a new data set in a new jamovi window (or tab in the browser). The following requires jamovi 2.7.12 or newer. - -Action are defined in the .a.yaml file as follows: - -```yaml - - name: open - title: Open - type: Action - action: open -``` - -Presently, the only action supported is of type `open` (visible as `action: open` in the .a.yaml snippet above). - -This in turn places a button in the analysis UI, with the text taken from `title`. If the user clicks the action button, the analysis is run, and the value of the option will be set to TRUE. i.e. - -```r - if (self$options$open) { - # if we're here, the user clicked the open button - } -``` - -In order to *perform* an action -- in this case open a file -- we perform the following steps. - -```r - if (self$options$open) { - - # 1. retrieve the option - option <- self$options$option('open') - - # 2. (optional) check that this version of jamovi supports actions - if (is.null(option$perform)) - return() # not support! - - # 3. call $perform() on the option, passing a callback - option$perform(function(action) { - - # 4. do stuff - - # 5a. if producing a data frame, return a result as follows - list( - data = ToothGrowth, - title = 'the fish was delish') - - # 5b. if writing to a file, return a result as follows - - # write the file to action$params$fullPath - write.csv(ToothGrowth, file=action$params$fullPath, row.names=FALSE) - - # return a result object using action$params$path (not $fullPath) - list( - path = action$params$path, - title = 'the fish was delish', - ext = 'csv' - ) - - # 5c. throw an error - - stop("Conditions are not satisfied") - }) - - } -``` diff --git a/src/content/docs/reference/api/analysis-definition.md b/src/content/docs/reference/api/analysis-definition.md index 753ca94..496f2af 100644 --- a/src/content/docs/reference/api/analysis-definition.md +++ b/src/content/docs/reference/api/analysis-definition.md @@ -1,13 +1,15 @@ --- layout: ../layouts/BaseLayout.astro title: "Analysis Definition" +description: "Comprehensive guide to the jamovi analysis definition (.a.yaml), covering metadata, menu placement, and options." +type: article --- -.a.yaml files +The analysis definition is a YAML file in the `jamovi/` directory with the extension `.a.yaml`. It describes the analysis metadata, how it appears in the jamovi menus, and the options (parameters) it requires. ## Header -the analysis definition is a yaml file in the `jamovi/` directory, with the extension `.a.yaml`. the analysis definition describes the analysis, the way it appears in menus, and the options it requires. the file is named to match the name of the analysis it describes, but converted to lowercase. an example is `ttestis.a.yaml`: +The header section of the `.a.yaml` file defines the analysis identity and its placement in the UI. The file must be named to match the name of the analysis, but converted to lowercase (e.g., `ttestis.a.yaml`). ```yaml --- @@ -38,137 +40,25 @@ options | an array of options that the analysis requires. these are describ ## Options -options represent the options that an analysis requires in order to run. when a jamovi module is used as an R package, they represent the arguments to the function. when used in jamovi itself, they represent the user interface (UI) options presented to the user. +Options represent the parameters that an analysis requires in order to run. When a jamovi module is used as an R package, they represent the arguments to the function. When used in jamovi itself, they represent the user interface (UI) options presented to the user. -each option has a name, a type, and some additional properties which are described in greater detail below. +Each option has a `name`, a `type`, and some additional properties. When a value is specified by the user, the option checks the value and produces an error if the value is not suitable. -when a value is specified by the user (either through the jamovi user interface, or through a function argument), the option checks the value and produces an error if the value is not suitable. the checks performed by each option are also detailed below. +### Option Types -the different option types are as follows: +The following option types are available in jamovi: -### Data +| Type | Description | +| :--- | :--- | +| [**Data**](/api/option-data) | The primary dataset for the analysis. | +| [**Bool**](/api/option-bool) | A true/false toggle (UI: Checkbox). | +| [**Integer**](/api/option-integer) | A whole number input. | +| [**Number**](/api/option-number) | A decimal number input. | +| [**List**](/api/option-list) | A selection from a predefined set of values. | +| [**Variable**](/api/option-variable) | A single variable selection from the dataset. | +| [**Variables**](/api/option-variables) | Multiple variable selections from the dataset. | +| [**Terms**](/api/option-terms) | Model terms, including main effects and interactions. | +| [**Group**](/api/option-group) | A container for organizing other options. | +| [**Action**](/api/option-action) | A button that triggers a specific task. | -`Data` is used for analyses which require data (almost all of them). if used, it should be the first of the options, and should always be called `data`. it has no additional properties. - -#### example - -```yaml - - name: data - type: Data -``` - -### Bool - -`Bool` is used for true/false values, and is typically represented in the UI as a checkbox. - -#### properties - - - title - - default: `false` - -#### example -```yaml - - name: bf - type: Bool - title: Bayes factor - default: false -``` -#### checks - - - the value must be `true` or `false` - -### Integer - -`Integer` is used for values which need to be whole numbers. For 'floating point' numbers, use `Number` instead. - -#### properties - - - title - - default: `0` - - min: `-Inf` - - max: `Inf` - -#### checks - - - the value must be a whole number - - the value must fall between the `min` and the `max` - -### Number - -`Number` is used for values which need to be numeric. For whole numbers, use `Integer` instead. - -#### properties - - - title - - default: `0.0` - - min: `-Inf` - - max: `Inf` - -#### example -```yaml - - name: ciWidth - type: Number - title: Confidence level - min: 50 - max: 99.9 - default: 95 -``` -#### checks - - - the value must be a number - - the value must fall between the `min` and the `max` - -### List - -`List` is used where only one of several values may be specified, and only one at a time. In the UI, these are typically represented as either a listbox, or a set of radio buttons. - -#### properties - - - title - - options - - default: `` - -`options` must be specified as an array of strings - -#### checks - - - the value must be one of the options - -### Variable - -`Variable` is used where a variable/column from the data set needs to be specified. In the UI, these are typically represented as a 'drop box', where variables can be dragged and dropped. - - - title - - suggested: `[]` - - permitted: `[continuous, ordinal, nominal, nominaltext]` - - rejectInf: `true` - - rejectMissing: `false` - -The value of `Variable` is a string (in R, a character vector of length 1) containing the assigned variable name. If nothing is assigned it has a value of `null`. - -#### checks - - - whether the value is a string - - whether the variable exists in the data set - - whether the variable type is permitted - - whether the variable contains non-finite values (if `rejectInf` is true) - - whether the variable contains missing values (if `rejectMissing` is true) - -### Variables - -`Variables` is used where multiple variables/columns from the data set need to be specified. In the UI, these are typically represented as a 'drop box', where variables can be dragged and dropped. - - - title - - suggested: `[]` - - permitted: `[continuous, ordinal, nominal, nominaltext]` - - rejectInf: `true` - - rejectMissing: `false` - -The value is an array of strings (in R, a character vector). If nothing is assigned to `Variables` it's value is an empty array (in R, a character vector of length 0). - -#### checks - - - whether the variable exists in the data set - - whether the variable type is permitted - - whether the variable contains non-finite values (if `rejectInf` is true) - - whether the variable contains missing values (if `rejectMissing` is true) +For a detailed look at how to interact with these options in your R code, see the [Options API (R)](/api/options-api) documentation. diff --git a/src/content/docs/reference/api/array.md b/src/content/docs/reference/api/array.md new file mode 100644 index 0000000..e6c674c --- /dev/null +++ b/src/content/docs/reference/api/array.md @@ -0,0 +1,125 @@ +--- +layout: ../layouts/BaseLayout.astro +title: Array +description: "Detailed reference for the jamovi Array results element, used for repeating output elements like tables or plots." +type: article +--- + +The `Array` element is a dynamic container used for repeating elements. It is particularly useful when you need to generate a set of results (like a table or a plot) for each level of a factor or for each variable in a list. + +The values of properties can be accessed using the `$` operator. For example, to retrieve the title of an array, one can go: + +```r +array$title +``` + +The methods of an array object are called using the `$` operator as well. For example: + +```r +array$setVisible(FALSE) +``` + +## Properties + +### name + +a string specifying the name of the array. + +### title + +a string specifying the title of the array. + +### visible + +`TRUE` or `FALSE`, whether the array is visible or not. + +### status + +a string, one of `'complete'`, `'error'`, `'inited'`, `'running'`. + +### state + +the state object associated with the array. + +## Methods + +### setStatus(status) + +sets the array's status, should be one of `'complete'`, `'error'`, `'inited'`, `'running'`. + +### setVisible(visible=TRUE) + +overrides the array's default visibility. + +### setTitle(title) + +sets the array's title. + +### setError(message) + +sets the array's status to 'error', and assigns the error message. + +### setState(object) + +sets the state object on the array. + +### addItem(key) + +adds a new item to the array. The `key` should be a unique identifier for this item. This method returns the newly created element (the template defined in `.r.yaml`). + +### get(key) + +retrieves an item from the array by its `key`. + +## Examples + +### 1. Define the Array in YAML + +In your `.r.yaml` file, you define an `Array` and provide an `items` template. This template defines what each element in the array will look like (e.g., a `Table`). + +```yaml +- name: modelResults + title: Model Results + type: Array + items: + type: Table + title: Results for Variable + columns: + - name: var + title: Variable + type: text + - name: value + title: Value + type: number +``` + +### 2. Implementation in R + +In the `.run()` function of your `.b.R` file, you can dynamically add items to the array using unique **keys**. Keys are typically strings (like variable names or factor levels) that uniquely identify each element in the array. + +```r +.run = function() { + array <- self$results$modelResults + + # Suppose we want a table for each dependent variable + deps <- self$options$deps + + for (dep in deps) { + # Create a new instance of the template for this variable + # The 'key' can be any string that uniquely identifies this item + table <- array$addItem(key = dep) + + # You can now interact with the new table object + table$setTitle(paste("Results for", dep)) + + # Add a row to the new table + table$setRow(rowNo=1, values=list( + var=dep, + value=mean(self$data[[dep]], na.rm=TRUE) + )) + } +} +``` + +> [!TIP] +> Arrays are the standard way in jamovi to handle "Split By" functionality or any situation where the number of output elements depends on the data or user options. diff --git a/src/content/docs/reference/api/group.md b/src/content/docs/reference/api/group.md new file mode 100644 index 0000000..6475906 --- /dev/null +++ b/src/content/docs/reference/api/group.md @@ -0,0 +1,70 @@ +--- +layout: ../layouts/BaseLayout.astro +title: Group +description: "Learn how to use the Group results element to organize and hierarchicalize your jamovi analysis output." +type: article +--- + +The `Group` element is a container used to organize other results elements (like tables, images, or other groups) into a logical hierarchy. + +## Methods + +### setStatus(status) + +sets the group's status, should be one of `'complete'`, `'error'`, `'inited'`, `'running'`. + +### setVisible(visible=TRUE) + +overrides the group's default visibility. + +### setTitle(title) + +sets the group's title. + +### setError(message) + +sets the group's status to 'error', and assigns the error message. + +### setState(object) + +sets the state object on the group. + +### get(name) + +retrieves a child element by its name. + +## Examples + +### 1. Define the Group in YAML + +A `Group` is defined in the `.r.yaml` file and can contain other results elements in its `items` property. + +```yaml +- name: descriptives + title: Descriptives + type: Group + items: + - name: statsTable + type: Table + title: Statistics +``` + +### 2. Access the Group in R + +In the `.run()` function, you can access the group and its children: + +```r +.run = function() { + # Access a group named 'descriptives' + group <- self$results$descriptives + + # Access a table inside that group + table <- group$get('statsTable') + + # Alternatively, using the $ operator (shorthand) + table <- group$statsTable + + # Set the group title dynamically + group$setTitle(paste("Descriptives for", self$options$variable)) +} +``` diff --git a/src/content/docs/reference/api/html.md b/src/content/docs/reference/api/html.md new file mode 100644 index 0000000..803ab7d --- /dev/null +++ b/src/content/docs/reference/api/html.md @@ -0,0 +1,73 @@ +--- +layout: ../layouts/BaseLayout.astro +title: Html +description: "Reference for the Html results element, allowing for rich, custom HTML output in jamovi analyses." +type: article +--- + +The `Html` element is used for displaying rich HTML output. This allows for custom formatting, links, and other HTML features that are not available in standard jamovi tables or text elements. + +> [!WARNING] +> While `Html` elements provide great flexibility, they should be used sparingly to maintain a consistent look and feel across jamovi analyses. For standard statistical results, `Table` and `Image` elements are preferred. + +## Methods + +### setStatus(status) + +sets the element's status, should be one of `'complete'`, `'error'`, `'inited'`, `'running'`. + +### setVisible(visible=TRUE) + +overrides the element's default visibility. + +### setTitle(title) + +sets the element's title. + +### setError(message) + +sets the element's status to 'error', and assigns the error message. + +### setState(object) + +sets the state object on the element. + +### setContent(content) + +sets the HTML content of the element. `content` should be a string containing valid HTML. + +## Examples + +### 1. Define the Html element in YAML + +An `Html` element is defined in the `.r.yaml` file: + +```yaml +- name: summaryHtml + title: Analysis Summary + type: Html +``` + +### 2. Set Content in R + +In the `.run()` function, you can generate HTML content and display it: + +```r +.run = function() { + # Access an HTML element named 'summaryHtml' + html <- self$results$summaryHtml + + # Create some HTML content + content <- " +

Analysis Summary

+

The results indicate a significant effect.

+ + " + + # Set the content + html$setContent(content) +} +``` diff --git a/src/content/docs/reference/api/i18n.md b/src/content/docs/reference/api/i18n.md deleted file mode 100644 index f07a09a..0000000 --- a/src/content/docs/reference/api/i18n.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -layout: ../layouts/BaseLayout.astro -title: Translation of Modules ---- - -jamovi supports the translation of modules. Although R does provide a rudimentary translation system, it's unfortunately limited in several significant ways. Perhaps the most significant limitation is that an R process cannot change the language it is using 'on the fly'. As a result, jamovi has had to provide its own translation system. - -## Enabling translations - -By default, all strings in the .a.yaml, .r.yaml, and .u.yaml are available to be translated, and don't require any special treatment by module developers. As such, the main task for module developers in enabling translation in modules is to ensure strings used in .R source files can be translated accordingly. The most common strings that need to be translated typically error messages and warnings. - -Strings are marked as translateable using the `.()` function from jmvcore. In order to use this without the `jmvcore::` prefix (i.e. allowing the more terse `.('Too few samples')`, rather than having to write `jmvcore::.('Too few samples')`), it's necessary to include the relevant import in the modules NAMESPACE file as follows: - -```r -importFrom(jmvcore,.) -``` - -This done, it's simply a matter of wrapping strings that need to be translated in calls to `.()`. Wrapping strings with `.()` performs two roles, the first is to indicate to the `jamovi-compiler` or `jmvtools` that the surrounded string needs translating. This allows the compiler (or jmvtools) to extract the string and place it in a 'database' of strings to translate. The second role of the `.()` function is to perform the translation at runtime. The `.()` function looks up a database of translated strings at runtime, and if it finds one suitable for the present language, it will return that to the calling function. - -### Recommendations - -1. Translatable strings should not have trailing or leading spaces. - -(Translators might not understand why, and trim them off). - -```r -resids <- format(.('{}Residuals), ifelse(std, .('Standardized '), '')) -``` - -Good: - -```r -if (std) { - resids <- .('Standardized Residuals') -} else { - resids <- .('Residuals') -} -``` - -### Limitations - -The `.()` function requires access to the analysis object (i.e. the `self` in `self$results$...`). In order to access the current analysis the `.()` function, when called, looks for the variable `self` in the calling function. i.e. - -```r -# R6 Class -.run=function() { - if (self$options$doStuff) { - message <- .('The fish was delish') - } -} -``` - -In this case, the `.()` goes looking for a variable called `self` in the `.run()` function. As `.run()` is a member of the Analysis R6 class, there's a `self` object defined and it will make use of it. - -For the most part, this simply happens transparently and module developers don't have to worry about it. The exception is where the analysis calls auxiliary functions which are not members of the analysis R6 class. i.e. a utility function as follows: - -```r -# BAD - -makeSSString <- function(sstype) { - if (sstype == 1) { - return .('Type 1 Sum of Squares is not suitable for this data set') - } - NULL -} - -# R6 Class -.run=function() { - message <- makeSSString(sstype) -} -``` - -In this case, `makeSSString()` has no `self` defined, and the call to `.()` will fail. The solution is to pass `self` into `makeSSString()` as follows: - -```r -# GOOD - -makeSSString <- function(sstype, self) { - if (sstype == 1) { - return .('Type 1 Sum of Squares is not suitable for this data set') - } - NULL -} - -# R6 Class -.run=function() { - message <- makeSSString(sstype, self) -} -``` - -### Creating catalog.pot and .po files - -catalog.pot and language .po files can be created with: - -```r -jmvtools::i18nCreate('catalog') # catalog.pot -jmvtools::i18nCreate('de') # de for german -``` - -and updated with: - -```r -jmvtools::i18nUpdate() -``` - -Having said that, the jamovi library is actually able to take care of this side of things for you. Reach out to us to participate. diff --git a/src/content/docs/reference/api/image.md b/src/content/docs/reference/api/image.md new file mode 100644 index 0000000..befc51e --- /dev/null +++ b/src/content/docs/reference/api/image.md @@ -0,0 +1,134 @@ +--- +layout: ../layouts/BaseLayout.astro +title: Image +description: "Technical reference for the jamovi Image results element, used for plots, charts, and graphical output." +type: article +--- + +The `Image` element is used for displaying graphical output, such as plots and charts, within jamovi results. + +The values of properties can be accessed using the `$` operator. For example, to retrieve the title of an image, one can go: + +```r +image$title +``` + +The methods of an image object are called using the `$` operator as well. For example: + +```r +image$setVisible(FALSE) +``` + +## Properties + +### name + +a string specifying the name of the image. + +### title + +a string specifying the title of the image. + +### visible + +`TRUE` or `FALSE`, whether the image is visible or not. + +### status + +a string, one of `'complete'`, `'error'`, `'inited'`, `'running'`. + +### state + +the state object associated with the image. + +### width + +an integer specifying the width of the image in pixels. + +### height + +an integer specifying the height of the image in pixels. + +### renderFun + +a string specifying the name of the private method in the analysis class used for rendering the image. + +### requiresData + +`TRUE` or `FALSE`, whether the image requires data to be rendered. If `TRUE`, the image will only be rendered if data is available. + +## Methods + +### setStatus(status) + +sets the image's status, should be one of `'complete'`, `'error'`, `'inited'`, `'running'`. + +### setVisible(visible=TRUE) + +overrides the image's default visibility. + +### setTitle(title) + +sets the image's title. + +### setError(message) + +sets the image's status to 'error', and assigns the error message. + +### setState(object) + +sets the state object on the image. + +### setSize(width, height) + +sets the width and height of the image. + +## Examples + +### 1. Define the Image in YAML + +First, you must define the image in your `.r.yaml` file and specify the `renderFun`. + +```yaml +- name: plot + title: My Awesome Plot + type: Image + width: 400 + height: 300 + renderFun: .plot +``` + +### 2. Implementation in R + +In jamovi, images are typically rendered by defining a **private method** in your analysis class. In R6, private methods are functions defined in the `private` list of your class and their names usually start with a dot (e.g., `.plot`). + +#### Prepare the Image +Inside the `.run()` function of your `.b.R` file, you can prepare the image. While you can access `self$data` directly in the rendering function, it is recommended to use `setState()` to store the specific data or objects needed for the plot. This allows jamovi to cache the image and avoid re-rendering it unnecessarily. + +```r +.run = function() { + image <- self$results$plot + + # Store data in state for caching and rendering + image$setState(self$data) +} +``` + +#### The Rendering Function +The rendering function is where the actual plotting happens. It must return `TRUE` if successful. + +```r +.plot = function(image, ...) { + if (is.null(image$state)) + return(FALSE) + + plot_data <- image$state + p <- ggplot(plot_data, aes(x=x, y=y)) + geom_point() + print(p) + + TRUE +} +``` + +> [!IMPORTANT] +> The `renderFun` must be a private method and it must **print** the plot object (e.g., using `print(p)`) to the active device. diff --git a/src/content/docs/reference/api/notice.md b/src/content/docs/reference/api/notice.md new file mode 100644 index 0000000..3b70bfc --- /dev/null +++ b/src/content/docs/reference/api/notice.md @@ -0,0 +1,58 @@ +--- +layout: ../layouts/BaseLayout.astro +title: Notice +description: "Documentation for the Notice results element, used for informational messages, warnings, and errors in jamovi." +type: article +--- + +The `Notice` element is used to display informational messages, warnings, or errors to the user within the jamovi results panel. They are particularly useful for alerting users to issues with their data, violations of assumptions, or providing additional context about the analysis. + +![Jamovi screenshot](@assets/reference/api/notices-example-1.png) + +![Jamovi screenshot](@assets/reference/api/notices-example-2.png) + +## Notice Types + +The `jmvcore::NoticeType` object provides the following constants for setting the notice type: + +- `jmvcore::NoticeType$INFO`: Blue background, informational icon. +- `jmvcore::NoticeType$WARNING`: Yellow background, warning icon. +- `jmvcore::NoticeType$STRONG_WARNING`: Orange background, strong warning icon. +- `jmvcore::NoticeType$ERROR`: Red background, error icon. + +## Examples + +### 1. Define the Notice in YAML + +A `Notice` can be defined in the `.r.yaml` file as part of the results structure. + +```yaml +results: + - name: dataNote + type: Notice +``` + +### 2. Implementation in R + +#### Static Definition +Setting the content of a notice defined in the YAML: + +```r +self$results$dataNote$setContent("Note: 5 cases were excluded due to missing values.") +self$results$dataNote$setType(jmvcore::NoticeType$INFO) +``` + +#### Dynamic Creation +Notices can also be created dynamically in R and inserted into the results tree. + +```r +if (violation) { + notice <- jmvcore::Notice$new( + options=self$options, + name='violationNotice', + type=jmvcore::NoticeType$STRONG_WARNING + ) + notice$setContent("Assumption of normality was violated.") + self$results$insert(1, notice) +} +``` diff --git a/src/content/docs/reference/api/notices.md b/src/content/docs/reference/api/notices.md deleted file mode 100644 index 7d2962a..0000000 --- a/src/content/docs/reference/api/notices.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -layout: ../layouts/BaseLayout.astro -title: "Notices" ---- - -Analyses can provide the user with notices that are displayed within the results. - -See the following examples: - -![Jamovi screenshot](@assets/reference/api/notices-example-1.png) - -![Jamovi screenshot](@assets/reference/api/notices-example-2.png) - - -Notices can be constructed as per: - -```r -notice <- jmvcore::Notice$new( - options=self$options, # self$options from the parent analysis - name='whateverYouLike', # results objects in jamovi must have a unique name - type=jmvcore::NoticeType$STRONG_WARNING # more options are possible, see below -) - -notice$setContent('The fish was delish') # set the content -self$results$insert(1, notice) # insert the notice at the top of the results -``` - -Valid values for the type of notice are: - -```r -NoticeType$ERROR -NoticeType$STRONG_WARNING -NoticeType$WARNING -NoticeType$INFO -``` - -We suggest you avoid using HTML in the content of your notices. - diff --git a/src/content/docs/reference/api/option-action.md b/src/content/docs/reference/api/option-action.md new file mode 100644 index 0000000..d05dff3 --- /dev/null +++ b/src/content/docs/reference/api/option-action.md @@ -0,0 +1,55 @@ +--- +layout: ../layouts/BaseLayout.astro +title: Action Option +description: "Documentation for the Action option, allowing analyses to trigger UI events like opening new datasets." +type: article +--- + +Actions allow an analysis to trigger specific events, such as opening a new data set in a new jamovi window. This functionality requires jamovi 2.7.12 or newer. + +## Definition + +Actions are defined in the `.a.yaml` file: + +```yaml + - name: open + title: Open + type: Action + action: open +``` + +Presently, the only action supported is of type `open`. + +## Usage in R + +When a user clicks the action button in the UI, the analysis is run, and the value of the option is set to `TRUE`. + +```r +if (self$options$open) { + # The user clicked the open button +} +``` + +### Performing the Action + +To actually execute the action, you must retrieve the Option object and call its `$perform()` method. + +```r +if (self$options$open) { + # 1. Retrieve the option object + option <- self$options$option('open') + + # 2. Check for compatibility + if (is.null(option$perform)) + return() + + # 3. Call $perform() with a callback + option$perform(function(action) { + # Perform logic (e.g., create a data frame) + list( + data = ToothGrowth, + title = 'Results from Action' + ) + }) +} +``` diff --git a/src/content/docs/reference/api/option-bool.md b/src/content/docs/reference/api/option-bool.md new file mode 100644 index 0000000..6d743cc --- /dev/null +++ b/src/content/docs/reference/api/option-bool.md @@ -0,0 +1,46 @@ +--- +layout: ../layouts/BaseLayout.astro +title: Bool Option +description: "Reference for the Bool option, represented as a checkbox in the jamovi user interface." +type: article +--- + +The `Bool` option represents a boolean (true/false) value. + +## Description + +In the jamovi UI, a `Bool` option is typically represented by a **Checkbox**. It is ideal for toggling specific statistics, plots, or analysis settings. + +## YAML Properties + +| Property | Type | Description | +|----------|------|-------------| +| `name` | string | The unique name of the option. | +| `type` | string | Must be `Bool`. | +| `title` | string | The label displayed in the UI. | +| `default` | boolean | The default value (`true` or `false`). Defaults to `false`. | + +## R Implementation + +In R, a `Bool` option is represented as a `logical` value (`TRUE` or `FALSE`). + +## Examples + +### 1. Define in YAML + +```yaml +- name: welch + type: Bool + title: Welch's + default: false +``` + +### 2. Implementation in R + +Access the value using `self$options$name`: + +```r +if (self$options$welch) { + # Perform Welch's t-test +} +``` diff --git a/src/content/docs/reference/api/option-data.md b/src/content/docs/reference/api/option-data.md new file mode 100644 index 0000000..acc9bc8 --- /dev/null +++ b/src/content/docs/reference/api/option-data.md @@ -0,0 +1,52 @@ +--- +layout: ../layouts/BaseLayout.astro +title: Data Option +description: "Learn how to define the primary dataset for a jamovi analysis using the Data option." +type: article +--- + +The `Data` option is used to specify the dataset that the analysis will operate on. Almost every analysis in jamovi begins with a `Data` option. + +## Description + +In the jamovi UI, the `Data` option is not explicitly represented as a control; instead, it represents the entire spreadsheet. When an analysis is called from R, the `data` argument accepts a `data.frame`. + +## YAML Properties + +| Property | Type | Description | +|----------|------|-------------| +| `name` | string | Must be `data`. | +| `type` | string | Must be `Data`. | + +## R Implementation + +In the R implementation, the data is accessed via `self$data`. While `self$options$data` exists, it is generally preferred to use `self$data` as it provides the actual `data.frame` (potentially with filters and missing value handling applied). + +## Examples + +### 1. Define in YAML + +The `Data` option should always be the first option in the `options` list of the `.a.yaml` file. + +```yaml +name: MyAnalysis +jas: '1.2' + +options: + - name: data + type: Data +``` + +### 2. Implementation in R + +Access the dataset in your `.run()` function: + +```r +.run = function() { + # Access the data frame + df <- self$data + + # Perform operations + n_rows <- nrow(df) +} +``` diff --git a/src/content/docs/reference/api/option-group.md b/src/content/docs/reference/api/option-group.md new file mode 100644 index 0000000..c57b78d --- /dev/null +++ b/src/content/docs/reference/api/option-group.md @@ -0,0 +1,52 @@ +--- +layout: ../layouts/BaseLayout.astro +title: Group Option +description: "Documentation for the Group option, used to organize analysis parameters into logical UI sections." +type: article +--- + +The `Group` option is a container used to organize related options into logical sections within the jamovi analysis panel. + +## Description + +In the jamovi UI, a `Group` option does not represent a data value itself. Instead, it acts as a visual container (often with a title) for other controls. This is essential for keeping complex analyses organized and readable. + +## YAML Properties + +| Property | Type | Description | +|----------|------|-------------| +| `name` | string | The unique name of the group. | +| `type` | string | Must be `Group`. | +| `title` | string | The heading displayed above the grouped options. | +| `items` | array | A list of option definitions that belong to this group. | + +## R Implementation + +The `Group` option has **no direct R implementation** for data processing, as it is a UI-only construct. The options contained within the group are accessed directly via `self$options$optionName`, regardless of their nesting in a group. + +## Examples + +### 1. Define in YAML + +```yaml +- name: optionsGroup + type: Group + title: Analysis Options + items: + - name: check1 + type: Bool + title: Perform normality test + - name: check2 + type: Bool + title: Perform homogeneity test +``` + +### 2. Implementation in R + +Access the nested options as if they were at the top level: + +```r +if (self$options$check1) { + # Normality test logic +} +``` diff --git a/src/content/docs/reference/api/option-integer.md b/src/content/docs/reference/api/option-integer.md new file mode 100644 index 0000000..fa774b1 --- /dev/null +++ b/src/content/docs/reference/api/option-integer.md @@ -0,0 +1,47 @@ +--- +layout: ../layouts/BaseLayout.astro +title: Integer Option +description: "Reference for the Integer option, used for whole number inputs in jamovi analyses." +type: article +--- + +The `Integer` option represents a whole number. + +## Description + +In the jamovi UI, an `Integer` option is typically represented by a **TextBox**. It validates that the user input is a whole number and falls within the specified range. + +## YAML Properties + +| Property | Type | Description | +|----------|------|-------------| +| `name` | string | The unique name of the option. | +| `type` | string | Must be `Integer`. | +| `title` | string | The label displayed in the UI. | +| `default` | integer | The default value. | +| `min` | integer | The minimum allowed value (inclusive). | +| `max` | integer | The maximum allowed value (inclusive). | + +## R Implementation + +In R, an `Integer` option is represented as an `integer` value. + +## Examples + +### 1. Define in YAML + +```yaml +- name: bootstrap + type: Integer + title: Bootstrap samples + default: 1000 + min: 1 +``` + +### 2. Implementation in R + +Access the value using `self$options$name`: + +```r +n_samples <- self$options$bootstrap +``` diff --git a/src/content/docs/reference/api/option-list.md b/src/content/docs/reference/api/option-list.md new file mode 100644 index 0000000..1af45d6 --- /dev/null +++ b/src/content/docs/reference/api/option-list.md @@ -0,0 +1,51 @@ +--- +layout: ../layouts/BaseLayout.astro +title: List Option +description: "Learn how to use the List option for selecting from predefined values in jamovi." +type: article +--- + +The `List` option allows the user to select one value from a predefined set of strings. + +## Description + +In the jamovi UI, a `List` option is typically represented by a **ComboBox** (drop-down) or a set of **RadioButtons**. + +## YAML Properties + +| Property | Type | Description | +|----------|------|-------------| +| `name` | string | The unique name of the option. | +| `type` | string | Must be `List`. | +| `title` | string | The label displayed in the UI. | +| `options` | array | A list of strings representing the available choices. | +| `default` | string | The default selected value. If omitted, the first item in `options` is used. | + +## R Implementation + +In R, a `List` option is represented as a `character` string. + +## Examples + +### 1. Define in YAML + +```yaml +- name: hypothesis + type: List + title: Hypothesis + options: + - greater + - less + - unequal + default: unequal +``` + +### 2. Implementation in R + +Access the value using `self$options$name`: + +```r +if (self$options$hypothesis == "greater") { + # Perform one-tailed test +} +``` diff --git a/src/content/docs/reference/api/option-number.md b/src/content/docs/reference/api/option-number.md new file mode 100644 index 0000000..7bad620 --- /dev/null +++ b/src/content/docs/reference/api/option-number.md @@ -0,0 +1,48 @@ +--- +layout: ../layouts/BaseLayout.astro +title: Number Option +description: "Documentation for the Number option, used for decimal and floating-point numeric inputs." +type: article +--- + +The `Number` option represents a decimal (floating-point) number. + +## Description + +In the jamovi UI, a `Number` option is typically represented by a **TextBox**. It validates that the user input is numeric and falls within the specified range. + +## YAML Properties + +| Property | Type | Description | +|----------|------|-------------| +| `name` | string | The unique name of the option. | +| `type` | string | Must be `Number`. | +| `title` | string | The label displayed in the UI. | +| `default` | number | The default value. | +| `min` | number | The minimum allowed value (inclusive). | +| `max` | number | The maximum allowed value (inclusive). | + +## R Implementation + +In R, a `Number` option is represented as a `numeric` value. + +## Examples + +### 1. Define in YAML + +```yaml +- name: ciWidth + type: Number + title: Confidence level + default: 95 + min: 50 + max: 99.9 +``` + +### 2. Implementation in R + +Access the value using `self$options$name`: + +```r +ci_level <- self$options$ciWidth / 100 +``` diff --git a/src/content/docs/reference/api/option-terms.md b/src/content/docs/reference/api/option-terms.md new file mode 100644 index 0000000..d2a042a --- /dev/null +++ b/src/content/docs/reference/api/option-terms.md @@ -0,0 +1,52 @@ +--- +layout: ../layouts/BaseLayout.astro +title: Terms Option +description: "Technical reference for the Terms option, used for model building, main effects, and interactions." +type: article +--- + +The `Terms` option is used to define model structures, including main effects and interactions between variables. + +## Description + +In the jamovi UI, the `Terms` option is typically paired with a `ListBox` and a `TermLabel`. It allows users to construct complex models (e.g., ANOVA, Linear Regression) by combining variables into interaction terms. + +## YAML Properties + +| Property | Type | Description | +|----------|------|-------------| +| `name` | string | The unique name of the option. | +| `type` | string | Must be `Terms`. | +| `title` | string | The label displayed in the UI. | +| `sources` | array | A list of option names (of type `Variable` or `Variables`) that provide the components for these terms. | + +## R Implementation + +In R, a `Terms` option is represented as a **list of character vectors**. Each character vector in the list represents a single term (e.g., `list("A", "B", c("A", "B"))` for main effects A and B, and their interaction). + +## Examples + +### 1. Define in YAML + +```yaml +- name: modelTerms + type: Terms + title: Model Terms + sources: + - factors + - covariates +``` + +### 2. Implementation in R + +Access the terms using `self$options$name`: + +```r +terms <- self$options$modelTerms + +# Example: Constructing a formula string +formula_parts <- sapply(terms, function(term) { + paste0(jmvcore::composeTerm(term)) +}) +full_formula <- paste0("dep ~ ", paste(formula_parts, collapse=" + ")) +``` diff --git a/src/content/docs/reference/api/option-variable.md b/src/content/docs/reference/api/option-variable.md new file mode 100644 index 0000000..84d04ce --- /dev/null +++ b/src/content/docs/reference/api/option-variable.md @@ -0,0 +1,56 @@ +--- +layout: ../layouts/BaseLayout.astro +title: Variable Option +description: "Learn how to use the Variable option for single column selection from the jamovi dataset." +type: article +--- + +The `Variable` option allows the user to select a single variable (column) from the dataset. + +## Description + +In the jamovi UI, a `Variable` option is represented as a **Target Drop Box**. Users can drag a single variable from the variable supplier into this slot. It is commonly used for dependent variables in simple tests or grouping variables. + +## YAML Properties + +| Property | Type | Description | +|----------|------|-------------| +| `name` | string | The unique name of the option. | +| `type` | string | Must be `Variable`. | +| `title` | string | The label displayed in the UI. | +| `suggested` | array | A list of suggested variable types (e.g., `[continuous]`). | +| `permitted` | array | A list of permitted variable types (e.g., `[continuous, ordinal, nominal]`). | +| `rejectInf` | boolean | If `true`, the analysis will error if the variable contains infinite values. Defaults to `true`. | +| `rejectMissing` | boolean | If `true`, the analysis will error if the variable contains missing values. Defaults to `false`. | + +## R Implementation + +In R, a `Variable` option is represented as a **character string** (a character vector of length 1) containing the name of the variable. If no variable is assigned, it is `NULL`. + +## Examples + +### 1. Define in YAML + +```yaml +- name: dep + type: Variable + title: Dependent Variable + suggested: + - continuous + permitted: + - continuous + - ordinal +``` + +### 2. Implementation in R + +Access the variable name using `self$options$name`: + +```r +depName <- self$options$dep + +if ( ! is.null(depName)) { + # Get the actual data column + column <- self$data[[depName]] +} +``` diff --git a/src/content/docs/reference/api/option-variables.md b/src/content/docs/reference/api/option-variables.md new file mode 100644 index 0000000..e68bfc0 --- /dev/null +++ b/src/content/docs/reference/api/option-variables.md @@ -0,0 +1,52 @@ +--- +layout: ../layouts/BaseLayout.astro +title: Variables Option +description: "Reference for the Variables option, used for multiple column selection from the jamovi dataset." +type: article +--- + +The `Variables` option allows the user to select multiple variables (columns) from the dataset. + +## Description + +In the jamovi UI, a `Variables` option is represented as a **Target Drop Box** that accepts multiple items. Users can drag several variables into this slot. It is ideal for multivariate analyses, repeated measures, or specifying multiple covariates. + +## YAML Properties + +| Property | Type | Description | +|----------|------|-------------| +| `name` | string | The unique name of the option. | +| `type` | string | Must be `Variables`. | +| `title` | string | The label displayed in the UI. | +| `suggested` | array | A list of suggested variable types. | +| `permitted` | array | A list of permitted variable types. | +| `rejectInf` | boolean | If `true`, errors on infinite values. Defaults to `true`. | +| `rejectMissing` | boolean | If `true`, errors on missing values. Defaults to `false`. | + +## R Implementation + +In R, a `Variables` option is represented as a **character vector**. If no variables are assigned, it returns an empty character vector (`character(0)`). + +## Examples + +### 1. Define in YAML + +```yaml +- name: deps + type: Variables + title: Dependent Variables + permitted: + - continuous +``` + +### 2. Implementation in R + +Access the list of variables using `self$options$name`: + +```r +depNames <- self$options$deps + +for (depName in depNames) { + # Perform analysis for each variable +} +``` diff --git a/src/content/docs/reference/api/options-api.md b/src/content/docs/reference/api/options-api.md new file mode 100644 index 0000000..e908037 --- /dev/null +++ b/src/content/docs/reference/api/options-api.md @@ -0,0 +1,87 @@ +--- +layout: ../layouts/BaseLayout.astro +title: Options API (R) +description: Learn how to access and interact with analysis options in your R code using the self$options object. +type: article +--- + +In jamovi, the `self$options` object is the **single source of truth** for your analysis. It acts as the bridge between the user interface (defined in your `.a.yaml` file) and your R execution logic. + +When a user changes a setting in the jamovi UI, those changes are synchronized to `self$options`. Your R code then reads from this object to determine how to perform the analysis. + +## The Mental Model + +Think of `self$options` as a read-only contract. It is an **R6 object** automatically generated by `jmvtools` based on your analysis definition. You should never try to modify `self$options` directly in your R code; instead, you treat it as the set of instructions provided by the user. + +## Accessing Values (The Shorthand) + +The most common task is retrieving the value of an option. jamovi provides a convenient shorthand using the `$` operator. This is the standard way to get the current state of a parameter. + +```r +# Accessing a boolean (Bool) option +if (self$options$showDescriptives) { + # ... calculate descriptives +} + +# Accessing a variable selection (Variables) +# Returns a character vector of variable names +dependentVariable <- self$options$dep + +# Accessing a numeric value (Number) +alpha <- self$options$alphaLevel +``` + +The values returned are standard R types (logical, character, numeric, etc.) corresponding to the option type defined in your YAML. + +## The Options Object API + +While the shorthand gives you the *value*, sometimes you need to interact with the **Option Object** itself. This is useful if you need to access metadata (like the option's title or default value) or if you are working with special types like [Actions](/api/option-action). + +To get the underlying R6 object, use the `$option()` method: + +```r +# Get the R6 object for 'myOption' +opt <- self$options$option('myOption') + +# Access metadata +title <- opt$title +defaultValue <- opt$default +``` + +### When to use the Object API +- **Actions**: To trigger an action via `self$options$option('myAction')$perform()`. +- **Metadata**: If your logic needs to know the default value or the title of the option as defined in the YAML. +- **Advanced Logic**: If you are writing generic code that needs to inspect the properties of the options. + +## Utility Methods + +The `self$options` object provides several utility methods to help manage parameters. + +### `as.list()` +Converts all current option values into a standard R `list`. This is particularly useful when you want to pass all analysis parameters to an external function or a base R function. + +```r +# Convert options to a list +args <- self$options$as.list() + +# Pass to another function +do.call(stats::t.test, args) +``` + +### `has(name)` +Checks if an option with the given name is defined in the analysis. This is useful for shared code that might be used across different analyses with slightly different option sets. + +```r +if (self$options$has('optionalSetting')) { + # Logic for when the option exists +} +``` + +## Relationship to Results + +Options are the primary drivers of your analysis results. This relationship manifests in two ways: + +1. **Conditional Logic (R)**: You use `if` statements checking `self$options` to decide which tables to fill or which calculations to run. +2. **Data Binding (YAML)**: You can bind the visibility or content of results directly to options in your `.r.yaml` file. For example, a table might only be visible if `self$options$showTable` is `TRUE`. + +By keeping `self$options` as the single source of truth, jamovi ensures that your analysis remains reproducible and consistent with the UI state. diff --git a/src/content/docs/reference/api/preformatted.md b/src/content/docs/reference/api/preformatted.md new file mode 100644 index 0000000..528ff35 --- /dev/null +++ b/src/content/docs/reference/api/preformatted.md @@ -0,0 +1,64 @@ +--- +layout: ../layouts/BaseLayout.astro +title: Preformatted +description: "Learn how to use the Preformatted results element for raw, monospaced text and R console output." +type: article +--- + +The `Preformatted` element is used for displaying raw, monospaced text. This is useful for showing R console output, model summaries, or any text where whitespace and alignment are important. + +## Methods + +### setStatus(status) + +sets the element's status, should be one of `'complete'`, `'error'`, `'inited'`, `'running'`. + +### setVisible(visible=TRUE) + +overrides the element's default visibility. + +### setTitle(title) + +sets the element's title. + +### setError(message) + +sets the element's status to 'error', and assigns the error message. + +### setState(object) + +sets the state object on the element. + +### setContent(content) + +sets the text content of the element. `content` should be a string. + +## Examples + +### 1. Define the Preformatted element in YAML + +A `Preformatted` element is defined in the `.r.yaml` file: + +```yaml +- name: debugOutput + title: Model Summary + type: Preformatted +``` + +### 2. Set Content in R + +In the `.run()` function, you can capture R output and display it in a `Preformatted` element: + +```r +.run = function() { + # Access a preformatted element named 'debugOutput' + pre <- self$results$debugOutput + + # Perform some calculation and capture the output + model <- lm(y ~ x, data = self$data) + output <- capture.output(summary(model)) + + # Join the lines and set the content + pre$setContent(paste(output, collapse="\n")) +} +``` diff --git a/src/content/docs/reference/api/results-definition.md b/src/content/docs/reference/api/results-definition.md index a8fd4bd..981b6d6 100644 --- a/src/content/docs/reference/api/results-definition.md +++ b/src/content/docs/reference/api/results-definition.md @@ -1,15 +1,15 @@ --- layout: ../layouts/BaseLayout.astro title: "Results Definition" +description: "Detailed reference for the jamovi results definition (.r.yaml), defining the structure of analysis output." +type: article --- -.r.yaml files - -### (In Progress) +The results definition is a YAML file in the `jamovi/` directory with the extension `.r.yaml`. It describes the structure and organization of the results produced by your analysis. ## Header -the results definition is a yaml file in the `jamovi/` directory, with the extension `.r.yaml`. the results definition describes the results produced by the analysis. the file is named to match the name of the analysis, but converted to lowercase. an example is `ttest.r.yaml`: +The header section of the `.r.yaml` file defines the identity of the results output. The file must be named to match the name of the analysis, but converted to lowercase (e.g., `ttest.r.yaml`). ```yaml --- @@ -20,87 +20,41 @@ jrs: '1.0' items: - name: ... type: ... - - name: ... - type: ... ``` -property | function --------------|----------------------------------------- -name | the name of the analysis. must correspond to the filename. -title | the title to display at the top of the results. -jrs | the `jamovi results spec`. should be '1.0'. must be wrapped in quotes to prevent it being interpretted as a number. -items | an array of results elements that make up the results. these are described in greater detail below. - -## Results - -each results element has the following properties: - - - name - - type - - title - - visible: `true` - - clearWith: `*` - -different results element types have different additional properties. - -the different results element types are as follows: - -### Preformatted - -Preformatted represents the simplest of results elements. it is simply a block of preformattd text. - -it has no additional properties. - -### Table - -Table is the most common result element in the results from jamovi analyses. Tables are represented as rich HTML tables in jamovi, and as nicely formatted ascii tables in an interactive R session. - -properties: - -property | default | description --------------------|---------|--------------------------------------- -columns | | an array of columns objects, see below -rows | `0` | an integer specifying the number of rows, or a data-binding where one row is created per element of the bound value -swapRowsColumns | `false` | whether the rows and columns should be swapped -notes | `[ ]` | an array of strings which appear as additional notes in the footnotes of the table. - -#### Column - -properties: - -property | default | description --------------|----------|--------------------------------------- -name | | the name of the column, a string -title | | the title that appears at the top of the column -type | `number` | either `number` (aligned right), `integer` (aligned right, displayed to zero decimal places) or `text` (aligned left) -format | | (optional) a string with comma separated values; `zto`, `pvalue` -content | | (optional) the content to appear in the cells of the column. -visible | `true` | `true`, `false` or a data-binding. the column will be visible if the bound value isn't `false` or `null` -superTitle | | (optional) a title to appear above the title of the column -combineBelow | `false` | if multiple adjacent cells in the column contain the same value, they will be combined into a single cell - -### Image - -properties: +| Property | Description | +| :--- | :--- | +| `name` | The internal name of the analysis. Must correspond to the filename. | +| `title` | The title displayed at the top of the jamovi results panel. | +| `jrs` | The jamovi results spec version (typically `'1.0'`). Must be wrapped in quotes. | +| `items` | An array of results elements that make up the results tree. | - - **width**: Integer. Default: 400. - - **height**: Integer. Default: 300. - - **renderFun**: String. The name of the R function used to render the plot. - - **requiresData**: Boolean or Logical Expression. Determines if the `renderFun` has access to the dataset (`self$data`). - -> [!TIP] -> Setting `requiresData: true` is essential for **Data-Driven** plots (like scatter plots) where the plot function needs the raw dataset. For more details on performance, see the **[Image State Performance](/tutorial/tuts0301-image-state-performance)** tutorial. +## Results Elements -### Group +The `items` property contains a collection of results elements. Each element type is designed for a specific kind of output. -properties: +### Element Types - - items +| Type | Description | +| :--- | :--- | +| [**Table**](/api/table) | Structured tabular data with columns and rows. | +| [**Image**](/api/image) | Plots and other graphical output. | +| [**Group**](/api/group) | A container for organizing other elements into sections. | +| [**Array**](/api/array) | A dynamic container for repeating elements (e.g., a table per factor level). | +| [**Notice**](/api/notice) | Informational messages, warnings, or errors. | +| [**Preformatted**](/api/preformatted) | Raw, monospaced text output. | +| [**Html**](/api/html) | Custom, rich HTML content. | -### Array +## Common Element Properties -properties: +All results elements share a set of common properties that can be configured in the YAML: - - items - - template +| Property | Description | +| :--- | :--- | +| `name` | The internal name used to access the element in R (e.g., `self$results$name`). | +| `type` | The type of results element (see table above). | +| `title` | The display title for the element in the results panel. | +| `visible` | (Optional) Whether the element is visible by default. Can be a boolean or a data-binding to an option. Defaults to `true`. | +| `clearWith` | (Optional) A list of option names. The element will be cleared/reset when any of these options change. Defaults to `*` (all options). | +For a detailed look at how to interact with these elements in your R code, see the [Results API (R)](/api/results-elements) documentation. diff --git a/src/content/docs/reference/api/results-elements.md b/src/content/docs/reference/api/results-elements.md index 6f0d54e..ccf6c42 100644 --- a/src/content/docs/reference/api/results-elements.md +++ b/src/content/docs/reference/api/results-elements.md @@ -1,80 +1,110 @@ --- layout: ../layouts/BaseLayout.astro title: Results Elements +description: Overview of jamovi Results Elements, the building blocks of an analysis output, including the Results Tree and dynamic creation in R. +type: article --- -This document describes the properties and methods of the results elements: +Results Elements are the building blocks of a jamovi analysis output. They are R6 objects that jamovi automatically instantiates based on the [Results Definition](/api/results-definition) (`.r.yaml`) of your module. - - Image - - Group - - Array - - Preformatted - - Html - -Table is described [here](/api/table). - -The values of properties can be accessed using the `$` operator. For example, to retrieve the title of an element, one can go: +In your analysis R code, these elements are accessed via `self$results`. For example, if you have a table named `resultsTable` defined in your `.r.yaml`, you can access it in R using: ```r -element$title +self$results$resultsTable ``` -The methods of a results elements are called using the `$` operator as well. For example: +## The Results Tree -```r -element$setTitle('An awesome title') -``` +The results of an analysis are organized in a hierarchical structure known as the **Results Tree**. The root of this tree is `self$results` (which is itself a [Group](/api/group) element). -## Elements +Elements like [Groups](/api/group) and [Arrays](/api/array) can contain other elements, allowing you to create complex, nested output structures. -The following properties and methods are common to all results elements +## Relationship to YAML -### Properties +The available elements and their initial configuration (such as titles, visibility, and default settings) are defined in the `.r.yaml` file. When an analysis is run, jamovi reads this definition and creates the corresponding R6 objects. While you can modify many properties of these objects at runtime (e.g., changing a title or hiding a table), their fundamental structure is determined by the YAML. -#### name +## Element Types -a string specifying the name of the element +jamovi provides several types of results elements, each designed for a specific purpose: -#### title +| Element | Description | +|---------|-------------| +| [Table](/api/table) | The most common element, used for displaying tabular data, statistics, and coefficients. | +| [Image](/api/image) | Used for displaying plots and other graphical output. | +| [Group](/api/group) | A container used to group related elements together. | +| [Array](/api/array) | A dynamic container that can hold multiple instances of the same element type (e.g., a table for each level of a factor). | +| [Notice](/api/notice) | Used for displaying informational messages, warnings, or errors. | +| [Preformatted](/api/preformatted) | Used for displaying raw text output, often from other R packages. | +| [Html](/api/html) | Used for displaying custom HTML content. | -a string specifying the title of the element +## Common API -#### visible +All results elements share a common set of properties and methods. These can be accessed using the `$` operator. -`TRUE` or `FALSE`, whether the element is visible or not +### Properties -#### status +#### name +A string specifying the name of the element as defined in the `.r.yaml`. -a string, one of `'complete'`, `'error'`, `'inited'`, `'running'` +#### title +A string specifying the title of the element. -#### rowKeys +#### visible +A boolean (`TRUE` or `FALSE`) indicating whether the element is currently visible in the jamovi results panel. -a list of 'keys' +#### status +A string indicating the current status of the element. Possible values are: +- `'inited'`: The element has been initialized but not yet run. +- `'running'`: The analysis is currently calculating values for this element. +- `'complete'`: The element has finished running and is displaying its final results. +- `'error'`: An error occurred during the calculation of this element. #### state - -the state +The state object associated with the element, used for caching and performance optimization. ### Methods -#### setStatus(status) +#### setTitle(title) +Sets the title of the element. +- `title`: A string containing the new title. -sets the element's status, should be one of `'complete'`, `'error'`, `'inited'`, `'running'` +#### setVisible(visible) +Sets the visibility of the element. +- `visible`: `TRUE` to show the element, `FALSE` to hide it. -#### setVisible(visible=TRUE) +#### setStatus(status) +Sets the status of the element. +- `status`: One of `'inited'`, `'running'`, `'complete'`, or `'error'`. -overrides the elements default visibility +#### setError(message) +Sets the element's status to `'error'` and displays the provided error message. +- `message`: A string containing the error message. -#### setTitle(title) +#### setState(object) +Sets the state object for the element. +- `object`: The object to be stored as state. -sets the element's title +## Dynamic Creation -#### setError(message) +While most results elements are defined in the `.r.yaml` file, they can also be created dynamically in R during the execution of an analysis. This is useful for output structures that depend on the data or for conditional elements like warnings. -sets the element's status to 'error', and assigns the error message +### Use Cases -#### setState(object) +- **Conditional Warnings**: Displaying a [Notice](/api/notice) only when certain conditions (e.g., assumption violations) are met. +- **Dynamic Output**: Using [Arrays](/api/array) to create a variable number of tables or plots based on the input data. + +### Methods -sets the state object on the element +To add a dynamically created element to the results, you can use the `insert()` method on a [Group](/api/group) object. +#### insert(index, element) +Inserts an element at a specific position within a group. +- `index`: The 1-based index where the element should be inserted. +- `element`: The results element object to insert. +Example: +```r +notice <- jmvcore::Notice$new(options=self$options, name='dynamicNotice') +notice$setContent("This is a dynamic notice.") +self$results$insert(1, notice) +``` diff --git a/src/content/docs/reference/api/table.md b/src/content/docs/reference/api/table.md index 797cdfa..aacd241 100644 --- a/src/content/docs/reference/api/table.md +++ b/src/content/docs/reference/api/table.md @@ -1,22 +1,12 @@ --- layout: ../layouts/BaseLayout.astro title: Table +description: "Comprehensive reference for jamovi Table objects, including column definitions, row management, and formatting." +type: article --- This document describes the properties and methods of a jamovi table object. -The values of properties can be accessed using the `$` operator, followed by the name. For example, to retrieve the title of a table, one can go: - -``` -table$title -``` - -The methods of a table object are called using the `$` operator as well. For example: - -```r -table$setRow(rowKey=1, values=list(t=2.3, df=2, p=0.45)) -``` - ## Properties ### name @@ -151,3 +141,52 @@ In practice, when an analysis is changed or re-run, `init` notes are not restore > [!TIP] > If the text of the note will always be the same, it is recommended to set the note in the `.r.yaml` file instead. + +## Examples + +### 1. Define the Table in YAML + +A `Table` is defined in the `.r.yaml` file. It typically includes a list of `columns`, but can also be defined with no columns if they are to be added dynamically in the R implementation. + +#### Static Columns +Defining a table with a fixed set of columns: + +```yaml +- name: statsTable + title: Descriptive Statistics + type: Table + rows: 1 + columns: + - name: var + title: Variable + type: text + - name: mean + title: Mean + type: number + - name: sd + title: SD + type: number +``` + +#### Dynamic Columns +Defining a table that will have its columns added at runtime using the [`addColumn()`](#addcolumnname-) method: + +```yaml +- name: dynamicTable + title: Results Table + type: Table +``` + +### 2. Implementation in R + +The values of properties can be accessed using the `$` operator, followed by the name. For example, to retrieve the title of a table, one can go: + +``` +table$title +``` + +The methods of a table object are called using the `$` operator as well. For example: + +```r +table$setRow(rowKey=1, values=list(t=2.3, df=2, p=0.45)) +``` diff --git a/src/content/docs/reference/api/ui-definition.md b/src/content/docs/reference/api/ui-definition.md index 1a8e8df..13c6217 100644 --- a/src/content/docs/reference/api/ui-definition.md +++ b/src/content/docs/reference/api/ui-definition.md @@ -1,89 +1,93 @@ --- layout: ../layouts/BaseLayout.astro title: "User-interface Definition" +description: "Guide to customizing the jamovi user interface using the UI definition (.u.yaml), including controls and layout." +type: article --- -## Automatic UI Generation +The user-interface definition is a YAML file in the `jamovi/` directory with the extension `.u.yaml`. While jamovi can automatically generate a UI from your analysis definition, the `.u.yaml` file allows you to customize the layout and appearance of the analysis options panel. + +## Header -One of the most powerful features of jamovi is its ability to automatically generate a functional user interface from your analysis definition (`.a.yaml`). When you run `jmvtools::install()`, jamovi looks at the `type` of each option and picks a sensible default control: +The header section defines the structure of the options panel. The file must be named to match the name of the analysis, but converted to lowercase (e.g., `ttest.u.yaml`). + +```yaml +name: ttest +title: Independent Samples T-Test +jus: '2.0' +compilerMode: tame +children: + - type: ... + name: ... +``` -| Option Type (`.a.yaml`) | Default UI Control (`.u.yaml`) | +| Property | Description | | :--- | :--- | -| `Bool` | `CheckBox` | -| `List` | `ComboBox` | -| `Variable` | `TargetLayoutBox` containing a `VariableLabel` | -| `Variables` | `TargetLayoutBox` containing multiple `VariableLabel`s | -| `Integer` / `Number` | `TextBox` | +| `name` | The internal name of the analysis. | +| `title` | The title displayed at the top of the options panel. | +| `jus` | The jamovi UI spec version (typically `'2.0'`). Must be wrapped in quotes. | +| `compilerMode` | Controls how `jmvtools` handles the file. Either `tame` or `aggressive`. Defaults to `aggressive`. | +| `events` | (Optional) Maps view-level events (e.g., `update`) to JavaScript handlers. | +| `children` | An array of UI controls that define the layout of the panel. | -## The UI YAML Structure +## Compiler Modes -For many analyses, the automatically generated UI is sufficient. However, for more complex tools, you will want to customize the layout, add labels, or group controls into sections. This is where `ttest.u.yaml` comes in. It follows a tree structure of controls. +The `compilerMode` property determines how the jamovi compiler (`jmvtools`) interacts with your `.u.yaml` file. It defaults to `aggressive` when an analysis is first created. -### Properties +- **`aggressive` (Default)**: The compiler will automatically regenerate and overwrite the `.u.yaml` file every time you install or build the module. This ensures the UI stays in sync with your `.a.yaml` but means **any manual changes to the UI definition will be lost.** +- **`tame`**: The compiler will respect your manual edits. It will add new controls for any new options you define, but it will not overwrite or rearrange your existing structure. **You must set the mode to `tame` if you wish to hand-polish your UI layout.** -| Property | Description | Form | -| :--- | :--- | :--- | -| `name` | The name of the analysis. | Unique string | -| `title` | Sets the title to be displayed at the top of the option panel. | string | -| `jus` | Defines the syntax version used (typically `'2.0'`). | string | -| `children` | An array of child control definitions. | Array | +## UI Interactivity (JavaScript) -### Example: Customizing Layout +For more complex UI behaviors, such as dynamically hiding controls or responding to user input with custom logic, jamovi allows you to attach JavaScript event handlers. These handlers are defined in a `.js` file in the `jamovi/js` directory and linked via the `events` property in your `.u.yaml`. -```yaml -name: descriptives -title: Descriptives -jus: '2.0' -children: - - type: LayoutBox - margin: large - children: - - type: CheckBox - name: plot_enabled - label: Enable Plots - - type: CollapseBox - label: Advanced Options - collapsed: true - children: - - type: TextBox - name: custom_iterations - label: Iterations -``` +For a comprehensive guide on building interactive interfaces and a complete list of available events, see the **[Advanced Customisation](/ui/advanced-customisation)** tutorial. -## Controls -The UI can be built using a variety of specialized controls: +## UI Controls -### Base Control +The UI is built using a hierarchy of controls. These controls are organized into three primary categories: -- [BaseControl (abstract)](/ui/basecontrol) +### Layout & Containers +Used to organize and group other controls. +- [**LayoutBox**](/ui/layoutbox): A generic container for layout management. +- [**CollapseBox**](/ui/collapsebox): A group that can be expanded or collapsed. +- [**TargetLayoutBox**](/ui/targetlayoutbox): A container specifically for variable drop targets. -### Layout Controls +### Input Controls +Directly map to analysis options defined in the `.a.yaml`. +- [**CheckBox**](/ui/checkbox): For boolean options. +- [**ComboBox**](/ui/combobox): For selecting from a list of options. +- [**TextBox**](/ui/textbox): For numeric or text input. +- [**RadioButton**](/ui/radiobutton): For selecting one from a set of mutually exclusive options. +- [**ListBox**](/ui/listbox): For managing lists of items (e.g., terms or custom levels). -- [ParentControl (abstract)](/ui/parentcontrol) -- [LayoutBox](/ui/layoutbox) -- [CollapseBox](/ui/collapsebox) -- [Supplier](/ui/supplier) -- [VariableSupplier](/ui/variablesupplier) -- [TargetLayoutBox](/ui/targetlayoutbox) +### Specialized Controls +- [**VariableSupplier**](/ui/variablesupplier): Displays the available variables from the dataset. +- [**VariableLabel**](/ui/variablelabel): Represents a single variable within a target box. +- [**TermLabel**](/ui/termlabel): Represents a model term (e.g., an interaction). +- [**Label**](/ui/label): Displays static text or titles within the UI. -#### Parent Controls +## Common Control Properties -- [CheckBox](/ui/checkbox) -- [RadioButton](/ui/radiobutton) -- [Label](/ui/label) +Most UI controls share these fundamental properties: -### Option Controls +| Property | Description | +| :--- | :--- | +| `type` | The class of the UI control (e.g., `CheckBox`). | +| `name` | (For option controls) The name of the corresponding option in `.a.yaml`. | +| `label` | The text label displayed next to or above the control. | -- [TextBox](/ui/textbox) -- [CheckBox](/ui/checkbox) -- [RadioButton](/ui/radiobutton) -- [ComboBox](/ui/combobox) -- [Label](/ui/label) -- [ListBox](/ui/listbox) -- [VariableLabel](/ui/variablelabel) -- [TermLabel](/ui/termlabel) +--- + +## Automatic UI Generation -### Display Controls +If no `.u.yaml` file is provided, jamovi automatically generates a functional interface based on your [Analysis Definition](/api/analysis-definition). -- [Label](/ui/label) +| Option Type (`.a.yaml`) | Default UI Control | +| :--- | :--- | +| `Bool` | `CheckBox` | +| `List` | `ComboBox` | +| `Variable` | `TargetLayoutBox` containing a `VariableLabel` | +| `Variables` | `TargetLayoutBox` containing multiple `VariableLabel`s | +| `Integer` / `Number` | `TextBox` | diff --git a/src/content/docs/reference/ui/basecontrol.md b/src/content/docs/reference/ui/basecontrol.md index d49d450..ccb66d9 100644 --- a/src/content/docs/reference/ui/basecontrol.md +++ b/src/content/docs/reference/ui/basecontrol.md @@ -1,6 +1,8 @@ --- layout: ../layouts/BaseLayout.astro title: "BaseControl" +type: article +description: "Technical reference for the BaseControl abstract class, the foundation for all jamovi UI controls." output: html_document --- diff --git a/src/content/docs/reference/ui/checkbox.md b/src/content/docs/reference/ui/checkbox.md index 6044ede..f8a0658 100644 --- a/src/content/docs/reference/ui/checkbox.md +++ b/src/content/docs/reference/ui/checkbox.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: "CheckBox" +type: article --- **Inherits from [`OptionControl`](/ui/optioncontrol), [`ParentControl`](/ui/parentcontrol)** diff --git a/src/content/docs/reference/ui/collapsebox.md b/src/content/docs/reference/ui/collapsebox.md index 3d1fe74..abfd43a 100644 --- a/src/content/docs/reference/ui/collapsebox.md +++ b/src/content/docs/reference/ui/collapsebox.md @@ -1,6 +1,8 @@ --- layout: ../layouts/BaseLayout.astro title: "CollapseBox" +type: article +description: "Technical reference for the jamovi UI CollapseBox control, which allows for grouping options in an expandable/collapsible section." output: html_document --- diff --git a/src/content/docs/reference/ui/combobox.md b/src/content/docs/reference/ui/combobox.md index 1ba3c05..82b19fa 100644 --- a/src/content/docs/reference/ui/combobox.md +++ b/src/content/docs/reference/ui/combobox.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: "ComboBox" +type: article --- **Inherits from [`OptionControl`](/ui/optioncontrol)** diff --git a/src/content/docs/reference/ui/custom-format.md b/src/content/docs/reference/ui/custom-format.md index addd5c3..d78aeba 100644 --- a/src/content/docs/reference/ui/custom-format.md +++ b/src/content/docs/reference/ui/custom-format.md @@ -1,6 +1,8 @@ --- layout: ../layouts/BaseLayout.astro title: "Custom Formats" +type: article +description: "Information about creating custom formats for jamovi UI controls (Coming Soon)." output: html_document --- diff --git a/src/content/docs/reference/ui/label.md b/src/content/docs/reference/ui/label.md index 9135998..671989a 100644 --- a/src/content/docs/reference/ui/label.md +++ b/src/content/docs/reference/ui/label.md @@ -1,6 +1,8 @@ --- layout: ../layouts/BaseLayout.astro title: "Label" +type: article +description: "Technical reference for the jamovi UI Label control, used for displaying static text or read-only option values." --- A `Label` is a simple control that displays text. It can take two inheritance forms depending on how it is setup. The first is a *static label* and the second is an *option label*. diff --git a/src/content/docs/reference/ui/layoutbox.md b/src/content/docs/reference/ui/layoutbox.md index c374545..9062fa0 100644 --- a/src/content/docs/reference/ui/layoutbox.md +++ b/src/content/docs/reference/ui/layoutbox.md @@ -1,6 +1,8 @@ --- layout: ../layouts/BaseLayout.astro title: "LayoutBox" +type: article +description: "Technical reference for the jamovi UI LayoutBox control, used for organizing and positioning child controls." output: html_document --- diff --git a/src/content/docs/reference/ui/listbox.md b/src/content/docs/reference/ui/listbox.md index 53cce82..e9f0424 100644 --- a/src/content/docs/reference/ui/listbox.md +++ b/src/content/docs/reference/ui/listbox.md @@ -1,6 +1,8 @@ --- layout: ../layouts/BaseLayout.astro title: "ListBox" +type: article +description: "Technical reference for the jamovi UI ListBox control, used for managing lists of items such as variables or terms." output: html_document --- diff --git a/src/content/docs/reference/ui/optioncontrol.md b/src/content/docs/reference/ui/optioncontrol.md index bd41db2..d1bff74 100644 --- a/src/content/docs/reference/ui/optioncontrol.md +++ b/src/content/docs/reference/ui/optioncontrol.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: "OptionControl" +type: article output: html_document --- diff --git a/src/content/docs/reference/ui/parentcontrol.md b/src/content/docs/reference/ui/parentcontrol.md index 7251f4c..94e13a0 100644 --- a/src/content/docs/reference/ui/parentcontrol.md +++ b/src/content/docs/reference/ui/parentcontrol.md @@ -1,6 +1,8 @@ --- layout: ../layouts/BaseLayout.astro title: "ParentControl" +type: article +description: "Technical reference for the ParentControl class, which provides common functionality for controls that can contain others." output: html_document --- diff --git a/src/content/docs/reference/ui/radiobutton.md b/src/content/docs/reference/ui/radiobutton.md index be569d6..cdf7b4f 100644 --- a/src/content/docs/reference/ui/radiobutton.md +++ b/src/content/docs/reference/ui/radiobutton.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: "RadioButton" +type: article --- **Inherits from [`OptionControl`](/ui/optioncontrol), [`ParentControl`](/ui/parentcontrol)** diff --git a/src/content/docs/reference/ui/standard-formats.md b/src/content/docs/reference/ui/standard-formats.md index 2a9a205..1280cbb 100644 --- a/src/content/docs/reference/ui/standard-formats.md +++ b/src/content/docs/reference/ui/standard-formats.md @@ -1,6 +1,8 @@ --- layout: ../layouts/BaseLayout.astro title: "Standard UI Formats" +type: article +description: "Reference for standard UI formats available in jamovi, such as variable, term, number, and bool." output: html_document --- diff --git a/src/content/docs/reference/ui/supplier.md b/src/content/docs/reference/ui/supplier.md index cf0288c..d164fb9 100644 --- a/src/content/docs/reference/ui/supplier.md +++ b/src/content/docs/reference/ui/supplier.md @@ -1,6 +1,8 @@ --- layout: ../layouts/BaseLayout.astro title: "Supplier" +type: article +description: "Technical reference for the jamovi UI Supplier control, used as a source for items like variables or levels." --- The `Supplier` control is a generic list of items from which the user can select and drag to other controls. It is often used for supplying factors or other non-variable items. diff --git a/src/content/docs/reference/ui/targetlayoutbox.md b/src/content/docs/reference/ui/targetlayoutbox.md index f2ac306..cf85a5c 100644 --- a/src/content/docs/reference/ui/targetlayoutbox.md +++ b/src/content/docs/reference/ui/targetlayoutbox.md @@ -1,6 +1,8 @@ --- layout: ../layouts/BaseLayout.astro title: "TargetLayoutBox" +type: article +description: "Technical reference for the jamovi UI TargetLayoutBox control, used to create drop targets for variables." --- The `TargetLayoutBox` is a container that acts as a destination for items dragged from a `Supplier` or `VariableSupplier`. It is used to define areas where users drop variables to assign them to analysis options. diff --git a/src/content/docs/reference/ui/termlabel.md b/src/content/docs/reference/ui/termlabel.md index 8cb98c8..6ae22d3 100644 --- a/src/content/docs/reference/ui/termlabel.md +++ b/src/content/docs/reference/ui/termlabel.md @@ -1,6 +1,8 @@ --- layout: ../layouts/BaseLayout.astro title: "TermLabel" +type: article +description: "Technical reference for the jamovi UI TermLabel control, specifically designed for displaying interaction terms." output: html_document --- The `TermLabel` control is used to represent interaction terms (e.g., `A * B`) within a `TargetLayoutBox`. It is typically used in analyses with complex models like ANOVA or Regression. diff --git a/src/content/docs/reference/ui/textbox.md b/src/content/docs/reference/ui/textbox.md index f5aa22e..80b667f 100644 --- a/src/content/docs/reference/ui/textbox.md +++ b/src/content/docs/reference/ui/textbox.md @@ -1,6 +1,8 @@ --- layout: ../layouts/BaseLayout.astro title: "TextBox" +type: article +description: "Technical reference for the jamovi UI TextBox control, used for entering text, numbers, and other formatted data." --- **Inherits from [`OptionControl`](/ui/optioncontrol)** diff --git a/src/content/docs/reference/ui/variablelabel.md b/src/content/docs/reference/ui/variablelabel.md index 457fed3..f74ea4f 100644 --- a/src/content/docs/reference/ui/variablelabel.md +++ b/src/content/docs/reference/ui/variablelabel.md @@ -1,6 +1,8 @@ --- layout: ../layouts/BaseLayout.astro title: "VariableLabel" +type: article +description: "Technical reference for the jamovi UI VariableLabel control, used for displaying variable names with their respective icons." output: html_document --- The `VariableLabel` control is used to represent a single variable within a `TargetLayoutBox`. It provides the visual representation of a "dropped" variable. diff --git a/src/content/docs/reference/ui/variablesupplier.md b/src/content/docs/reference/ui/variablesupplier.md index 01af732..291796f 100644 --- a/src/content/docs/reference/ui/variablesupplier.md +++ b/src/content/docs/reference/ui/variablesupplier.md @@ -1,6 +1,8 @@ --- layout: ../layouts/BaseLayout.astro title: "VariableSupplier" +type: article +description: "Technical reference for the jamovi UI VariableSupplier control, the primary source for variables in an analysis UI." --- The `VariableSupplier` is a foundational component of the jamovi UI. it represents the sidebar on the left of the analysis options that lists all the variables available in the current dataset. diff --git a/src/content/docs/resources/misc/cheat-sheet.md b/src/content/docs/resources/misc/cheat-sheet.md index 9500bc2..ccac3b7 100644 --- a/src/content/docs/resources/misc/cheat-sheet.md +++ b/src/content/docs/resources/misc/cheat-sheet.md @@ -1,6 +1,7 @@ --- layout: ../layouts/BaseLayout.astro title: "Development Cheat Sheet" +type: article description: "A quick reference guide for building jamovi modules, analyses, and results." --- diff --git a/src/content/docs/resources/misc/project-structure.md b/src/content/docs/resources/misc/project-structure.md index 8912c23..00055c4 100644 --- a/src/content/docs/resources/misc/project-structure.md +++ b/src/content/docs/resources/misc/project-structure.md @@ -1,6 +1,8 @@ --- layout: ../layouts/BaseLayout.astro title: "project structure" +type: article +description: "Overview of the jamovi source code structure, including build components, assembly process, and directory layout." --- the jamovi source structure contains the following components: diff --git a/src/content/docs/resources/misc/updates.md b/src/content/docs/resources/misc/updates.md index fb33d37..3984739 100644 --- a/src/content/docs/resources/misc/updates.md +++ b/src/content/docs/resources/misc/updates.md @@ -1,6 +1,8 @@ --- layout: ../layouts/BaseLayout.astro title: API Updates +type: article +description: "Stay informed about the latest changes, ecosystem improvements, and API updates for jamovi developers." --- Welcome to the jamovi developer updates page. Here we track important changes to the jamovi API and ecosystem improvements. @@ -52,4 +54,4 @@ Significant improvements to the development workflow: - **Compiler Modes**: Introduced `aggressive` (default) and `tame` modes for UI generation. ### Dev Mode & Debugging (02-04-2017) -jamovi 0.7.2.7 adds **dev mode**, providing a stack trace when an analysis errors. Read more in [Debugging an Analysis](/tutorial/tuts0204-debugging-an-analysis). +jamovi 0.7.2.7 adds **dev mode**, providing a stack trace when an analysis errors. Read more in [Debugging an Analysis](/tutorial/tuts0104-input-checks). diff --git a/src/data/menu.ts b/src/data/menu.ts index 8bdf2ca..313f2f7 100644 --- a/src/data/menu.ts +++ b/src/data/menu.ts @@ -23,6 +23,7 @@ export const menu = [ { text: '3 - Advanced Table Techniques', href: '/tutorial/tuts0201a-advanced-table-techniques' }, { text: '4 - Handling Data', href: '/tutorial/tuts0202-handling-data' }, { text: '5 - State', href: '/tutorial/tuts0203-state' }, + { text: '6 - Module Translation', href: '/tutorial/tuts0204-translation' }, ] }, { @@ -64,13 +65,33 @@ export const menu = [ }, { section: 'reference', - category: 'API (R)', + category: 'Options API (R)', + items: [ + { text: 'Options API', href: '/api/options-api' }, + { text: 'Data', href: '/api/option-data' }, + { text: 'Bool', href: '/api/option-bool' }, + { text: 'Integer', href: '/api/option-integer' }, + { text: 'Number', href: '/api/option-number' }, + { text: 'List', href: '/api/option-list' }, + { text: 'Variable', href: '/api/option-variable' }, + { text: 'Variables', href: '/api/option-variables' }, + { text: 'Terms', href: '/api/option-terms' }, + { text: 'Group', href: '/api/option-group' }, + { text: 'Action', href: '/api/option-action' }, + ] + }, + { + section: 'reference', + category: 'Results API (R)', items: [ { text: 'Results Elements', href: '/api/results-elements' }, { text: 'Table', href: '/api/table' }, - { text: 'Notices', href: '/api/notices' }, - { text: 'Actions', href: '/api/actions' }, - { text: 'Module Translation', href: '/api/i18n' }, + { text: 'Image', href: '/api/image' }, + { text: 'Group', href: '/api/group' }, + { text: 'Array', href: '/api/array' }, + { text: 'Preformatted', href: '/api/preformatted' }, + { text: 'Html', href: '/api/html' }, + { text: 'Notice', href: '/api/notice' }, ] }, { diff --git a/src/pages/404.astro b/src/pages/404.astro new file mode 100644 index 0000000..a6ae7c6 --- /dev/null +++ b/src/pages/404.astro @@ -0,0 +1,157 @@ +--- +import BaseLayout from '../layouts/BaseLayout.astro'; +import Search from '../components/Search.astro'; + +const frontmatter = { + title: '404 - Page Not Found', + description: 'The page you are looking for has moved or does not exist.' +}; +--- + + +
+

+ We've recently updated our documentation and some pages have moved. + The content you're looking for might be under a new URL. +

+ +
+

Try searching for the topic you're looking for:

+
+ +
+
+ + + +
+

Quick Links

+ +
+
+ + + + +