From 785f4be5e07071e318f731b6966fae3fa6d0001e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Rodr=C3=ADguez=20S=C3=A1nchez?= Date: Wed, 6 Nov 2024 14:35:11 +0100 Subject: [PATCH 1/7] Enable GitHub pages --- _config.yml | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 _config.yml diff --git a/_config.yml b/_config.yml new file mode 100644 index 0000000000..da027c6046 --- /dev/null +++ b/_config.yml @@ -0,0 +1,3 @@ +theme: jekyll-theme-minimal +title: Developer's docs +description: Manual for JASP module developers From 7a64760149ff0a9b943f768a4465fd29c99f5b54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Rodr=C3=ADguez=20S=C3=A1nchez?= Date: Tue, 26 Nov 2024 12:56:30 +0100 Subject: [PATCH 2/7] Fix wrong table format --- Docs/development/jasp-adding-module.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Docs/development/jasp-adding-module.md b/Docs/development/jasp-adding-module.md index 21a1f40c89..84686c116a 100644 --- a/Docs/development/jasp-adding-module.md +++ b/Docs/development/jasp-adding-module.md @@ -50,10 +50,10 @@ So the root object of your `Description.qml` is a `Description` object that has | `maintainer` | Name and email of maintainer. An example: "John Doe \". If it isn't a valid email adress **R will complain**. | | `website` | Website of the author. | | `license` | License under which the module is released. To have it distributed by us this should be a [free software license](https://en.wikipedia.org/wiki/Free_software_license), aka something like "GPL (>= 2)". | - | `requiresData` | Optional: Whether the analyses and/or module require a dataset or not. | + | `requiresData` | Optional: Whether the analyses and/or module require a dataset or not. | | `preloadData` | Optional: Whether the analyses can handle getting the dataset as an argument to the R-function. | - In the future most of this info will be taking straight from [DESCRIPTION](#packageMetadata). + In the future most of this info will be taken straight from [DESCRIPTION](#packageMetadata). #### Description Menu A very important part of [Description.qml](#Description.qml) is the menu specification, as this makes it possible for a user of your module to actually run your analyses. You specify the analyses your module offers, what their titles are, which [options form](#qml) they use and which R-functions should be called to run them. Furthermore you can add separators between groups of analyses and you can add headers with icons inside the menu to make it clearer what category each group of analyses embodies. From 8d872864ea9356aaf1cea65f13843dd18e1b3bf6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Rodr=C3=ADguez=20S=C3=A1nchez?= Date: Tue, 26 Nov 2024 13:36:19 +0100 Subject: [PATCH 3/7] Improve readability and add graphical approaches --- Docs/development/jasp-adding-module.md | 174 ++++++++++++++----------- 1 file changed, 97 insertions(+), 77 deletions(-) diff --git a/Docs/development/jasp-adding-module.md b/Docs/development/jasp-adding-module.md index 84686c116a..db8a7ffba6 100644 --- a/Docs/development/jasp-adding-module.md +++ b/Docs/development/jasp-adding-module.md @@ -8,88 +8,55 @@ In a nutshell, a JASP module provides no more (and no less) than a user-friendly ![](./img/puzzle.svg) -The ability to add your own module to JASP is a recently added feature (as of 0.9.3). + ## Structure -A module folder should look as follows: - -- ModuleName/ - - [inst/](#inst) - - [Description.qml](#Descriptionqml) - - [Upgrades.qml](#Upgradesqml) - - [icons/](#icons) - - [qml/](#qml) - - [help/](#help) - - [R/](#r) - - [DESCRIPTION](#package-metadata) - - [NAMESPACE](#package-metadata) - -### Description.qml -The Description.qml file is the main configuration file for a JASP Module and consists of a `Description` qml root object where you can add `Package`'s and `Analysis`, `GroupTitle` and `Separator` objects to. I would suggest you take a look at the description made by the JASP team at [one our modules on GitHub](https://github.com/jasp-stats). - -It should always start with the following: +A module folder looks like a standard R package + some special files in the `inst/` folder: + +```sh +. +├── .Rproj +├── DESCRIPTION +├── LICENSE +├── NAMESPACE # Controls function importing +├── R # Where the package functions live +│ └── functions.R +│ └── more-functions.R +│ └── ... +├── README.md +├── renv.lock # Optional +├── _processedLockFile.lock # Optional +├── tests/ # Optional +│ +│ # === So far, this is just a standard R package === +│ # === Interaction with JASP starts below === +│ +└──inst + ├── Description.qml + ├── Upgrades.qml # Optional + ├── help + ├── icons + └── qml + └── examples.qml ``` -import QtQuick 2.12 -import JASP.Module 1.0 -Description -{ -``` +The functionality of those files can be graphically summarized as follows: -#### Module Description -So the root object of your `Description.qml` is a `Description` object that has the following properties: - - | property | description | - |---------------|-------------| - | `name` | Specifies the name of the module, only necessary if you are not adding your own [DESCRIPTION](#packageMetadata) file. This name should contain only ASCII letters, numbers and dots, have at least two characters and start with a letter and not end in a dot.| - | `title` | The user-friendly name that is shown in the ribbonbar (top of JASP) and the modules-menu (the right-hand-side menu in JASP). | - | `description` | A description of the module that will be shown during install. | - | `icon` | The filename of the icon to show in the ribbonbar. | - | `version` | The current version of your module, encoded as a string. This is a sequence of at least two (and usually three) non-negative integers separated by single ‘.’ or ‘-’ characters. A good example is "1.0.0", a version such as "0.01" or "0.01.0" will be handled as if it were ‘0.1-0’. It is not a decimal number, so for example "0.9" < "0.75" since 9 < 75. | - | `author` | Name of the author. | - | `maintainer` | Name and email of maintainer. An example: "John Doe \". If it isn't a valid email adress **R will complain**. | - | `website` | Website of the author. | - | `license` | License under which the module is released. To have it distributed by us this should be a [free software license](https://en.wikipedia.org/wiki/Free_software_license), aka something like "GPL (>= 2)". | - | `requiresData` | Optional: Whether the analyses and/or module require a dataset or not. | - | `preloadData` | Optional: Whether the analyses can handle getting the dataset as an argument to the R-function. | - - In the future most of this info will be taken straight from [DESCRIPTION](#packageMetadata). - -#### Description Menu -A very important part of [Description.qml](#Description.qml) is the menu specification, as this makes it possible for a user of your module to actually run your analyses. You specify the analyses your module offers, what their titles are, which [options form](#qml) they use and which R-functions should be called to run them. Furthermore you can add separators between groups of analyses and you can add headers with icons inside the menu to make it clearer what category each group of analyses embodies. +```mermaid +graph LR +Description.qml -- points to --> qmls & icons & help +qmls["qml files"] -- create submenu(s) for --> Analysis +R["R functions"] -- imported via --> NAMESPACE -- implement --> Analysis +Analysis & icons & help -- create --> Menu["Graphical menu"] +``` -This menu is specified by a succession of `GroupTitle`, `Separator` and `Analysis` QML objects. +### `Description.qml` +`Description.qml` is the main configuration file for a JASP Module. It will coordinate all the moving parts in order to create the graphical menu we are aiming for. -##### Analysis -The most important one and you should always have at least one of these, because otherwise your module doesn't do *anything*. -It represents, surprise surprise, one of your analyses and has the following fields: - - | fieldname | description | - |------------|-------------| - | `title` | Name of the analysis and, if `menu` is missing, the text shown in the ribbonbutton-menu. | - | `func` | Name of the main R function of an analysis, this should be part of your R-code. | - | `qml` | Optional: Filename of the qml file associated with an analysis, it must be located in the [qml folder](#qml). If it isn't filled `func + ".qml"` is used. | - | `menu` | Optional: Text shown in the menu that opens when the ribbonbutton is clicked. If it isn't entered `title` is used. | - | `icon` | Optional: Filename of the icon to show next to `title` in the menu. | - | `requiresData` | Optional: Whether it requires a dataset or not. If not entered the default is taken from Description. | - | `preloadData` | Optional: Whether it can handle getting the dataset as an argument to the R-function. If not entered the default is taken from Description. | - - +It contains a `Description` qml root object where you can add `Package`'s and `Analysis`, `GroupTitle` and `Separator` objects to. -##### GroupTitle -A nice big header for your menu, can have an icon and it will be clearly visible. Useful for breaking up the list in, for instance, "Bayesian" and "Classical". -It has the following fields: +Click below to see an example. In the next lines, we'll dissect it to understand each of its elements. - | fieldname | description | - |------------|-------------| - | `title` | Name of the analysis and, if `menu` is missing, the text shown in the ribbonbutton-menu. | - | `icon` | Optional: Filename of the icon to show next to `title` in the menu, can be used by analyses and headers. | - -##### Separator -A nice line to break your menu even better than a GroupTitle would do. -Has no properties. - -
Example @@ -99,7 +66,7 @@ import JASP.Module 1.0 Description { - title: "Amazing module" + title: "Amazing module" description: "This is a totally amazing module." version: "0.0.1" author: "yourName" @@ -133,7 +100,7 @@ Description GroupTitle { title: "Nederlandse Analyses" - icon: 1"dutchFlag.svg" + icon: "dutchFlag.svg" } Analysis @@ -152,9 +119,62 @@ Description } } ``` -
+You can see more `Description.qml` files in the wild at virtually any of [our modules on GitHub](https://github.com/jasp-stats). + +#### Module Description +So the root object of your `Description.qml` is a `Description` object that has the following properties: + + | property | description | + |----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | `name` | Specifies the name of the module, only necessary if you are not adding your own [DESCRIPTION](#packageMetadata) file. This name should contain only ASCII letters, numbers and dots, have at least two characters and start with a letter and not end in a dot. | + | `title` | The user-friendly name that is shown in the ribbonbar (top of JASP) and the modules-menu (the right-hand-side menu in JASP). | + | `description` | A description of the module that will be shown during install. | + | `icon` | The filename of the icon to show in the ribbonbar. | + | `version` | The current version of your module, encoded as a string. This is a sequence of at least two (and usually three) non-negative integers separated by single ‘.’ or ‘-’ characters. A good example is "1.0.0", a version such as "0.01" or "0.01.0" will be handled as if it were ‘0.1-0’. It is not a decimal number, so for example "0.9" < "0.75" since 9 < 75. | + | `author` | Name of the author. | + | `maintainer` | Name and email of maintainer. An example: "John Doe \". If it isn't a valid email adress **R will complain**. | + | `website` | Website of the author. | + | `license` | License under which the module is released. To have it distributed by us this should be a [free software license](https://en.wikipedia.org/wiki/Free_software_license), aka something like "GPL (>= 2)". | + | `requiresData` | Optional: Whether the analyses and/or module require a dataset or not. | + | `preloadData` | Optional: Whether the analyses can handle getting the dataset as an argument to the R-function. | + +In the future most of this info will be taken straight from R's [DESCRIPTION](#packageMetadata) file. + +#### Submenu(s) specification +A very important part of [Description.qml](#Description.qml) is the menu specification, as this makes it possible for a user of your module to actually run your analyses. You specify the analyses your module offers, what their titles are, which [options form](#qml) they use and which R-functions should be called to run them. Furthermore you can add separators between groups of analyses and you can add headers with icons inside the menu to make it clearer what category each group of analyses embodies. + +This menu is specified by a succession of `GroupTitle`, `Separator` and `Analysis` QML objects. + +##### Analysis +Analyses are the most important element, and you should always have at least one of these. Otherwise your module doesn't do *anything*. It represents, unsurprisingly, one of your analyses. It has the following fields: + + | fieldname | description | + |----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| + | `title` | Name of the analysis and, if `menu` is missing, the text shown in the ribbonbutton-menu. | + | `func` | Name of the main R function of an analysis, this should be part of your R-code. | + | `qml` | Optional: Filename of the qml file associated with an analysis, it must be located in the [qml folder](#qml). If it isn't filled `func + ".qml"` is used. | + | `menu` | Optional: Text shown in the menu that opens when the ribbonbutton is clicked. If it isn't entered `title` is used. | + | `icon` | Optional: Filename of the icon to show next to `title` in the menu. | + | `requiresData` | Optional: Whether it requires a dataset or not. If not entered the default is taken from Description. | + | `preloadData` | Optional: Whether it can handle getting the dataset as an argument to the R-function. If not entered the default is taken from Description. | + + + +##### GroupTitle +A nice big header for your menu, can have an icon and it will be clearly visible. Useful for breaking up the list in, for instance, "Bayesian" and "Classical". +It has the following fields: + + | fieldname | description | + |-----------|----------------------------------------------------------------------------------------------------------| + | `title` | Name of the analysis and, if `menu` is missing, the text shown in the ribbonbutton-menu. | + | `icon` | Optional: Filename of the icon to show next to `title` in the menu, can be used by analyses and headers. | + +##### Separator +A nice line to break your menu even better than a GroupTitle would do. +Has no properties. + ### Upgrades.qml The optional Upgrades.qml file contains any upgrades that must be done on older, saved, versions of your analyses. So this is only of importance after you release a second or later version of your module and it will allow for seamless loading of these older files. For more information on this, see [the manual on Upgrades.qml](jasp-upgrade-qml.md). @@ -180,4 +200,4 @@ So suppose you have an image in `module/help/img/picture.png`, to link to it you Because a JASP Module is also an R package it should contain a [DESCRIPTION](https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#The-DESCRIPTION-file) file and a [NAMESPACE](https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#Package-namespaces) file. JASP uses the Imports field in a DESCRIPTION file to understand which dependencies it needs to install from [CRAN](https://cran.r-project.org/), in fact it lets R figure this out for it. It also installs the module as an actual R-package which means you must specify each of the main-analysis-functions in the NAMESPACE file to make sure JASP can see these functions. -To actually use this shiny new module and work on it see: [development workflow](./jasp-module-workflow.md)). +To actually use this shiny new module and work on it see: [development workflow](./jasp-module-workflow.md)). \ No newline at end of file From bec43edb4cc9645beb0c86ec2f0e33bf24c9c5aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Rodr=C3=ADguez=20S=C3=A1nchez?= Date: Tue, 26 Nov 2024 13:53:19 +0100 Subject: [PATCH 4/7] Use R-centric workflow diagram --- Docs/development/jasp-adding-module.md | 31 ++++++++++++-------------- 1 file changed, 14 insertions(+), 17 deletions(-) diff --git a/Docs/development/jasp-adding-module.md b/Docs/development/jasp-adding-module.md index db8a7ffba6..c52987cd38 100644 --- a/Docs/development/jasp-adding-module.md +++ b/Docs/development/jasp-adding-module.md @@ -11,7 +11,7 @@ In a nutshell, a JASP module provides no more (and no less) than a user-friendly ## Structure -A module folder looks like a standard R package + some special files in the `inst/` folder: +A module folder looks like a standard R package + some [qml](https://doc.qt.io/qt-6/qmlapplications.html) files in the `inst/` folder: ```sh . @@ -43,11 +43,9 @@ A module folder looks like a standard R package + some special files in the `ins The functionality of those files can be graphically summarized as follows: ```mermaid -graph LR -Description.qml -- points to --> qmls & icons & help -qmls["qml files"] -- create submenu(s) for --> Analysis -R["R functions"] -- imported via --> NAMESPACE -- implement --> Analysis -Analysis & icons & help -- create --> Menu["Graphical menu"] +graph TD +R["R functions"] -- imported via --> NAMESPACE -- called by --> qmls["qml files"] -- to create--> Analyses +Analyses & help & icons & aesthetics["other aesthetics"] -- coordinated by --> Description.qml -- to create --> Menu["Graphical menu"] ``` ### `Description.qml` @@ -173,22 +171,18 @@ It has the following fields: ##### Separator A nice line to break your menu even better than a GroupTitle would do. -Has no properties. +It has no properties. - -### Upgrades.qml -The optional Upgrades.qml file contains any upgrades that must be done on older, saved, versions of your analyses. So this is only of importance after you release a second or later version of your module and it will allow for seamless loading of these older files. For more information on this, see [the manual on Upgrades.qml](jasp-upgrade-qml.md). - -#### icons +### `icons/` The icons folder is where you should place all icons you want to show, aka one for the ribbonbar that opens the [menu](#description-menu) and possibly more for use with headers and/or analyses. Preferably this is an [svg](https://nl.wikipedia.org/wiki/Scalable_Vector_Graphics) because this scales very gracefully. You could also use [png](https://nl.wikipedia.org/wiki/Portable_network_graphics) or [jpg](https://nl.wikipedia.org/wiki/JPEG) but since these do not scale very well they could make your icon look pretty bad on some computers. If you specify an icon somewhere in [Description.qml](#Description.qml) you should include the extension but not the path. As an example, the file `ModuleName/inst/icons/myGorgeousIcon.svg` would be specified only as `myGorgeousIcon.svg` and JASP will make sure to retrieve it from this directory. -#### qml +### `qml/` The qml folder is where you place your [qml](https://en.wikipedia.org/wiki/QML) files. In practice you probably want to have at least a single qml file per analysis. You can then specify which file to use per analysis in the [menu](#description-menu), the names should include the extension `.qml` as well. A detailed guide on creating QML files can be found [here](jasp-qml-guide.md). As an aside, if you want to go for creating you own reusable qml components you can store them here as well. This is described in more detail [here](jasp-qml-guide.md#advanced-usage). -#### R +### `R/` In the R folder you should place your R file(s). You could add all your analyses into one file, or store separately them into separate files (recommended). You might event want to separate the reusable parts of your code further into their own file(s). The important part is that the name(s) of your main function(s) match the name(s) you specified under `function` in the analysis-entries of the [menu](#description-menu). A detailed guide on creating R analyses can be found [here](r-analyses-guide.md). -#### help +### `help/` The help folder is where you place the documentation for your module. You should name the helpfile for each analysis with the exact same functionname as your analysis has. **Only all characters should be lowercase**. - **Image**:To be able to refer to another helpfile or an image in your module's helpfile or in the `info` field of the = options in QML you can use a special string. This string is `%HELP_FOLDER%` and when loaded it will be replaced with the path to the `help`-folder of your module. @@ -196,8 +190,11 @@ So suppose you have an image in `module/help/img/picture.png`, to link to it you - **Math**:If you want to add math expressions to help documentation, use TeX/LaTeX code into `\\\\(...\\\\)` or `$...$` for inline style, and use `\\\\[...\\\\]` or `$$...$$` for block style math expressions, note that you may need to escape characters such `$\\alpha+\\beta$` to get $\alpha+\beta$. - **R Code**:Suppose want to display example R code block or highlighting in the help documentation, you can use ` ```r ``` ` with your R code. -#### Package Metadata +### Package Metadata Because a JASP Module is also an R package it should contain a [DESCRIPTION](https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#The-DESCRIPTION-file) file and a [NAMESPACE](https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#Package-namespaces) file. JASP uses the Imports field in a DESCRIPTION file to understand which dependencies it needs to install from [CRAN](https://cran.r-project.org/), in fact it lets R figure this out for it. It also installs the module as an actual R-package which means you must specify each of the main-analysis-functions in the NAMESPACE file to make sure JASP can see these functions. -To actually use this shiny new module and work on it see: [development workflow](./jasp-module-workflow.md)). \ No newline at end of file +To actually use this shiny new module and work on it see: [development workflow](./jasp-module-workflow.md)). + +### `Upgrades.qml` +The optional Upgrades.qml file contains any upgrades that must be done on older, saved, versions of your analyses. So this is only of importance after you release a second or later version of your module and it will allow for seamless loading of these older files. For more information on this, see [the manual on Upgrades.qml](jasp-upgrade-qml.md). \ No newline at end of file From fcfc9322798aca9b98ff2e721fac5123c7d2c4ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Rodr=C3=ADguez=20S=C3=A1nchez?= Date: Tue, 26 Nov 2024 14:29:14 +0100 Subject: [PATCH 5/7] Reorder and clarify folder structure --- Docs/development/jasp-adding-module.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/Docs/development/jasp-adding-module.md b/Docs/development/jasp-adding-module.md index c52987cd38..c7b72b240e 100644 --- a/Docs/development/jasp-adding-module.md +++ b/Docs/development/jasp-adding-module.md @@ -34,10 +34,14 @@ A module folder looks like a standard R package + some [qml](https://doc.qt.io/q └──inst ├── Description.qml ├── Upgrades.qml # Optional + ├── qml + │ └── analysis_1.qml + │ └── ... ├── help - ├── icons - └── qml - └── examples.qml + │ └── ... + └── icons + ├── .svg + └── ... ``` The functionality of those files can be graphically summarized as follows: @@ -173,15 +177,9 @@ It has the following fields: A nice line to break your menu even better than a GroupTitle would do. It has no properties. -### `icons/` -The icons folder is where you should place all icons you want to show, aka one for the ribbonbar that opens the [menu](#description-menu) and possibly more for use with headers and/or analyses. Preferably this is an [svg](https://nl.wikipedia.org/wiki/Scalable_Vector_Graphics) because this scales very gracefully. You could also use [png](https://nl.wikipedia.org/wiki/Portable_network_graphics) or [jpg](https://nl.wikipedia.org/wiki/JPEG) but since these do not scale very well they could make your icon look pretty bad on some computers. If you specify an icon somewhere in [Description.qml](#Description.qml) you should include the extension but not the path. As an example, the file `ModuleName/inst/icons/myGorgeousIcon.svg` would be specified only as `myGorgeousIcon.svg` and JASP will make sure to retrieve it from this directory. - ### `qml/` The qml folder is where you place your [qml](https://en.wikipedia.org/wiki/QML) files. In practice you probably want to have at least a single qml file per analysis. You can then specify which file to use per analysis in the [menu](#description-menu), the names should include the extension `.qml` as well. A detailed guide on creating QML files can be found [here](jasp-qml-guide.md). As an aside, if you want to go for creating you own reusable qml components you can store them here as well. This is described in more detail [here](jasp-qml-guide.md#advanced-usage). -### `R/` -In the R folder you should place your R file(s). You could add all your analyses into one file, or store separately them into separate files (recommended). You might event want to separate the reusable parts of your code further into their own file(s). The important part is that the name(s) of your main function(s) match the name(s) you specified under `function` in the analysis-entries of the [menu](#description-menu). A detailed guide on creating R analyses can be found [here](r-analyses-guide.md). - ### `help/` The help folder is where you place the documentation for your module. You should name the helpfile for each analysis with the exact same functionname as your analysis has. **Only all characters should be lowercase**. - **Image**:To be able to refer to another helpfile or an image in your module's helpfile or in the `info` field of the = options in QML you can use a special string. @@ -190,6 +188,12 @@ So suppose you have an image in `module/help/img/picture.png`, to link to it you - **Math**:If you want to add math expressions to help documentation, use TeX/LaTeX code into `\\\\(...\\\\)` or `$...$` for inline style, and use `\\\\[...\\\\]` or `$$...$$` for block style math expressions, note that you may need to escape characters such `$\\alpha+\\beta$` to get $\alpha+\beta$. - **R Code**:Suppose want to display example R code block or highlighting in the help documentation, you can use ` ```r ``` ` with your R code. +### `icons/` +The icons folder is where you should place all icons you want to show, aka one for the ribbonbar that opens the [menu](#description-menu) and possibly more for use with headers and/or analyses. Preferably this is an [svg](https://nl.wikipedia.org/wiki/Scalable_Vector_Graphics) because this scales very gracefully. You could also use [png](https://nl.wikipedia.org/wiki/Portable_network_graphics) or [jpg](https://nl.wikipedia.org/wiki/JPEG) but since these do not scale very well they could make your icon look pretty bad on some computers. If you specify an icon somewhere in [Description.qml](#Description.qml) you should include the extension but not the path. As an example, the file `ModuleName/inst/icons/myGorgeousIcon.svg` would be specified only as `myGorgeousIcon.svg` and JASP will make sure to retrieve it from this directory. + +### `R/` +In the R folder you should place your R file(s). You could add all your analyses into one file, or store separately them into separate files (recommended). You might event want to separate the reusable parts of your code further into their own file(s). The important part is that the name(s) of your main function(s) match the name(s) you specified under `function` in the analysis-entries of the [menu](#description-menu). A detailed guide on creating R analyses can be found [here](r-analyses-guide.md). + ### Package Metadata Because a JASP Module is also an R package it should contain a [DESCRIPTION](https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#The-DESCRIPTION-file) file and a [NAMESPACE](https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#Package-namespaces) file. JASP uses the Imports field in a DESCRIPTION file to understand which dependencies it needs to install from [CRAN](https://cran.r-project.org/), in fact it lets R figure this out for it. It also installs the module as an actual R-package which means you must specify each of the main-analysis-functions in the NAMESPACE file to make sure JASP can see these functions. From a0c4cf43375a4d12865f1d7f021eae7b7b210a07 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Rodr=C3=ADguez=20S=C3=A1nchez?= Date: Tue, 26 Nov 2024 14:45:02 +0100 Subject: [PATCH 6/7] Match title with name --- Docs/development/jasp-adding-module.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Docs/development/jasp-adding-module.md b/Docs/development/jasp-adding-module.md index c7b72b240e..595e6ee245 100644 --- a/Docs/development/jasp-adding-module.md +++ b/Docs/development/jasp-adding-module.md @@ -1,16 +1,16 @@ -Structure of a JASP module +Adding a module to JASP ================================ -The basic idea of loadable modules in JASP is that they follow the general structure of an R package. From now on, we'll assume the reader is familiar with R packaging. If not, check out these excellent materials: Software Carpentries' [R packaging course](https://carpentries-incubator.github.io/lesson-R-packaging/index.html) and, if you want to go deeper, the [R packages book](https://r-pkgs.org/). +## Structure of a JASP module + +Modules in JASP follow the general structure of an R package. From now on, we'll assume the reader is familiar with R packaging. If not, check out these excellent materials: Software Carpentries' [R packaging course](https://carpentries-incubator.github.io/lesson-R-packaging/index.html) and, if you want to go deeper, the [R packages book](https://r-pkgs.org/). In a nutshell, a JASP module provides no more (and no less) than a user-friendly graphical interface for an underlying R package. See a graphical summary below: ![](./img/puzzle.svg) - - -## Structure +## Detailed structure A module folder looks like a standard R package + some [qml](https://doc.qt.io/qt-6/qmlapplications.html) files in the `inst/` folder: ```sh From 66d1c6bf25b658ee7844c1f6977bcf5549ddf78b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Rodr=C3=ADguez=20S=C3=A1nchez?= Date: Tue, 26 Nov 2024 14:48:28 +0100 Subject: [PATCH 7/7] Explicitly mention qml as an external tool --- Docs/development/jasp-adding-module.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Docs/development/jasp-adding-module.md b/Docs/development/jasp-adding-module.md index 595e6ee245..c60b95f028 100644 --- a/Docs/development/jasp-adding-module.md +++ b/Docs/development/jasp-adding-module.md @@ -6,6 +6,8 @@ Adding a module to JASP Modules in JASP follow the general structure of an R package. From now on, we'll assume the reader is familiar with R packaging. If not, check out these excellent materials: Software Carpentries' [R packaging course](https://carpentries-incubator.github.io/lesson-R-packaging/index.html) and, if you want to go deeper, the [R packages book](https://r-pkgs.org/). +On top of it, we provide a graphical user interface. We'll use Qt's `qml` files for this. `qml` files allows us to describe a user interface in terms of their visual components using plain text. More information about the `qml` format can be found [here](https://doc.qt.io/qt-6/qmlapplications.html). + In a nutshell, a JASP module provides no more (and no less) than a user-friendly graphical interface for an underlying R package. See a graphical summary below: ![](./img/puzzle.svg)