The CGI library by Dantom provides the interface for creating powerful dynamic websites using DM.
Using the CGI/Topic() proc or the htmllib library by Dantom you'll be able to do everything from a simple page with dynamic content to a powerful forum. You're only limited by what you can output using DM.
The most popular method of using Dantom.CGI (DMCGI from here on) is to include the htmllib library along side with it. The htmllib provides a datum-based page handler system that allows you to use forms and process various data. I'll detail the usage of the htmllib in my review of it; for now lets move on to the more powerful method...
CGI/Topic()
The Topic() proc is the function that BYOND uses to handle incoming data and internal links. CGI/Topic() is no different, it allows your world to interact with links and incoming data; the difference is that CGI/Topic() spits the resulting data back out in a way a browser can read and display.
The proc takes two arguments, the first is most commonly called 'href' this variable will contain all of the parameters passed to your world in text format (eg: "action=test&other=something"). The second argument is commonly called 'href_list' or 'prms' this is generated by passing the first argument through params2list().
Usage of the href argument is generally for checking if any parameters are passed or not, since it's easier to make use of href_list to read and use the parameters.
Here are a few examples of how to use CGI/Topic()
CGI/Topic()
usr << "Hello world"
This will display a simple 'Hello world' message to the person viewing the page.
In CGI/Topic() usr will always be the person accessing the page. Anything output will be displayed on the page, you can also use browse() which will act identical to simple output when the world is running in CGI mode.
CGI/Topic(href)
if(!href)
usr << "<a href=\"?clickhere\">Click here</a>
else if(href == "clickhere")
usr << "Thanks for clicking!"
This will present the user with a link, and upon clicking that link it will display a thank you message.
When only using a single parameter with no value it's easy enough to just use href alone.
CGI/Topic(href,href_list[])
if(!href)
usr << "<a href=\"?page=one\">Page one</a> or <a href=\"?page=two\">Page two</a>?"
else if(href_list["page"])
if(href_list["page"] == "one")
usr << "This is page one!"
else if(href_list["page"] == "two")
usr << "This is page two!"
else
usr << "Whoops! This isn't a page at all!"
This will present the viewer with two links, both leading to different output.
Since the URL parameters contain a parameter with a value the href_list will contain a list element named after the parameter with an associated value equal to the value of the passed parameter.
BYOND Key Support
One of the best features of DMCGI is the ability to make use of the key variable to see the viewer's BYOND key. The library provides a Login() and Logout() proc which will lead the user to the BYOND login page. Both procs take a string as an argument, this argument is used to redirect the user back to a certain page after a successful login or logout.
The library also provides a variable called 'authenticate' which when set to true will force the viewer to login before being able to access the page.
CGI/Topic(href)
if(!href)
if(usr.ckey == "guest")
usr << "You need to <a href=\"?login\">login</a>"
else
usr << "Welcome [usr.key]! (<a href=\"logout\">logout</a>"
else
if(href == "login")
src.Login("http://myurl.com")
else if(href == "logout")
src.Logout("http://myurl.com")
This will show the viewer a message informing them that they need to be logged in if they're not already logged in (their key will be 'Guest' if not logged in) and a welcome message if they are.
Calling src.Login() will direct the viewer to the login page, the argument will redirect them back to "http://myurl.com" after they've logged in. Logout() works the same, except it logs them out.
Other /CGI procs
GetEnv(name)
The GetEnv() proc allows you to grab system environment variable values, which is helpful for things like telling what kind of system the world is running on.
SetCookie(name,value,expires,domain,path,secure)
The SetCookie() proc allows you to set HTTP cookies for the viewer, just like any web language does.
SetCookie("mycookie","rocks",world.realtime+36000,"myurl.com","/",0)
This will set a cookie known as 'mycookie' with the value 'rocks' that expires roughly 360 minutes after it is set. The domain argument tells the browser what domains/subdomains to accept the cookie from, and the path tells it what file path to accept it from. The secure setting will make the cookie secure, which will prevent it from being edited.
WebifyByondUrl(url)
This proc is depreciated, it used to change a URL into an old-style dms.cgi URL for usage in joining BYOND worlds.
Reroute(url)
This proc will send the proper browser headers to cause the page to redirect to the URL specified. You can't output any text to the page before using this proc.
HttpHeader()
This proc is automatically called and you should never need to manually call it. It sends the required HTTP headers to the page output so that the browser will recognize it as something valid to display.
The /CGI variables
content_type (Default: "text/html")
The content_type variable allows you to change what content header is sent to the browser, this will let you do things like displaying the page as plain text or even generating images.
expires (Default: 0)
The expires variable tells the browser how long to cache the data on the page, the default 0 prevents any caching from being done, since most CGI content is dynamic.
http_headers (Default: null)
The http_headers variable will contain newline-separated headers that are sent by the page, this is useful if you're debugging the entire output of your CGI.
default_form, waiting_form (Default: null)
These are used in conjunction with htmllib, I'll explain them in the review for that library.
authenticate (Default: 0)
Then set to 1 (true) the authenticate variable will force the viewer to login before CGI/Topic() is even called.
cookies (Default: empty list)
The cookies variable contains all of the cookies avaliable to the CGI application. Cookies are only avaliable if set on the same domain and path as the application.
params (Default: empty list)
The params variable is a list of params passed to the world, this is later translated to the first argument of CGI/Topic().
header_done (Default: null)
The header_done variable is set to true when any non-header output is sent to the browser. This is useful for telling if you can send new headers manually or not.
byond_mode (Default: 0)
The byond_mode variable is automatically set to 1 if the application is running in Dream Seeker and not the browser. Useful for altering behavior between the two.
That's about it, that should be all you need to know to get started with DMCGI. If you have any questions or need any help be sure to check out the DMCGI Guild. You can find more information on advanced DMCGI techniques and setting up a server to use DMCGI there.
And remember, there may be more information avaliable in the included documentation of the library, be sure to read it over before you get started!
