<p> If you're using Windows, you should get the pre-built version from <ahref="https://code.pacman-ghost.com/public/vasl-templates/releases">here</a>, unpack it somewhere, then run <tt>vasl-templates.exe</tt>. Note that it can be a bit slow to start, so please give it a few seconds.
<p> If the program won't start because a DLL is missing from your computer, install the <ahref="https://www.microsoft.com/en-in/download/details.aspx?id=48145">VC2015 runtime</a> (get the 32-bit version, <tt>vc_redist.<u>x86</u>.exe</tt>, even if you are running 64-bit Windows).
<p><divclass="info"style="float:right;width:30%;margin:0 0 0 1em;"> Note that config files installed into the container are taken from their normal location (<tt>$/vasl_templates/webapp/config/</tt>), but are <em>overridden</em> with Docker-specific versions in <tt>$/docker/config/</tt>. </div>
If you have Docker installed, the webapp can be run in a container e.g.
<p> Then open a browser and connect to the webapp at <tt>http://localhost:5010</tt>.
<divclass="warning"style="margin:1em;"> If you have SElinux enabled, it may prevent the container from accessing files on the host. Access can be allowed like this:
<p> You can also run the program directly from the source code. Get a copy from <ahref="https://code.pacman-ghost.com/public/vasl-templates">here</a> in the usual way, by <tt>git clone</tt>'ing it, or downloading a ZIP and unpacking it somewhere.
<p> The web server was written and tested using Python 3.10.4, but it doesn't do anything particularly funky, so any recent version of Python <em>should</em> work.
<p> While not essential, it is <em>strongly</em> recommended that you set up a <ahref="https://virtualenv.pypa.io/en/stable/">virtual environment</a> first. Then <tt>cd</tt> into the project's root directory, and install the requirements (note the trailing period):
<p> If you're on Windows, the Qt runtime will have been installed as part of PyQt5 (when you did the <tt>pip install</tt> above), but if you're in a virtual environment and you're getting <em>"DLL load failed"</em> errors, this is due to a problem with the way Python sets up the virtualenv. In the virtualenv's <tt>scripts/</tt> sub-directory, there should be <em>two</em> Python DLL's, so if you're missing <tt>python3.dll</tt>, copy it over from the Python installation the virtualenv was created from, and you should be good to go.
The webdriver is tightly coupled with the browser, so make sure that the webdriver you use supports the version of the browser you have.
<p> You must also make sure to get the correct type (32- or 64-bit) for your browser (check the About box).
<p> Since browsers usually automatically update themselves as new versions are released, this means that the webdriver you use will eventually become out-of-date, and may stop working. In this case, simply get a new version of the webdriver that supports the version of the browser you have.
<li><ahref="https://github.com/mozilla/geckodriver/releases"><tt>geckodriver</tt></a> (requires Firefox to be installed)
<li><ahref="http://chromedriver.chromium.org/downloads"><tt>chromedriver</tt></a> (requires Chrome to be installed)
</ul>
<p> Unpack the download ZIP file somewhere (it will contain a single executable file), and configure the location in the <em>Server Settings</em> dialog (or set <tt>WEBDRIVER_PATH</tt> in <tt>site.cfg</tt>, if you are running from source).
<p> The desktop application uses OpenGL for the embedded browser, so if you are getting error messages about OpenGL, or the main window is not displaying properly, you can try configuring OpenGL to work in a different way.
<p> Create a file called <tt>debug.cfg</tt> in <tt>$/config/</tt> (the same directory that contains a file called <tt>app.cfg</tt>) that looks like this:
<p> In the worst case, you can set up your <tt>debug.cfg</tt> file like this:
<divclass="code">
[Debug]
DISABLE_WEBENGINEVIEW = 1
</div>
The program will then not attempt to create the embedded browser, and will just start the web server, which you can then connect to in an external browser at <tt>http://localhost:5010</tt>.
As an example, we'll set up <em>The Streets Of Stalingrad</em>. The scenario card tells us that this is played on Board 1, so fire up VASL, add this board, then save the scenario somewhere (e.g. <tt>streets-of-stalingrad.vsav</tt>).
In <em>VASL Templates</em>, open the save file for this scenario (<tt>The Streets Of Stalingrad (Scenario C).json</tt>) in the <tt>examples/</tt> directory.
<divclass="info"style="float:right;margin-top:1em;"> This information is provided by the <ahref="https://aslscenarioarchive.com">ASL Scenario Archive</a>. </div>
We now want to create labels in the VASL scenario for all this information. Choose <em>Update VASL scenario</em> from the menu, and select the VASL scenario file you created earlier (e.g. <tt>streets-of-stalingrad.vsav</tt>). The program will now launch VASSAL to do the work - be patient, since it may take a minute or two, and you may see VASSAL momentarily appear on-screen.
<p> Once it's done, save the updated <tt>.vsav</tt> file somewhere. Go back to VASSAL, open the updated <tt>.vsav</tt> file, and you will see all the labels with the scenario information: <br>
<ahref="https://vasl-templates.org"><em>VASL Templates</em></a> makes it easy to set up attractive <ahref="http://vasl.info">VASL</a> scenarios, with loads of useful information embedded to assist with game play.
<p> We'll show how by walking through a setup of everyone's favorite scenario, <em>Hill 621</em>. Click on the screenshot to the right to see the finished scenario.
<divclass="info"style="width:40%;margin:1em;"> You can find more examples <ahref="https://code.pacman-ghost.com/preview/vasl-templates/examples/">here</a>, with files that you can load into the program, together with the generated VASL scenarios. </div>
We start by entering the basic scenario details, such as its name, location and date. The easiest way to do this is by finding the scenario in the <ahref="https://aslscenarioarchive.com">ASL Scenario Archive</a> and loading the information from there.
<p> Click on the search button, enter the name of the scenario, and once you've found the correct one, click on <em>Import</em> to transfer the details into <em>VASL Templates</em>.
<p> If the <em>Downloads</em> button is enabled, this means that somebody has contributed the entire scenario setup and/or VASL save file, and these are available for download.
<divclass="info"style="float:right;width:40%;margin:1em 0;"> The scenario card may list special rules and errata, and have screenshots of the map setup, all of which will help you set up your scenario correctly. </div>
Once the scenario details are in, click on one of the <em>Snippet</em> buttons (<imgsrc="images/snippet.png"style="height:1em;margin-bottom:-3px;">), and the program will generate an HTML snippet and put it into your clipboard, which you can then copy into a VASL label.
<divclass="warning"style="width:40%;margin:1em;"> Make sure to use the <em>"Label (no background)"</em> label, as indicated in the screenshot, since the others may not work properly! </div>
<p> Labels come in two parts, which are accessible via the right-click menu, or press Ctrl-L and Ctrl-2 to access each one. I always just use the first line, so I delete everything in line 2.
<p> The thick black box indicates that the label is selected. If you click elsewhere on the main window, it goes away, and the label will remain in place even if you click on it, or try to drag it. To select it again, Shift-Click somewhere in the box, and you will be able to move it around, or edit it. This can sometimes be difficult to find, since it's not visible on-screen, but it will be in the middle (vertically and horizontally) of the label.
<p>Once you've got the hang of adding labels to your VASL scenario, you can get <em>VASL Templates</em> to do it automatically for you. After entering all the scenario details, choose <em>Update VASL scenario</em> from the menu, select the <tt>.vsav</tt> file you want to update, and all the labels will be inserted into the scenario (or updated, if they're already there).
<divclass="info"style="width:50%;margin:1em;"> VASSAL will be run to update the scenario, so you may see it temporarily appear on-screen. The process can be a little slow, and may take several minutes to complete. </div>
Adding the scenario's victory conditions is straight-forward. The content is HTML, but the WYSIWYG editor lets you format things without having to worry about that, or you can click on the angled brackets icon to edit the raw HTML.
<p> The content in the screenshot on the left will produce a snippet that looks this:
<p> Note that we explicitly set a width for the snippet (240px), which caused the text to wrap onto a new line. You could also do this by manually inserting <tt><br></tt> tags where you want line-breaks (or press Shift-Enter, if you're in WYSIWYG mode).
Adding the vehicles and ordnance for each player is just a matter of selecting them from a list, and the generated HTML snippet will produce a table of information for each one (see right). Very handy if you have a menagerie of armor and you're, say, looking for something that can fire Smoke.
<p> The scenario date is taken into account when generating these tables e.g. APCR for the Pz IVH is A5<sup>2</sup>4<sup>3</sup>3<sup>4</sup>, but since the program knows the scenario is set in 1944, it just shows A3. Had the scenario been set in 1941, it wouldn't be shown at all.
<divclass="info"style="width:40%;margin:1em;"> It's also possible to include Chapter H notes in your scenarios, although you will need to <ahref="#"onclick="select_tab('chapterh');">set some things up</a> first. </div>
Finally, if special support weapons such as PF and BAZ are in play, snippets are available with information for them. As with vehicles/ordnance, they are date-aware and update themselves accordingly.
<p> If you have already set up the VASL scenario, you can choose <em>Analyze VASL scenario</em> from the menu, and the program will scan the <tt>.vsav</tt> file for vehicles and ordnance, and automatically create entries for each one.
<divclass="info"style="margin:1em;"> Only counters from the two configured nationalities will be imported, <br> so make sure you set these first. </div>
<p> Extra templates are also available to generate other kinds of snippets e.g. to keep track of how many PF shots you have left, or to generate boxes that you can use to hold off-board counters.
You can also include your own images in scenarios e.g. the picture from the scenario card, or CG reinforcement tables.
<p> In the <em>Server Settings</em> dialog, configure the directory where you keep your files, then in a template, use <tt>{{USER_FILES}}</tt> at the start of an image URL e.g.
<divclass="code">
<img src="{{USER_FILES}}/hill-621.png">
</div>
You can add a <tt>scaling</tt> parameter to resize the image (as a percentage of the original) e.g.
<divclass="hint"style="float:left;width:45%;margin:1em;"> If you use this feature in your scenarios, the images won't be available if you share the VASL scenario with someone else (since the files are only on your computer). However, if you upload them to a web server on the internet, you can configure the <em>"User files"</em> directory as a URL, and any image URL's that use <tt>{{USER_FILES}}</tt> will now get them from there. </div>
<divclass="warning"style="float:left;width:35%;margin:1em;"> You should avoid having spaces in image URL's, since VASSAL seems to have problems with them. </div>
<divclass="hint"style="float:left;width:35%;margin:-0.5em 0 0 1em;"> VASSAL caches images (which can't be turned off), so if you're making changes that don't seem to be having any effect, try restarting VASSAL. </div>
When the scenario has been completed and checked, you can contribute it back to the community by uploading it to the <ahref="https://aslscenarioarchive.com">ASL Scenario Archive</a>, where it will be made available to everyone for download.
<p> Just add your VASL scenario file (<tt>.vsav</tt>), a screenshot will be automatically generated (or you can add your own), then click <em>Upload</em>.
<divclass="info"style="float:right;width:40%;margin-top:1em;">For copyright reasons, some details will be removed from the upload e.g. the Victory Conditions and SSR's. </div>
As an added bonus, <em>VASL Templates</em> can also analyze VASL log files, to generate a report on how the game went. Choose <em>Analyze log files</em> from the menu, and add one or more VASL log files.
<p> You will be shown a report showing distribution graphs for the dice, and how the dice went over time. You can filter by the type of dice roll (e.g. only Morale Checks or To Kill rolls), as well as change the window size for moving averages. You can even download the data as a CSV, for further analysis.
The report also calculates <em>"hotness"</em>, which is a measure of how hot your dice were. The more low rolls you make, the higher your hotness score, while rolling high makes it go down.
<p> So if you lose, you now have some hard numbers to back you up when you blame the dice <imgsrc="images/smilies/cool.gif">
Turn this on to show the <em>User Settings</em> dialog before updating a VASL scenario. This is useful if you are often creating VASL setups with different settings, and gives you a chance to make sure they are correct.
<li><em>From this program</em>: the <em>VASL Templates</em> program must be running before you open the scenario in VASSAL. If you are playing with someone online, they must have the program running as well.
<li><em>From the internet</em>: you must have a working internet connection when you open the scenario in VASSAL. There will be a short delay when opening the scenario, as VASSAL downloads the images.
<p> VASSAL can be slow downloading images (which causes the main window to blank out and hang when opening scenarios), so options are provided to disable them.
If you have set up the <ahref="#"onclick="select_tab('chapterh');">Chapter H vehicle/ordnance notes</a> as HTML, it may not be possible to get the layout you want, since VASSAL's HTML engine is very old and doesn't support many HTML/CSS features. To work around this, this option tells <em>VASL Templates</em> to render the HTML itself (using a modern browser) and send it as an image to VASSAL, which is slower but gives better results.
<p> To optimize this process, the generated images are cached. If you want to pre-load this cache with all the available images, open <tt>http://localhost:5010/load-vo-notes-image-cache</tt> in a browser.
<p><em>VASL Templates</em> can be configured to include Chapter H notes in your VASL scenarios, but since this is copyrighted material, the data files are not included in releases, and you will need to set them up yourself.
<p> Unpack this <ahref="https://code.pacman-ghost.com/preview/vasl-templates/chapter-h/">ZIP file</a> somewhere, and configure the location in the <em>Server Settings</em> dialog (or the <tt>CHAPTER_H_NOTES_DIR</tt> setting in <tt>site.cfg</tt>, if you are running from source).
<p> The ZIP file contains placeholder files for the Chapter H vehicle/ordnance notes and multi-applicable notes, so all you have to do is update these files with the real content.
<p> Multi-applicable notes are stored as HTML, so for example, for German Multi-Applicable Vehicle Note A, change the file <tt>german/vehicles/a.html</tt> as follows:
<divclass="info"style="width:60%;margin:1em 0;"> Because Windows has case-insensitive filenames, the convention is that Multi-Applicable Note "A" is stored in a file called <tt>a.html</tt>, while Multi-Applicable Note "a" is stored in <tt>a_.html</tt> (with a trailing underscore). </div>
<p><imgsrc="images/chapter-h/psw-234.1-note74.png"style="float:left;"class="preview"> The vehicle and ordnance notes themselves are stored as image files, so you need to scan your Chapter H pages, and crop each individual note. For example, an image for the German PSW 234/1 can be seen to the left - download and save it on top of <tt>german/vehicles/74.png</tt> (because it's note #74).
<divclass="hint"style="width:60%;margin:1em;"> It is also possible to store the vehicle/ordnance notes as HTML, and while it is significantly more work to set things up this way, it gives much better results. Using the placeholder files from the ZIP above, wherever there is a <tt>.png</tt> file, rename it to have a <tt>.html</tt> extension, and then put the HTML in there.
<p> Unfortunately, the HTML engine used by VASSAL is ancient and doesn't support floating images, which is needed to format this content in the same way as the ASLRB. To work around this, an option is provided (in the User Settings) to show these vehicle/ordnance notes as images. If this is enabled, the vehicle/ordnance notes will be rendered by the <em>VASL Templates</em> program (using a modern browser), and sent to VASSAL as an image, which is slower but gives the expected layout. If you don't use images in your HTML, you can leave this option disabled, and the raw HTML will be inserted into the VASL scenario, where it will be displayed much more quickly by VASSAL.
<h2> Adding Chapter H notes to your VASL scenario </h2>
<p><imgsrc="images/chapter-h/ui.png"style="float:right;"class="preview"> Restart the <em>VASL Templates</em> program, and add a PSW 234/1 to the German OB. You will see some changes in the UI (see screenshot).
<p> In the bottom-right, there are new controls for generating an HTML snippet for the multi-applicable notes. Click on the <em>Snippet</em> button, create a label in a VASL scenario, and you see the multi-applicable notes for the vehicles in the OB (the program will only include those that are needed). This content was taken from the <tt>a.html</tt> file you set up earlier.
<p> Each individual vehicle and ordnance can also now have its own snippet button. Click on the one for the PSW 234/1, transfer the snippet to your VASL scenario, and you will see the image for Note 74 you set up earlier.
<divclass="hint"style="float:left;width:50%;margin:1em;"> Depending on how you scanned the Chapter H pages, the image may not be the right size, so you can set a scaling factor for these images in the Server Settings dialog. As a guide, I scanned my ASLRB at 300dpi, and a scaling factor of 40% produced images that fit in with the rest of the scenario. However, if you have a lot of these images, there will be a noticeable delay when loading the scenario in VASSAL (because the program has to resize all the images), so you will be better off shrinking the images yourself, then setting the scaling factor to 100, so that no resizing needs to be done. </div>
<divclass="warning"style="float:left;width:35%;margin:1em;"> VASSAL caches images (which can't be turned off), so if you're making changes that don't seem to be having any effect, try restarting VASSAL. </div>
<p> If you Shift-Click on the Snippet buttons, an <em>image</em> of the snippet will be copied to the clipboard, instead of the raw HTML snippet. You can then copy these into Microsoft Word (or any other editor that can accept images), and print it out, to get a reference sheet with all the Chapter H notes for a scenario. Very handy, even if you're not using VASL!
<divclass="info"style="margin:1em;"> This feature requires a <ahref="#install-webdriver"onclick="select_tab('installation');"><em>webdriver</em></a> to be installed. </div>
<h2style="margin-top:0;"> How template files work </h2>
<p> The HTML snippets are generated from <em>template files</em>, which are simply text files that contain the HTML you want to insert into the VASL labels, but with placeholders for the scenario name, victory conditions, each player's OB, etc. The user enters these details into the program, and when they want to generate a snippet, all the placeholders are replaced in the template with the real values, thus producing an HTML snippet specific to that scenario.
We'll take a look at the <tt>ssr.j2</tt> file, which is used to generate snippets for the SSR's.
<p> Open the file in a text editor (if you're on Windows, you will probably need to right-click on the file and choose <em>Open with...</em>), and you'll see something like this:
<p> The template looks like normal HTML, but with some extra stuff. Things that look like <tt>{% ... %}</tt> are commands to the template processor. At the top of the file, we see this:
<divclass="code">
<table style="
{%if SSR_WIDTH%} width: {{SSR_WIDTH}} ; {%endif%}
">
</div>
This is saying <em>if the user has specified SSR_WIDTH, then insert into the generated HTML snippet everything up to the next <tt>{%endif%}</tt></em>. In this case, that's the following:
<divclass="code">
width: {{SSR_WIDTH}} ;
</div>
Things that look like <tt>{{...}}</tt> are the actual values entered by the user into the UI, in this case, the SSR width.
<p> So, if the user has specified a width of, say <em>300px</em>, this is what will be inserted into the final HTML snippet:
<divclass="code">
<table style="width: 300px ;">
</div>
But if the user hasn't specified anything for this field, what's between the <tt>{%if ...%}</tt> and <tt>{%endif%}</tt> will be ignored, and we get this:
This sets up an HTML list (<tt><ul></tt>) and repeats everything between the <tt>{%for ...%}</tt> and <tt>{%endfor%}</tt>, once for each entry in the <tt>SSR</tt> variable, which contains the SSR's entered by the user in the UI. Each time around, <tt>{{ssr}}</tt> will be updated to hold the next entry, which will be inserted into the generated HTML snippet as a <tt><li></tt> node.
<p> If you want to customize how the HTML snippets are generated, you could just edit the template files directly, but the down-side of doing this is that if you install a new version of the program, you will lose your changes.
<p> If you're running the desktop application, you can specify the template pack to start with, so that you don't have to manually upload it each time i.e.
When you're writing a new template file, it would be painful to have to ZIP up and upload a new template pack every time you made a change, so you can edit templates directly within the program (see screenshot).
<p> Changes you make are live i.e. they will take effect immediately, but note that there is no way to save your changes, so once you're happy with how the template is working, you need to copy it out and save it somewhere.
<p> The tests use <ahref="http://pytest.org">pytest</a> and <ahref="https://www.seleniumhq.org/projects/webdriver/">Selenium WebDriver</a>, so you will need <tt>geckodriver</tt> and/or <tt>chromedriver</tt> somewhere in your PATH. The driver to use can be specified via the <tt>--webdriver</tt> parameter, and you can also run the tests headless e.g
<p> The test suite communicates with the web server being tested using gRPC, which runs over a socket. To configure this port, rename the provided <tt>debug.cfg.example</tt> file to <tt>debug.cfg</tt>, and configure it there (or use -1 to have one automatically assigned.).
<p> You should also provide at least one installation of VASSAL, and at least one VASL <tt>.vmod</tt> file. If there are multiple installations of either, the tests will be run against each combination thereof.
<p> The program uses VASSAL to update VASL scenarios (<tt>.vsav</tt> files), and since this is written in Java, a helper program has been written in Java to do this.
where <tt>VASSAL_DIR</tt> points to VASSAL's <tt>lib/</tt> directory (because the program needs <tt>Vengine.jar</tt>).
<p> Since this program doesn't change very often, the resulting artifact (<tt>vassal-shim.jar</tt>) is checked into source control, so that it can be used directly, without needing to install a JDK and compiling it first.
<p> Python code is checked using <ahref="https://pylint.readthedocs.io/en/latest/"><tt>pylint</tt></a> (installed during the <tt>pip install</tt> above), which should be run from the root directory of the repo.
<p> Javascript is checked using <ahref="http://jshint.com"><tt>jshint</tt></a>, run using <ahref="https://github.com/mozilla/rhino">Rhino</a>, both of which need to be installed manually. Set the <tt>JSHINT_RHINO</tt> environment variable to point to the script that will run <tt>jshint</tt> using Rhino e.g.
<p> It is possible to compile the desktop application down to a single binary. This is typically done for the benefit of Windows users, but also works for other platforms. From the root directory of the repo: