User Input

## Introduction

Sometimes you'll want to accept input from people who use your generator - perhaps their character's name, their age, or something like that. Let's go through some examples of different input types that we might want in our generator.

## Examples

### Text and Number Input

First up, is a simple text input form. Let's say we wanted to make it so whenever they type into that input, it puts the text that they've typed into a variable called `[name]`. We can then use this `[name]` variable wherever we want in our code. To do this, you simply need to paste the following code in the bottom-right panel of the editor (the HTML panel):

```
 <input oninput="name = this.value" placeholder="Please enter your name..."/>

```

Now whenever they type some text into that input form, the text will immediately be put into the `[name]` variable. All the magic is happening in this part of the above snippet: `oninput="name = this.value"`. That just means "Whenever the value in the input form changes, set the `[name]` variable to the text that's in the input form". If you don't fully understand how it works, that's fine - you can copy and paste this without really needing to know what's happening there.

You can change `name` to `age` or to anything else you desire so long as it doesn't have any spaces. I recommend using capital letters like this `myVariable` or `MyVariable` to help you separate words and make them more readable, or you can use underscores like this: `my_variable`. Here's a minimal example that uses the above code. If you'd like it to update as the user types (so they don't have to click a "generate" button), have a look at this auto-updating input example).

Notice in those examples that I've written `name = Default Name` in the Perchance code panel (the main editor on the left-hand side). We need to add a default name otherwise we'll get an error because we'd be using a variable before it actually exists (it would only come into existence once they start typing for the first time).

> **Important note:** If you're taking a **number** as user input (such as an age, or height, etc.), you should write this instead:
>
>
>
> ```
>  <input oninput="num = Number(this.value)" placeholder="Please type a number..."/>
>
> ```
>
> If you don't do that, it may still work, but certain advanced features (like using the variable in "dynamic odds" statements) will behave weirdly because the engine treats the input as text rather than as a number. The `Number(...)` function converts text to a number.
>
>

If you need a larger text box input, have a look at this minimal textarea example, and this more complex example. If you'd like users of your generator to be able to input **their own lists**, have a look at this example.

### Dropdown Lists

Next up is a drop-down list. To create a drop-down list like this, you'll need to paste the following code in your HTML panel:

```
 <select oninput="country = this.value">
 	<option value="Mexico">Mexico</option>
 	<option value="Germany">Germany</option>
 	<option value="Britain">Britain</option>
 </select>

```

Now whenever they select a different item in that drop-down menu, the `[country]` variable will be set to whatever is in the `value` attribute of the `<option>...</option>` that they selected. So if they click an option like this: `<option value="veg">Vegetables</option>`, then the variable would be set to `"veg"`. The "Vegetables" part is just what gets actually displayed in the drop-down menu.

If we were making a name generator where we let the user choose the nationality of the name to be generated (Mexican, German, or British), then our Perchance code might look something like this:

```
 output
 	[BritishName] ^[country == "Britain"]
 	[MexicanName] ^[country == "Mexico"]
 	[GermanName] ^[country == "Germany"]

```

If you're confused about what's going on there, read the "Dynamic Odds" section that's on this page (scroll up). Here's a drop-down list example using the above code. Just as in the previous text-input example, if we change `country = this.value` to `country = this.value, update()`, then it will re-randomize the output automatically when they change their drop-down selection (so they don't need to click randomize after changing the drop-down). Here's an example of multiple drop-down lists. And here's an example of a drop-down list where its items are dynamically generated from one of your Perchance lists (explained here).

### Checkboxes

Another common input type is a checkbox. Users can toggle this on and off by clicking it, and you can use its state (checked or unchecked) to change the odds of certain items in your lists (or, ore commonly, to completely disable an item if a checkbox isn't checked). To add a checkbox to your generator, just add the following code to your HTML panel:

```
 <input type="checkbox" id="thingy"/>

```

In this example we've set the `id` of the checkbox to `thingy`, but you can call it whatever you want. You use the `id` to determine whether it's checked or not, like this: `[thing.checked]`. That will evaluate to `true` if it is checked, or `false` if it's not. So let's say you have these in your HTML panel:

```
 <input type="checkbox" id="animalBox"/>
 <input type="checkbox" id="plantBox"/>

```

and this in your Perchance code panel:

```
 animal = {import:animal}
 plant = {import:plant-species}

 output
   [animal] ^[animalBox.checked]
   [plant]  ^[plantBox.checked]

```

And now the `[output]` list will only output an animal if the `animalBox` checkbox is checked, and it will only output a plant if the `plantBox` checkbox is checked. Here's an example generator based on the above code. Note that the checkbox `id`s must not have the same name as any of your lists or variables, so the above example wouldn't work if we used `id="animal"`. If you want your checkbox to be checked by default, just add the `checked` attribute to your checkbox HTML like so:

```
 <input type="checkbox" id="animalBox" checked/>

```

If you want the generator to re-randomize automatically when they click the checkbox, then add then you can add the `oninput` attribute like this:

```
 <input type="checkbox" id="animalBox" oninput="update()"/>

```

Here's another simple check-box example.

### Other Types

There are lots of other types of inputs in HTML, for example you can make a color picker, a date picker, a sliding range, and more. Learning some basic HTML and JavaScript will help you if you want to make generators that rely heavily on inputs. It's hard work (especially JavaScript), but it's worth it!

NoteNeed to document the other types here in the Wiki to expand the tutorial!
Types Needed Documentation:

* button
* datetime-local
* email
* file
* image
* month
* number
* password
* radio
* time