Using extra project JavaScript and CSS resources

There are various ways for your project to provide additional JavaScript and Cascading Style Sheets. The chosen skin already provides many. Your project can supplement that, and provide additional capabilities for your whole site or for specific pages.

Note that the new Dispatcher capability provides its own more powerful techniques. See Status of Themes: Skins and Dispatcher. Still, some of the techniques described below are relevant.

Demonstration #1:

Demonstration #2:

Demonstration #3:

Overview

The "link" and "script" elements can be added to the head section of your source xml or source html documents. The project sitemap can add a Transformer to inject additional elements to the internal xml. The "Content Aware Pipelines" can detect certain documents to apply such. The sitemaps and locationmaps resolve the linked resources by searching through a set of known locations in your project.

To understand how the various resources are linked and resolved, view the source file that created this page. Also follow the addition in r1538085 to this site's project sitemap ($FORREST_HOME/site-author/sitemap.xmap) which shows how to utilise the Sourcetype Action (Content Aware Pipeline) and how to use an additional Transformer to inject an additional "script" element to the header of the internal xml.

The initial addition of this document was r1538085 and the first major enhancement was r1538865.

D3.js Data Driven Documentation

Hooking up D3.js is very easy, as shown there. After declaring the "script" element in the header of your source, then add one of the example snippets to your project JS. The "randomly color paragraphs" example is a quick test that you are up and running.

Obviously it is a very powerful combination to use D3 together with Forrest's ability to gather, co-ordinate, and transform data.

Leaflet

Follow the excellent example "using D3 to render GeoJSON shapes in conjunction with Leaflet".

Forrest will automatically find the CSS and JS when you place them in the corresponding "project resources" directories as explained above.

In this case we need to help Forrest find the images that are used by the Leaflet CSS. For example, it is looking for the resource css/images/zoom-in.png (i.e. relative to its CSS file).

However, the default machinery in Forrest for locating images does not look in that location, even if you try to place them there.

Add to your "project locationmap". This is consulted first in the sequence of locationmaps, so you can cause Forrest to look for all project image files in certain specific locations. If it does not find them there, then it continues through the default locationmaps.

So if you added your source images to a resources/images/leaflet/ sub-directory, then add the following to your "project locationmap":

<match pattern="project.images.**.*">
  <location src="{properties:resources.images}leaflet/{1}.{2}" />
</match>

Note that each locationmap match can try multiple locations in sequence.

This "project locationmap" technique is useful for utilising multiple image/javascript/css libraries and keeping their resources separate.