Adding Machines to Web Pages

NOTE: This discussion only applies to PCjs running on its own web server. Adding PCjs machines to other web servers is a topic for another day.

For this exercise, let's use the page for Central Point PC Tools 1.03, which initially contained only a directory listing of the diskette.

First, a bit of background: every page on the pcjs.org website is a Markdown file, usually named README.md (or index.md), which contains some data at the top of the file called "Front Matter" that tells Jekyll -- the HTML page generator used by GitHub Pages -- some basic things about the page, like its title (title) and location (permalink) on the website.

The Central Point PC Tools 1.03 page's Front Matter was originally very simple:

---
layout: page
title: Central Point PC Tools 1.03
permalink: /software/pcx86/util/other/pctools/1.03/
redirect_from: /disks/pcx86/tools/other/pctools/1.03/
---

So I inserted the following machine definition. As the name implies, machines can contain more than one machine definition, but for this exercise, the page will contain only one machine, with an id of "ibm5150":

---
layout: page
...
machines:
  - id: ibm5150
    type: pcx86
    config: /configs/pcx86/machine/ibm/5150/cga/64kb/machine.json
    sizeRAM: 256
    testRAM: false
    autoMount:
      A:
        name: PC DOS 2.00 (Disk 1)
      B:
        name: Central Point PC Tools 1.03
    autoType: $date\r$time\rB:\rPCTOOLS\r
---

Then, in the body of the page, wherever you want the machine to appear, insert the following line:

{% include machine.html id="ibm5150" %}

And that's it!

Any machine definition must include id, type, and config properties, and by convention, I always start the definition (the line with the hyphen) with the id property:

  - id: ibm5150
    type: pcx86
    config: /configs/pcx86/machine/ibm/5150/cga/64kb/machine.json

id is user-defined; machine IDs are not shared across pages unless you also use the resume property (which is a topic for another day). type must be a recognized machine emulator type; "pcx86" indicates the PCjs IBM PC emulator. And config should be the location of an existing configuration file; it's also possible to list all the configuration properties directly underneath the config property and not use an external file at all, and while that can be slightly faster in terms of page load speed, I prefer having reusable machine configurations.

Any other properties, such as sizeRAM, autoMount, etc, simply extend (or override, in case of a conflict) any properties present in the config file.

The autoType property is particularly handy, because it allows you to inject an initial set of keystrokes into the machine, to help kickstart a demonstration of the software, and it includes several enhancements, like the ability to inject the current date ($date) and time ($time). Until I have time to do a more thorough write-up on autoType, not to mention many other handy features, see this PCjs blog post for more details.

Config files come in two flavors: XML and JSON. For this exercise, I used a JSON file, which is new for PCjs.org 2.0. The original PCjs.org 1.0 website was built exclusively with XML files, which are still used and and still supported.

Personally, I prefer the XML format, because it describes not only how the machine components should be configured but also how (and in what order) any visual elements should be laid out on the page. Compare the machine.json used above to its original machine.xml counterpart.

XML files are transformed into HTML by a common set of XSL files, whereas JSON configuration files require separate HTML template files for every machine type.