A Tutorial by Airjoe
So, you want to make a website and figured you'd give DMCGI a try? Or maybe you just wanted to become a little more familiar with DMCGI in general. Well, whatever it is, you need somewhere to start, so here it is.
Contents:
- The Basics
- Starting with Dynamics
- Organisation for Dynamic Pages
- Basic Forms and href_list
Each section will contain a challenge at the end. The answers to the challenges can be found here, along with all the code from each section.
Before I actually get into the programming, let's find out what DMCGI really is and how it works. Basically, DMCGI is simply a web scripting language. A benefit of using a CGI language is the ability to make a dynamic page instead of a static page. If you had a static page, which is generally just HTML, you would have to edit code every time you want to make a change to the website. With a dynamic page, your script can change the page based on user input or other current conditions (such as the time of day or the current price of a stock). This gets rid of having to mess with icky HTML, especially if you're not a great HTML programmer. So, why use it over any other web-based language? Well, its really just preference. If you're already a decent programmer in the DM language, however, you may find it easiest to use DMCGI.
But how does it work? The documentation of Dantom's CGI lib says, "DM source code is compiled into a .dmb byte code file. Normally, this is accessed by users through Dream Seeker, either directly or over the Internet. In web mode, the .dmb file is uploaded to a web site where users can access it using any web browser." Dantom's CGI library allows you to do this. If you're really interested in the technical details, take a look at the source code. Either way, you're going to need to download it. Do so at http://www.byond.com/developer/Dantom/CGI. If you're not very experienced with HTML forms, it may be to your benefit to use Dantom's htmllib as well. (This tutorial will not cover how to use Dantom.HTMLlib.)
The main points of DMCGI are the CGI datum, and the Topic() procedure. The CGI datum is almost equivalent to the client in a normal BYOND game. It is the person who is viewing the site. The Topic() procedure is called anytime the viewer is sending something to the program (such as sending information that a link was clicked, or submitting a form.) The Topic() procedure takes three arguments; only two of which will be used in DMCGI. These are href (which is whatever is after the ? in a link or address, for example; index.dmb?Something) and href_list (simply params2list(href)).
Let's get started with the code! Here's a little snippet just to get you introduced.
That's a very basic example. When the viewer first accesses the webpage, they will see "Welcome to this webpage! About This", because there is no link involved, and there is no "?" in the address. If, however, you had a url to the site such as "http://www.mysite.com/index.dmb?About" then they would be brought straight the the About page. You probably noticed usr is used in that example. usr is safe in CGI/Topic().
Challenge 1: See if you can modify that example to make one of those "How to keep an idiot occupied for hours!" type things.
You might be saying, "Well, that's really easy stuff. I could do that in regular HTML." That example barely touches the capabilities of DMCGI. Let's see if we can do something a little more advanced. How about a counter? This will use a couple things from normal DM programming, such as a savefile. It will also use the world/New() procedure, for loading the savefile.
If you look through the code there, you should be able to understand it. The stuff on top is pretty basic DM stuff. The only real difference in CGI/Topic() is a little addition at the end of display. You'll also notice the CGI/New() procedure. This is called whenever a viewer first accesses the page. In CGI/New() in this example, we add to the Hits variable and then Save.
Challenge 2: This counter will add a hit everytime anyone comes to the site. Can you make it so it only will add for each unique hit? (Hint: Look into the CGI library for help)
Easy to follow so far, right? Let's keep going. How about we make a system to make it easier to keep track of our pages. This is a step towards dynamic page creation, deletion, and also navigation!
See, rather than hard code each page in the CGI/Topic() procedure, you can use a list and just look for href in that list. By doing this, you allow yourself to be able to add and remove from that list, letting you make and delete pages from your site.
Challenge 3: Can you make a working navigation section?
A key point to using CGI is the ability to use forms. Let's look at the code for a basic form.
First let's understand the form, in case you don't have experience with html forms. The first line in BasicForm is <form method="get">. This starts a form, with the method set as "get". The GET method sends the form contents in the URL, so we can use href_list. The POST method does not work in DreamSeeker. The next line is a hidden "input". Nothing is actually "inputted" into this; there is no field. Rather, it's a way to send more information to CGI/Topic(). In this case, we're sending a piece of information called "action", and it's value is "exampleform". You can see this is parsed for in CGI/Topic().
The next line is a text input. Its name is set to "Name" so we can access it later, and its value is already set. For more information about forms, input types, and attributes, be sure to check out the w3schools webpage. The line after that is another type of "input" -- a submit button. The value of a submit button is just what the submit button says. After this, we close the form.
In CGI/Topic(), the normal stuff happens first (finding the page). This can be changed around if you want to do something special with a form. In this example, the only thing that's going to happen is a little piece is going to be displayed. After the initial display has been determined, Topic() checks href_list for a variable called "action". If "action" is set to "exampleform", and there is also a variable called "name", then display the welcoming message. Otherwise, if the viewer is on the main page, display the form.
Challenge 4: Can you make a login system so that the viewer cannot access the main page without logging in?
