CloudSixteen/Clockwork — pull request #9 by SpencerSharkey (2013-07-11 23:04:03+00:00)
Title: Added DermaRequest Library - Capable of sending Derma popups to players with server-side callbacks.

DermaRequest Library
=====
*A simple library that adds the ability for the server to easily request strings from the client. It can also be used to push Derma message boxes to players!*

## Usage
There are currently two simple functions in the DermaRequest.* library.
```RequestString(Player ply, String title, String question, String default, Func Callback)```
- Requests a string from a player using [Derma_StringRequest](http://wiki.garrysmod.com/page/Global/Derma_StringRequest) and passes the result as an argument to the _Callback_ function provided as the last argument.

```RequestConfirmation(Player ply, String title, String question, Func Callback)```
- Requests a confirmation from a player using [Derma_Query](http://wiki.garrysmod.com/page/Global/Derma_Query) and passes the result as an argument to the _Callback_ function provided in the last parameter of the method (```true``` for "Confirm", ```false``` for "Cancel").

```Message(Player player, String message, String title, String buttontext)```
- Uses [Derma_Message](http://wiki.garrysmod.com/page/Global/Derma_Message) to send a message to a player.

## Examples
The following example adds a command named FavoriteColor, which when ran will request from the player their favorite color using the DermaRequest library. Specifically, this example uses the ```RequestString```
```lua
local COMMAND = Clockwork.command:New("FavoriteColor");
COMMAND.tip = "Asks you a simple question!";
COMMAND.flags = CMD_DEFAULT;

-- Called when the command has been run.
function COMMAND:OnRun(player, entity)
Clockwork.dermaRequest:RequestString(player, "Title of DFrame", "What is your favorite color?", "", function(text)
Clockwork.player:Notify(player, "You told the server your favorite color is: "..text..".")
end)
end;

COMMAND:Register();
```
This example utilizes RequestConfirmation, asking for a suicide confirmation first.
```lua
local COMMAND = Clockwork.command:New("Suicide");
COMMAND.tip = "Kills you, but asks you first!";
COMMAND.flags = CMD_DEFAULT;

-- Called when the command has been run.
function COMMAND:OnRun(player, entity)
Clockwork.dermaRequest:RequestConfirmation(player, "Suicide Hotline", "Please confirm you'd like to die.", function(result)
if (result) then
player:Kill()
else
Clockwork.player:Notify(player, "We've spared you this time. Come again.")
end
end)
end;

COMMAND:Register();
```

The final example makes it known to a player that flashlights are disabled. This uses the ```Message``` method.
```lua
-- Called when a player switches their flashlight on or off.
function Schema:PlayerSwitchFlashlight(player, on)
Clockwork.dermaRequest:Message(player, "Ouch! The light hurts... stop turning it on.", "No Flashlights.", "I'm Sorry")
return false;
end;
```

## Amendment
Obviously the examples given on this page aren't to be used in production, they just show how to use the functions. There are many practical uses for these functions such as asking for input while running commands, using items and entities, and much more. Sending Derma popup messages is a more prompt method of alerting a player if the information is a "must-see". Overall, the DermaRequest library is used in Slidefuse schemas and it's saved a lot of otherwise unneeded work.