Randmap HTML / JavaScript Coding

Main  |   Name Builder  |   Symbol Map Editor  |   Writing Maps

Terms of Use - Randmap can be freely used only for non-profit purposes. And also
I (the original author) am not reponsible for any damage or unexpected results.
In other words use at your own risk.

You can add a generator to your page the fast/easy way,
or you can read how to Use a Generator Object with JavaScript

Fast/Easy Way to Add a Generator to a Web Page

Adding a generator to your site this way takes mostly just cutting and pasting.
Follow the steps below to add a generator like this one to your page:
Example Generator

Step 1) The main JavaScript code used by the generator is in the file randmap2.js.
You'll have to put a copy of randmap2.js in the same place as your HTML files.
Right click or option click below and do a 'save as' to get this file.
download randmap2.js

Step 2) Include the following fragment only once on the page that will be using one or more generators.
This fragment must come before the second fragment that you'll be adding later.
Between the <head> and </head> tags is a good place to paste this code.
If randmap2.js is in a different location than the html page, you can change the part that says src="randmap2.js"

First Fragment:

Step 3) You will need a symbol map.
You can write one yourself using the symbol map editor,
or have the name builder make a map for you,
or you can get a map any other way.

Step 4) Now you have to get the second fragment of code.
Paste your symbol map into the box below.
Change the value in the number of lines box if you want.
Click on Get Code. This will create the second fragment of code.

  Enter number of lines you want to generate each time the button is clicked
 

Get Code       Clear

Step 5) Copy the second fragment of code and paste it into the body of your HTML
source at the place where you want the generator to appear.
You can paste a whole bunch of second fragments into a single page if you want.
This way you can have multiple generators that each use different symbol maps.

Step 6) *optional* Tweak the second fragment to change how the generator looks.
If you look at the code you'll see either size="30" or cols="30"
The 30 is approximately how many characters will fit horizontally in the generator's output box.
Change this number if you want
Another thing you can tweak is value="Generate"
Generate is what the button on the generator says. You can replace Generate with whatever you want.
You can also try changing other things like deleting the <br> or adding new tags inside the form element.

Writing your own JavaScript that uses randmap2.js

Here's the basics of using a Generator with JavaScript.
Note: this page doesnt explain the JavaScript language or how to use the Document Object Model,
which are the two other things you need to know in order to write a program that uses a Generator.

First of all, you need to download randmap2.js which contains all the random generator code
Putting the following line inside the head of your HTML file will link the page to randmap2.js:
<script type="text/javascript" src="randmap2.js"></script>
Just make sure that the src attribute refers to the correct location of randmap2.js.

Here's a very basic html document that uses a Generator:

<html>
<head>
<title>Randmap Example</title>
<script type="text/javascript" src="randmap2.js"></script>
</head>

<body>
<script type="text/javascript">
<!--

var map_string = "<root>random\n<root>words\n<root>chaos\n<root>monkey";
var gen = new Generator();

if(gen == null)
{
   alert("Problem creating a generator object!");
}
else
{
   var success = gen.buildMap(map_string);

   if(success == true)
   {
      document.write("Here are some random words: ");

      var random_string;

      for(var i = 0; i < 3; ++i)
      {
         random_string = gen.generate();
         document.write(random_string + " ");
      }
   }
   else
   {
     alert("Problem with map_string !");
     alert(gen.strError);
   }
}

//-->
</script>
</body>
</html>
Click Here to see this page

Generator

Generator is the one important object you need to know about. The line var gen = new Generator(); creates a Generator object.
A Generator has has two important member functions, buildMap() and generate().
Before you can use generate(), you have to call buildMap() and have it return true.

Generator.buildMap()

You pass the buildMap() method one argument, a string containing a symbol map. buildMap() returns true if it successfully parses the map string,
or false if the string isnt a valid symbol map. After buildMap() returns false, you can read the member string strError.
strError holds a descriptive string that says what went wrong while parsing or validating the symbol map.
If buildMap() returns true, you're ready to call generate().
buildMap() can be called at any time, including after it was previously called
buildMap() might take a second or so to exectute especially if the symbol map you pass it is big (or if the computer or browser is slow).
Because of the delay you should avoid calling buildMap() when you dont have to.

Generator.generate()

generate() is a simple method that takes no arguments and returns a newly generated random string each time.
It can only be called after buildMap() previously returns true.

Encoding Symbol Maps in JavaScript

Including a symbol map inside a JavaScript program can be tricky. Symbol maps usually contain lots of newline characters.
But in JavaScript, the map needs to be all on one line with newlines replaced by the two-character sequence \n
Other characters including quotes and backslashes need to be escaped with a backslash too.
Suppose you have a symbol map that looks like this:

<root>   "I said \"Hello World\""

<root>   "wêírð"

<root>    "Back \\ slash"

If you wanted to use this map in a JavaScript program you could follow the normal rules for escaping characters.
Start by replacing every \ with \\

<root>   "I said \\"Hello World\\""

<root>   "wêírð"

<root>    "Back \\\\ slash"

Next replace every " with \" and every ' with \' 

<root>   \"I said \\\"Hello World\\\"\"

<root>   \"wêírð\"

<root>    \"Back \\\\ slash\"

You can encode the characters with accent marks using \u**** where **** is the character's unicode code, in hexadecimal 

<root>   \"I said \\\"Hello World\\\"\"

<root>   \"w\u00EA\u00EDr\u00F0\"

<root>    \"Back \\\\ slash\"

And finally you can replace the newlines with \n and this is what you get: 

<root>   \"I said \\\"Hello World\\\"\"\n\n<root>   \"w\u00EA\u00EDr\u00F0\"\n\n<root>    \"Back \\\\ slash\"

Now you can enclose this thing in double quotes and assign it to a variable: 

var map_string = "<root>   \"I said \\\"Hello World\\\"\"\n\n<root>   \"w\u00EA\u00EDr\u00F0\"\n\n<root>    \"Back \\\\ slash\"";

It's a lot of work to do this, and easy to make a mistake. So instead you can have the function toJSLiteral() do all the work for you.
toJSLiteral() is a window-level function defined in randmap2.js.
It takes one string containing a raw symbol map as an argument, and returns the string encoded for use as the contents of a JavaScript string literal.
The Convert button on the map editor page uses toJSLiteral() to convert the contents of the edit box.
Using the map editor's Convert button is probably the easiest way to get a symbol map converted for use in a JavaScript program.

Main