The Endless Engine

Using the Endless Engine in Your Own Code: The Randomizer Class

Initialization

To use the Endless Engine in your own Code, you need to first include the Endless Engine JS. The easiest way to add the Endless Engine to your own code is by adding the script tag:

<script src="https://cdn.jsdelivr.net/gh/carteredge/endless-engine@main/endless-engine.js"></script>

(If you want to create an Endless Engine randomizer that runs entirely offline, download the Endless Engine JavaScript to your project folder and add <script src="endless-engine.js"></script> to your HTML file.)

Once this is accomplished, you can call the Randomizer class from your code:

var myRandomizer = new Randomizer(myRandomizerData, myRandomizerFields);

The Randomizer accepts (but does not require at creation) the initial data and fields. The data should be provided as a Javascript object (described below), and the fields should be an array of strings, each of which is the name of a field you want randomized and added to the HTML document.

If you do not add data and fields at initialization, you can always set them at a later point (or change them), for example:

myRandomizer.data = myRandomizerData;

... or ...

myRandomizer.fields = ["myFirstField", "mySecondField"];

You can also provide the Randomizer fields when you call the randomize function (described in the next session). Additionally, if you don't provide fields for the Randomizer, it will default to randomizing each top-level key of your data object.

Calling the Randomizer

Once you have provided your data and fields to the Randomizer, you can call the randomize function. The function accepts the fields you want to randomize as the first argument. Additionally, if you provide the id of an element in the second argument, it will replace the children of that element with the elements generated from the results of the randomization.

For instance, if you call:

myRandomizer.randomize(myRandomizerFields, "outputTargetID");

The output HTML elements are by default of the form: 

                    
<li class="row">
    <strong>myFieldName</strong>
    <div>Randomizer result for myFieldName</div>
</li>

NOTE: No element is generated for any field that randomizes to an empty value, e.g. "".

If you provided fields to the Randomizer during initialization or at another point, you can pass any value with a truthiness of false to the Randomizer to use the existing fields, such as:

myRandomizer.randomize(0, "outputTargetID");

Of course, if you don't need to pass the id of the target element, you can instead simply call:

myRandomizer.randomize();

The returned value from the randomizer takes the form of an object with each field containing a text and a value attribute. Often, the value and text are the same, but not always. For instance, in the case of template strings, the value will be the initial template and the text will be the result after the templated fields have also been randomized. (For more on randomization templates, see the section on Randomizer data.

The returned object could look something like this: 

                    
{
    myField: {
        text: "Some randomized value",
        value: "Some randomized value"
    },
    myTemplateField: {
        text: "A template that reference something else.",
        value: "A template that references {myOtherField}"
    },
    myOtherField: {
        text: "something else",
        value: "something else"
    },
}

What's Next?

Creating Your Own Endless Engine Data
If you just want to start playing with randomizing your data, you can start by replacing the sampleData in the sample code using instructions here!

Try the Endless Engine Sample!
See the Endless Engine in action!