Metadata-Version: 2.1
Name: nbforms
Version: 0.2.1
Summary: Jupyter Notebook forms using ipywidgets
Home-page: https://github.com/chrispyles/nbforms
Author: Chris Pyles
Author-email: cpyles@berkeley.edu
License: BSD-3-Clause
Description: # nbforms
        
        [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/chrispyles/nbforms/master?filepath=demo%2Fdemo.ipynb)
        
        nbforms is a Python package designed to allow forms to be submitted by users such that the data they submit is immediately available for use in the notebook by the entire group. This is accomplished using ipywidgets and a Heroku-deployable Sinatra webapp, [nbforms-server](https://github.com/chrispyles/nbforms-server).
        
        ## Installation
        
        To install the Python package, use pip:
        
        ```
        pip install nbforms
        ```
        
        ## Deployment
        
        ### Setup: Server
        
        Before using nbforms in a notebook, you must deploy a webapp to Heroku which will collect and organize the responses. If you plan to have multiple notebooks, you only need one server, as you can provide a notebook identifier in the config files that will distinguish responses.
        
        To deploy the webapp, click the deploy button in the [nbforms-server README](https://github.com/chrispyles/nbforms-server).
        
        ### Setup: Config File
        
        nbforms requires a JSON-formatted config file to set up the `Notebook` class. The default path that `Notebook` checks is `./nbforms_config.json`, although you can pass a custom path to the `Notebook` constructor. The structure of the config file is very specific; it contains the information that the notebook needs to create widgets and send requests. The structure of this file is:
        
        ```python
        {
            "server_url": "",             # URL to your Heroku app
        
            "notebook": "",               # an ID to collect responses
        
            "questions": [{               # questions to ask, a list of dicts
        
              "identifier": "",           # a question identifer, should be unique within
                                          # this notebook
              "type": "",                 # question type; can be one of:
                                          #   multiplechoice, checkbox, text, paragraph
        
              "question": "",             # the question text
        
              "options": [                # options from which to choose if type is 
                ...                       # multiplechoice or checkbox
              ],
              "placeholder": ""           # placeholder for textbox if type is text or
                                          # paragraph
            }, 
            ...                           # more question dictionaries
          ]
        }
        ```
        
        The `server_url` key should be the URL to your Heroku-deployed nbforms-server, e.g. `https://my-nbforms-server.herokuapp.com`. The `notebook` key should be some string or number to identify the notebook that you're deploying. This is used to keep the notebook responses distinguished on the server. Finally, the `questions` key should be a list of dictionaries that define the information for your questions.
        
        Questions can have one of four types: `multiplechoice`, `checkbox`, `text`, or `paragraph`. The `type` key in the question is used to create the widget. If you have a `multiplechoice` or `checkbox`, you must provide a list of options as the `options` key. For `text` and `paragraph` responses, you can provide an optional `placeholder` key which will replace the default placeholder.
        
        There is a sample config file at [`demo/nbforms_config.json`](demo/nbforms_config.json). Each nbforms-server comes with a page that will generate a config file for you. The config generator for the demo server can be found [here](https://nbforms-demo-server.herokuapp.com/config_generator.html).
        
        ### In-Notebook: Import and Instantiate
        
        To use the nbforms, you must first import it and create a `Notebook` instance. This will load the config file (defaulting to look at `./nbforms_config.json`) and ask the user to input a username and a password. If the username already exists on the server, the password will be checked and an API key will be generated, to be stored in the `Notebook` class. If it does not exist, a new user will be created, and an API key generated. If the user _does_ exist but an incorrect password is provided, the cell will error.
        
        ```python
        import nbforms
        form = nbforms.Notebook()
        ```
        
        ### In-Notebook: Collecting Responses
        
        To collect the responses for a question, insert a cell that calls the `Notebook.ask` function on the **identifier** of the question. For example, if I had a question `q1`, I would call
        
        ```python
        form.ask("q1")
        ```
        
        This will output the widget and a "Submit" button that, when clicked, will send an HTTP POST request to your nbforms server with the student's username, API key, notebook ID, question identifier, and response to be stored on the server.
        
        `Notebook.ask` can accept multiple questions; for example, `form.ask("q1", "q3")` would display a widget with `q1` and `q3` as its tabs. Passing no arguments to `Notebook.ask` will display all of the questions.
        
        ### In-Notebook: Retrieving Data
        
        nbforms allows you to get your data from the server and collect it into either a datascience `Table` or a pandas `DataFrame`. To retrieve the responses from the server, use `Notebook.to_table` or `Notebook.to_df`; the optional `user_hashes` argument (default `False`) indicates whether or not to include a column with the hashes username.
        
        ```python
        # datascience Table
        form.to_table("q1", "q2", ...)
        
        # pandas DataFrame
        form.to_df("q1", "q3", ..., user_hashes=True)
        ```
        
        ### Database Maintenance
        
        There is not much database maintance that can be done, but you can optionally delete all responses on the server by running `rake clear` on your Heroku app.
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
