From b165bb2668ea047e6c77751c7bb622c29f0a0ab2 Mon Sep 17 00:00:00 2001 From: Etesam Date: Mon, 8 Aug 2022 11:02:18 -0400 Subject: [PATCH] Creates a readme for simple_static_task (#882) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 📝 Created a readme for simple_static_task * ⚡️ Skips cypress action when only .md files changed * 📝 Added path-ignore to pull_request and main * ✅ Testing paths-ignore rule in github action * 📝 Made small clarification to html task readme --- .../workflows/cypress-end-to-end-tests.yml | 5 +- examples/simple_static_task/README.md | 47 +++++++++++++++++++ examples/static_react_task/README.md | 4 +- .../blueprints/static_html_task/README.md | 33 ++++++++++++- 4 files changed, 85 insertions(+), 4 deletions(-) create mode 100644 examples/simple_static_task/README.md diff --git a/.github/workflows/cypress-end-to-end-tests.yml b/.github/workflows/cypress-end-to-end-tests.yml index b4b21f1ab..383d0956d 100644 --- a/.github/workflows/cypress-end-to-end-tests.yml +++ b/.github/workflows/cypress-end-to-end-tests.yml @@ -1,9 +1,12 @@ name: cypress-end-to-end-tests on: pull_request: + paths-ignore: + - "**.md" push: branches: [main] - + paths-ignore: + - "**.md" jobs: # This job is made to setup path filtering, learn more about it here: https://github.com/facebookresearch/Mephisto/pull/857 changes: diff --git a/examples/simple_static_task/README.md b/examples/simple_static_task/README.md new file mode 100644 index 000000000..85c579aa9 --- /dev/null +++ b/examples/simple_static_task/README.md @@ -0,0 +1,47 @@ +# Simple Static Task +This example script is to demonstrate how to launch a simple task using a html file. The "static" nature of this task means that all of the content required for a worker to complete the task must be set before the task is launched, and must be able to be sent to the app upon initialization. + +This specific example can be run with: +```console +python static_test_script.py +``` + +and can additionally be launched with an onboarding step by specifying an onboarding qualification: + +```console +python static_run_with_onboarding.py +``` + +## Submit button customization +### Hide the submit button +Writing the markup below in `demo_task.html` will allow you to hide the submit button. + +```html + +``` + +You can get window properties as such: +```html + +``` + + +## Testing +To run tests locally you should first launch the task as follows: + +```bash +python static_test_script.py +``` +This will run the task. + +Then go into the `mephisto/abstractions/blueprints/static_html_task/source` and run +```console +npm run test +``` +to open cypress. + +Select the Chrome browser and click on the one spec that shows up to run the tests. diff --git a/examples/static_react_task/README.md b/examples/static_react_task/README.md index cca27d259..561257b96 100644 --- a/examples/static_react_task/README.md +++ b/examples/static_react_task/README.md @@ -130,6 +130,6 @@ python run_task.py mephisto.task.post_install_script=link_mephisto_task.sh mephi ``` This will run the task and make sure to link the `mephisto-task` package with the local one. -Also make sure that the baseUrl property in the cypress.config.js matches one of the urls that are outputted from the run_task.py script. +Then you can run cypress by going into the webapp directory and running `npm run test`. This should open the cypress app. -Then you can run cypress by going into the webapp directory and running `npm run test`. This should open the cypress app. It should be self-explanatory from this point on. \ No newline at end of file +Click the Chrome browser and select a spec to run some tests. \ No newline at end of file diff --git a/mephisto/abstractions/blueprints/static_html_task/README.md b/mephisto/abstractions/blueprints/static_html_task/README.md index 795c5739a..05a6fd6ce 100644 --- a/mephisto/abstractions/blueprints/static_html_task/README.md +++ b/mephisto/abstractions/blueprints/static_html_task/README.md @@ -1,4 +1,5 @@ # `StaticHTMLBlueprint` + ## Overview The `StaticHTMLBlueprint` exists to create a simple transition stand-in to allow users of other platforms (which generally push for customization with HTML) to begin using Mephisto with minimal changes. This generally exists in the form of specifying a templated HTML file and providing assignment data that fills the templates. @@ -9,8 +10,11 @@ An example usage case is available [here](https://github.com/facebookresearch/Me ## Implementation Details At a high level, this is a deeper implementation of the abstract `StaticArchitect`, which contains all of the logic for deploying arbitrary tasks where the worker is given some content, and we ask for one response, as a complete `Unit`. This module adds the logic to ensure that the frontend where the worker is given content is able to render arbitrary HTML. + ### `app.jsx` -The `app.jsx` file contains most of the logic to ensure we can render HTML, including being able to attach and execute the arbitrary scripts that are included or linked in the given HTML file. It creates a react application using the `mephisto-task` package, and creates an empty form with a submit button. It then populates the inner form using two primary methods: +The `app.jsx` file contains most of the logic to ensure we can render HTML, including being able to attach and execute the arbitrary scripts that are included or linked in the given HTML file. It creates a react application using the `mephisto-task` package, and creates an empty form with a submit button. + +It then populates the inner form using two primary methods: - `handleUpdatingRemainingScripts`: This method walks through the list of scripts that are given in the attached HTML, either loading the external script and putting it into the head, or directly evaluating the content of local scripts. As the page has already loaded by the time we are loading in the remaining scripts, this all must be injected in an asynchronous manner. _Ultimately_ this isn't incredibly safe if you don't trust the attached scripts. - `interpolateHtml`: This method injects the values for the specific task into their template variable slots. These template variables are specified in the `InitializationData` for an assignment, and populate fields as noted in the **Template Variables** section below. @@ -18,11 +22,38 @@ Upon submit, the data in the form (as marked by the `name` fields of any inputs) #### Template Variables You can provide template variables when running your task, generally in the form of template variables that are given names. When you specify these (either via `.csv` or directly providing a parsed array of dicts for this data), any named variable `my_special_variable` will be filled into the frontend in all locations containing `${my_special_variable}`. + #### Mephisto-specific Template Variables As of now, we also make available the following variables to the HTML via templating: - `${mephisto_agent_id}`: The agent ID that Mephisto has associated with the current worker and task. - `${provider_worker_id}`: The worker id that the provider uses locally to identify the worker. +#### `useMephistoGlobalConfig` +This hook allows for a state to be updated when an event is consumed. An event is emitted for consumption whenever a window variable is set in `demo_task.html` using: + +```html + +``` + +**Example of the hook in use** +```jsx +const [isSubmitButtonHidden, setIsSubmitButtonHidden] = + useMephistoGlobalConfig( + "HIDE_SUBMIT_BUTTON", + false, + (valueThatStateWillBeUpdatedTo) => typeof valueThatStateWillBeUpdatedTo === "boolean" + ); +``` +This sets the isSubmitButtonHidden state to be equal to whatever it was set to in the html when the HIDE_SUBMIT_BUTTON config name is consumed. + +In this case: +* The first argument is the name of the event you are consuming. +* The second argument(optional) is the default value for `isSubmitButtonHidden` +* The third argument(optional) is a validation function. + * When defined, the validation function has to return true for the state to update to `valueThatStateWillBeUpdatedTo` + ### `StaticHTMLBlueprint` The `Blueprint` here extends on the abstract `StaticBlueprint`, adding HTML-specific requirements to outline the task that ends up visualized. The added arguments are as follows: - `task_source`: The path to the (templated) HTML that should be displayed for the task.