Locker-plugin

Link to Pluginhttps://perchance.org/locker-plugin

## Basic Overview

This plugin is a more powerful version of the lockable-list plugin. It allows you to create a "locker" which holds a value if the user clicks a lock icon. It's slightly more complicated than the lockable-list plugin, so I'll go through a few simple examples and explain it slowly.

## Importing and Usage

### Using the Locker

First, you'll just need to import the plugin by putting this code in your Perchance code panel:

```
locker = {import:locker-plugin}

```

And here's a simple example of how to use it (explained below):

```
output
	The [locker("a1", animal.selectOne)] [locker("a1_button")] has befriended the [locker("a2", animal.selectOne)] [locker("a2_button")].

animal
	frog
	mouse
	rabbit
	cow
	...

```

and that would output this: The mouse 🔓 has befriended the deer 🔓.

Here's what's happening there: When we write `[locker("a1", animal.selectOne)]`, we're creating a locker called `a1` and putting a value inside it: `animal.selectOne`.

If the locker is currently **unlocked**, then the statement `[locker("a1", animal.selectOne)]` will simply output the value we put in: `animal.selectOne`.

**But** if the locker is currently **locked**, then it "rejects" our value and outputs the value that has been locked inside it. So if the `a1` locker is locked on "frog", then `[locker("a1", animal.selectOne)]` will output "frog" instead of `animal.selectOne`.

Here's another example:

```
output
	Pair 1: [locker("p1", letterPair.evaluateItem)] [locker("p1_button")]<br>Pair 2: [locker("p2", letterPair.evaluateItem)] [locker("p2_button")]

letterPair
	{A-Z}{A-Z}

```

Pair 1: RJ 🔓

Pair 2: QG 🔓

Notice that this plugin is unlike the lockable-list plugin in that rather than passing a list name, we need to input the actual, final value that we want to store in the locker.

So in this case we use `.evaluateItem` (explained in the tutorial) to fully get a fully-evaluated letter pair (i.e. just plain text - no curly brackets). If we'd written `letterPair.selectOne`, then we'd be storing the unevaluated `{A-Z}{A-Z}` item in the locker.

That's perfectly allowable, but it wouldn't give us what we want - we want the user to be able to lock onto a specific letter pair - not on that pair of curly blocks (which would result in a new letter pair every time you click randomize).

### Storing Value in the Locker

If you want to get the current value that is in a particular locker **without** attempting to replace it with another value, then you can do that like this:

```
output
	The current value that's inside the "hello" locker is: [locker("hello")].

```

And you can of course assign it to a variable so you can use it later:

```
output
	[h = locker("hello")] [h] [h] [h] [h] [h]

```

And you can also put the locker's value into a variable at the moment that you (try to) input a new value to the locker:

```
output
	[a = locker("a1", animal.selectOne)] [a] [a] [a] [a] [a]

```

In that case, if the `a1` locker was locked, then our new `animal.selectOne` value will be rejected, and `a` will be assigned the value that was already in the locker. Otherwise `a` will be assigned the new value (whatever `animal.selectOne` turned out to be).

You can attempt to put **any** value inside a locker at any time - a locker isn't specific to a particular list - if it's unlocked then it will accept any value you throw at it. The value will get rejected if the locker is currently locked. You could attempt to put the number 10 in the "num" locker like this:

```
[a = locker("num", 10)] is a number and it's bigger than [a-2]

```

`a` will be 10 if the locker was unlocked, otherwise it will be whatever was in the locker when it was locked.

### Styling the Locker

You can change the lock/unlock icon by doing two things. **First**, you need to paste this anywhere in your Perchance code panel:

```
lockerOptions
	lockedIcon = 🛑
  unlockedIcon = 🎲

```

And **second**, you need to paste this at the top of your HTML code panel (the bottom-right text editor) to "initialize" the plugin with those options:

```
[locker(lockerOptions)]

```

Here's an example generator showing how to do those two steps. In this example I've chosen some other emojis, but you can choose whatever you want (even an HTML image tag, for example). You can also use this feature to change the size of the existing icons:

```
lockerOptions
  lockedIcon = <span style="font-size:200%;">🔐</span>

```

## Notes

* Here's an example of a generator that uses this plugin.
* Here's a simple example that changes the icons with `lockerOptions`.
* The main difference between this plugin and the lockable-list plugin is that this plugin allows you to put arbitrary values in arbitrary lockers. The lockable-list plugin only allows you to apply locks to actual lists, and this can be very inconvenient if, for example, you wanted to use a single list multiple times with independent locks. This plugin, on the other hand, makes that very easy. Just remember to write in `list.selectOne` or `list.evaluateItem` in the brackets, rather than just `list`.
* Remember that you can ask for help on the forum if needed.