JSInterfaces

The Common JS Interfaces

Here's a quick description of some of the common JavaScript interfaces that we use.

class State

This is a helper class that allows the simulation of common formatting techniques at the time - many DOS mags (and even some Windows ones) simply used control characters (such as \xAB or \xFF) to signify a color change, or an inline image, or a font change, and so on. However, since we're porting from this very state-based system to a (hopefully) well-formed HTML one, we're going to need some help.

What the State class does is simply create an interface where control characters can request setting or removing or toggling some states, and the State class will keep track of these states and turn them into CSS-compatible styles, while attempting to maintain the markup integrity.

Example (from Dissonance #02)

Original text:

júliusban  \xffCCSce\xffCBRage\xffCCNest\xffCA  party

Example parsing code:

      if (str[i]=='\xff')
      {
        switch (str[++i])
        {
          case "C": // color
            {
              var color = str[++i];
              switch(color)
              {
                case "A": out += this.state.add("color","#B8B8B8"); break;
                case "B": out += this.state.add("color","#D0D040"); break;
                case "C": out += this.state.add("color","#00B848"); break;
                case "D": out += this.state.add("color","#00B8D0"); break;
                case "E": out += this.state.add("color","#CC4040"); break;
              }
              // todo
            }
            break;
[...]

Resulting markup (with line breaks for clarity):

júliusban  </span>
<span style="color:#00B848;">Sce</span>
<span style="color:#D0D040;">Rage</span>
<span style="color:#00B848;">Nest</span>
<span style="color:#B8B8B8;">  party

Note how when there's a change, the state manager will attempt to close the previous tag. This makes the markup fairly bloated, but it's something we have to live with.

class MagInterface

This is the wrapper class each magazine sits in. The functions are documented in the source, so instead here's a set of considerations and recommended workflow:

1. First, implement the following "abstract" functions: getMagDisplayName, getExtension, getIssues, generateHTML and getModes - most of these are fairly self-explanatory, with the exception of getIssues: since this file both serves as data for JavaScript and the actual website, this has to be well-formed JSON! Again, check existing mags for reference
2. Second, implement loadMagIssueData: This function receives an ArrayBuffer with the mag datafile specified in the url field of the getIssues record, and should return a Promise which it resolves once it's done loading.
3. Next, implement loadFileFromArchive if possible (some mags don't necessarily have a file-based system, so may just have to return null here); again this receives a filename (or index), and should return a Promise that resolves with an ArrayBuffer of the file contents. This will allow helper functions like loadASCIIStringFromArchive to sit on top.
4. Implement loadMenu and loadArchive; the former's first parameter is a boolean that's true when the mag is first loaded - use this to reset the scrolling and stuff. The latter receives an article filename or index as parameter.

Other tips:

• Use this.issueX and this.issueY and window.onresize() to change the mag resolution if it wasn't 640x480.