You may remember I released a small DMCGI example in my first How-To, but in this one we're going to delve deeper into the world of DMCGI, the awesome web-language that can be used on servers where BYOND is installed.
First, download Dantom.CGI and include it in your project.
Table of Contents:
- What procs do what
- Basic Examples
- Advanced Examples
Here's a list of procs and other stuff you're gonna want to look at before you start.
CGI - This is the main thing. It's a datum with its own procs and variables, most of which are defined in the CGI library you should have downloaded and included with your project.
Topic() - This is a big one, too. This proc is called every time a request from a browser is sent to your program.
I'll explain more later, but these are the biggest parts.
More In-Depth with the Topic() proc
I personally see the Topic proc as one of the neatest procs DM has. It not only allows you to use links in your game that interact with other parts of your game, but it also makes DMCGI a very powerful tool.
First let's take a look at the arguments Topic takes: "href", which is any text after a ? character in a URL; "href_list", which will be explained later; and "hsrc", which isn't really needed in DMCGI, so I won't go into it.
This means the Topic() proc should look something like this: Topic(href,href_list). Since you don't need hsrc, don't even bother adding it to the proc. href is pretty much a toned-down version of href_list, so it's used for very basic pages. I'll show you a commented example of how to make a simple "Hello world" page that has more than one page built-in using href.
CGI //This shows the program you're making a CGI object.
Topic(href) //not using href_list so don't waste space defining it.
if(!href) //if href is empty go to the default
usr << browse("<HTML><BODY>Hello world!</BODY></HTML>")
//display a simple page to the user
if(href == "two") //if the URL is something like http://www.yoursite.com/yourprogram.dmb?two
//it will go to this one.
usr << browse("<HTML><BODY>Hello again!</BODY></HTML>")
//Display a different page
Okay, this is where Topic() takes its second argument, href_list (which is a list, of course); this stores any data passed into the URL with a variable name (e.g., http://www.yoursite.com/test.dmb?argument=something). In that example, href_list["argument"] would equal "something". This is useful if you want to separate your site into sections, and have to use the same name in two different sections.
CGI //Again, make sure you always have this.
Topic(href,href_list) //Now it has both arguments.
if(href) //If href has a value
if(href_list["section"]) //If "section" is being passed into the URL
if(href_list["section"] == "one") //If the URL is something like
usr << browse("<HTML><BODY>This is section one.</BODY></HTML>")
//Let them know what section they're in.
Now using the first example on this page you can make a fully functional page with sections, all using one file.
Okay, say you want to force a user to log into your site to use it, using the BYOND login system (DMCGI can use BYOND keys just like DM itself; neat, huh?). Well, it's not hard. The CGI library has a built-in variable for this, appropriately named "authenticate". All you have to do is set this variable to 1, and it'll force login.
CGI //Make sure it knows you're using CGI variables.
authenticate = 1 //This tells it to authenticate a user.
Very simple. Now let's move on.
Another cool feature of the CGI library is the Login() proc, which directs the user to the BYOND-key login page, and directs the user back to your page after logging in. This is useful if you want a login link on your page.
Topic(href) //Just a basic Topic()
if(href == "login") //If the user clicks something like
src.Login() //Simply call the Login() proc for the CGI object here,
//and the library does the rest.
You can do the same thing with the Logout() proc here, to log the user out of the current key.
Well, I hope you enjoyed this installment of Nadrew's How-To's. And I hope this helps you on your way to making DMCGI-enabled websites. You can find the fully commented source to my website at http://www.nadrew.com/index.dmb?source [this link no longer works -- Ed.].