Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Immediate documentation fix for people confused by .ts plugin setup #3439

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/developers/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,9 @@ If you are developing a new plugin or extension there are two different reposito

The main `jspsych` repository is open to new plugins and extensions that are likely to be widely used. We require that contributions to main repository are well documented and tested before they are merged. Contributions to the main repository must use TypeScript. We limit contributions to this repository because once a plugin or extension is in the main codebase we are generally committed to providing updates as we develop new versions of jsPsych. Each new plugin and extension potentially increases the amount of development work that we will need to do in the future, so we are somewhat selective about what we will merge. If you have an idea that you'd like to discuss please [open a discussion thread](https://github.com/jspsych/jsPsych/discussions/new) and we'd love to chat about it!

The `jspsych-contrib` repository is open to any contributions that are complete and working code. There are some minimal guidelines in place about basic documentation that should be provided. Contributors can choose whether to develop their plugin or extension using our [TypeScript template](https://github.com/jspsych/jspsych-contrib/tree/main/packages/plugin-template-ts) or using our [JavaScript template](https://github.com/jspsych/jspsych-contrib/tree/main/packages/plugin-template). Contributions to `jspsych-contrib` are not evaluated for general usefulness in the same way that contributions to the main repository are. We also periodically consider whether to move contributions into the main repository from `jspsych-contrib` based on their popularity and completeness (documentation and testing).
The `jspsych-contrib` repository is open to any contributions that are complete and working code. There are some minimal guidelines in place about basic documentation that should be provided. Contributors can choose whether to develop their plugin or extension using our [TypeScript template](https://github.com/jspsych/jspsych-contrib/blob/main/templates/plugin-template-ts/src/index.ts) or using our [JavaScript template](https://github.com/jspsych/jspsych-contrib/blob/main/templates/plugin-template-js/src/index.js). Check our [plugin developer documentation](https://www.jspsych.org/latest/developers/plugin-development/) for additional guidance.

Contributions to `jspsych-contrib` are not evaluated for general usefulness in the same way that contributions to the main repository are. We also periodically consider whether to move contributions into the main repository from `jspsych-contrib` based on their popularity and completeness (documentation and testing).



Expand Down
10 changes: 4 additions & 6 deletions docs/developers/plugin-development.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,11 @@ As of version 7.0, plugins are [JavaScript Classes](https://developer.mozilla.or
* [A `trial()` method](#trial) that accepts an `HTMLElement` as its first argument and an `object` of trial parameters as its second argument. There is an optional third argument to [handle the `on_load` event](#asynchronous-loading) in certain cirumstances. The `trial()` method should *either* invoke `jsPsych.finishTrial()` or should be an `async` function that returns a data object to [end the trial and save data](#save-data).
* [A static `info` property](#static-info) on the class that contains an object describing the plugin's parameters, data generated, and version.

### Templates
## Plugin templates

Templates for plugins are available in the [jspsych-contrib](https://github.com/jspsych/jspsych-contrib) repository. Plugins can be written in either plain [JavaScript](https://github.com/jspsych/jspsych-contrib/blob/main/templates/plugin-template-js/src/index.js) or in [TypeScript](https://github.com/jspsych/jspsych-contrib/blob/main/templates/plugin-template-ts/src/index.ts).

Plugins can be written in either plain JavaScript or in TypeScript. Template files for both [JavaScript](https://github.com/jspsych/jspsych-contrib/blob/main/templates/plugin-template-js/src/index.js) and [TypeScript](https://github.com/jspsych/jspsych-contrib/blob/main/templates/plugin-template-ts/src/index.ts) are available in the [jspsych-contrib repository](https://github.com/jspsych/jspsych-contrib/).
Additionally, `jspsych-contrib` offers guidance for either approach in its [`README`](https://github.com/jspsych/jspsych-contrib) file. It is likewise (for now) the exclusive home for CLI tools like `npm run new`, which we've built to help developers get started. Those relying on Typescript can then use the `npm run build` command to compile their `index.ts` code into Javascript files. Meanwhile, those templating directly in Javascript can run their trial code using the `trial()` method, as detailed below.

## Plugin components

Expand Down Expand Up @@ -328,8 +330,4 @@ If you are developing a plugin with the aim of including it in the main jsPsych

We also recommend that you make your plugin *as general as possible*. Consider using parameters to give the user of the plugin as many options for customization as possible. For example, if you have any text that displays in the plugin including things like button labels, implement the text as a parameter. This allows users running experiments in other languages to replace text values as needed.

## Plugin templates

Templates for plugins are available in the [jspsych-contrib](https://github.com/jspsych/jspsych-contrib) repository. There is a command-line tool for generating a new plugin from these templates in that repository. See the README file in the jspsych-contrib repository for more information.


Loading