Introduction to Pages

The Uniform Resource Locator (URL)

To understand the naming structure of pages, we need to review how content is addressed on the Internet (the Word Wide Web). Each web page> is a document (or resource>) that can be uniquely addressed by a Uniform Resource Locator, or URL. A URL consists of the following parts:

1. Scheme - the protocol used by the browser to request the resource. For the purposes of this chapter, there are two possible schemes: HTTP or HTTPS. HTTP stands for Hypertext Transfer Protocol and the added S for Secure. The scheme is always followed by a colon and two forward slashes ://
2. Domain name - a name that is looked up in the Domain Name Registry to find the IP address of a server (or network of servers). It may be possible to use an IP address instead of the domain name, though in many cases the web server looks at the domain name to determine what content will be served, in order to provided multiple domains on the same server.
3. Port number - a number that identifies a service provided by the server at the specified domain name or IP address. Normally, the port number can be omitted and will be inferred based on the scheme: 80 for HTTP and 443 for HTTPS. The port number, if present, is preceded by by a colon :
4. Path - a name that indentifies a resource on the web server. The path must start with a forward slash / and can optionally include multiple forward slashes which is similar to a directory structure on a computer file system. A path that ends with a forward slash is generally regarded as a request for the content of a directory (i.e. a list of files therein) and most web servers will either serve the content of an Index file inside the directory or deny the request if no such file is found.
5. Query string - a string of (usually) name-value pairs with an equal sign = between name and value and an ampersand & between pairs. The query is separated from the path by a question mark ? A query string is used by a web server to generate dynamic content, as opposed to a static file.
6. Anchor - a name identifying a place inside the resource which the browser should jump to (like a bookmark). An anchor is separated from the path or query string by a hash #

Invalid characters in a URL

The most important rule of URLs is that they may not contain spaces. So-called “reserved characters” must be encoded by a percentage sign (%) followed by a hexadecimal number corresponding to each of the character's byte values in UTF-8 encoding. This means that spaces are replaced by %20 and the percent character by %25

Any characters not listed above must be encoded with their UTF-8 byte codes, e.g. the pound sign £ must be encoded as %C2%A3

Inside the query string, however, most reserved characters listed above are allowed unencoded, since only the ?, &, =, + and # characters have special meaning in that context. A plus sign + can be used (instead of %20) to encode a space, and therefore an actual + must be encoded with %2B

Case-sensitivity

The scheme and domain name parts of a URL are always case-insensitive, according to domain name rules. Conversely, web browsers treat the #anchor part as case-sensitive (e.g. #a and #A are two different bookmarks).

The handling of the path and query portions depends on the web server software. The PlanetGIS web server treat these as case-sensitive, so you have to pay attention to the case of your page names and query parameters. Most web servers are case-sensitive because their underlying file systems are case-sensitive (e.g. the Linux operating system).

The home page and index pages

Home page

A home page is the main page of a website and is usually a page at a default location that is served when the user of a web browser only specifies a domain name. When you browse to docs.planetgis.org the web browser automatically sends a request for a page named / on the server designated by the DNS system to serve pages for docs.planetgis.org. Effectively, a / is automatically appended to your request.

Web servers have a special setting that specifies the name of the file that will be served in such a case and some may even list the files found in the directory that has been set as the root for the website. The PlanetGIS web server will not serve any content for such requests and will return a 404 Not Found message unless a page exists with the name Index, which will be your home page.

Index pages

Similarly to the home page, any request that ends in a forward slash / is translated to a request for an Index file inside the directory specified by the request (or a listing of all the files in that location). The PlanetGIS web server always looks for an Index page and will return 404 Not Found if such a page does not exist. For example, the request docs.planetgis.org/Index/ is the same (is translated to) docs.planetgis.org/Index/Index which doesn't exist.

Important note: It is a very common mistake to end a URL that already contains a page's name with / so keep in mind that it means the same as ending the URL with /Index (on a PlanetGIS web server).

The hierarchy of pages

Pages in PlanetGIS do not correspond to files on a file system, but instead to rows in a database table. The name of each page is the full path which will appear in requests to the web server, always starting with /. The Page Manager presents pages in a hierarchical (tree) structure, with the root node denoted by a forward slash:

Notice how the name (path) of the selected page is /Art/Logo52.png, but in the Pages tree on the left, the page is presented as a sub-node of Art/. Nodes in the pages tree with names ending in / are only groupings of pages with paths that start with the portion represented by that node, similar to a folder for files.

Public pages

Pages can be marked as public in order to make them available in PlanetGIS' main menu. A public name can also be specified to show instead of the page path. Public pages will then be listed in the Pages menu:

This is an excellent way to present your reports to users of your GIS project. The menu will link to Planet's built-in web server. For a more advanced menu system or to link to hosted pages (from PlanetGIS App Server or anywhere else) you may want to create a menu page from which the other pages will be linked.

Offline pages

The Offline check box allows you to hide a page. The web server will return 404 Not Found for such pages. Note that you can still preview an offline page in the Preview tab, and while doing that, a web browser will receive the page's content if pointed to your local IP address (as is the case when you click the View button; see The Built-in Web Server below). Offline pages hosted by the App Server will always be unavailable.

Cache control

Cache-control is a header that web servers send along with a requested document, that tells the browser how long a page is likely to stay unaltered on the server. This allows a web browser to avoid re-fetching content that changes infrequently. Most web pages refer to many other resources (images, script libraries and style sheets) which only need to be loaded once while the web page itself should be considered outdated as soon as it is fetched. Reloading a page should only fetch the page again but the browser should keep using other resources already fetched. The Ctrl+F5 keyboard combination tells the browser to refetch everything.

Cache-control should be Don't cache for pages generated with information from a database, but if you don't expect the database to change frequently and want to save bandwidth on a busy server, perhaps 1 hour is a good choice. The default None let's the browser decide, which generally is the same as Don't cache.

For images, a good value is 1 week and some things like fonts hosted by your server, even longer. You can also enter the number of seconds instead of choosing an item in the dropdown list.

Draft pages

If you have a PlanetGIS App Server serving your pages to the Internet or have colleagues accessing the built-in web server on your desktop PlanetGIS, you will be making changes to live web pages. Untested changes could be malfunctioning or perhaps even dangerous. Creating a parallel testing project might make sense in the early stages but is cumbersome for incremental changes. You'd need two data streams, app servers, and perhaps even a sub-domain for the test site. You could do it in an offline project if you are working alone, but you would have the same inconveniences when transferring work between projects.

PlanetGIS solves this by allowing you to create a draft version of each page. Any request to the PlanetGIS web server (local or hosted) that has a path starting with /draft/ (lowercase; if you need your own Draft directory, capitalise the D) tells the web server to load the draft version of the page, if one exists. If no draft version exists, the regular page is served. The server essentially removes the /draft portion from the request after making a note that a draft is being requested.

Relative links (links that don't include the server name and don't have a path starting with /) will get the /draft/ prefix when you follow them, but they will also work for pages that don't have a draft version. Following an absolute link (starting with /) will cause the browser to lose the /draft/ prefix for further links.

Draft pages are meant to be obscure, i.e. a web browser user should not happen onto a draft page without deliberately inserting /draft in the address bar or by clicking on a link that you sent them. Do not make links to draft pages unless those links are also in draft pages and you will remember to change them before publishing the draft. If you use relative links, this is a non-issue.

Creating a draft page

To create a draft version of a page, right-click on the page in the Pages tree to get the popup menu seen in . Then click Create draft. (This menu item will not appear if a page already has a draft version.) The current template and SQL for the page will be copied to its draft version, but other settings are shared between the draft and published versions.

When you are satisfied with the draft, you can click Publish draft to replace the regular content (template and SQL) with the draft version, and the draft copy will be discarded. Similarly, if you don't require the draft and the regular (published) version is acceptable as is, click Remove draft. These actions still require you to Save to make the changes permanent.

Sometimes work on a draft evolves so much that it needs to become a new page, or you might want to start with a new draft without losing your work on the current draft. Save draft as new page will create a new page, initially with the suffix _copy. Current unsaved changes still need to be either saved or discarded, and you will also have to click Remove draft if you want to create a new draft from the original version.

Previous versions of a page

As with all data entities in PlanetGIS, a history is maintained of all changes, and you can restore a page to any previous version. In , you can see all previous versions listed by clicking on the text indicating the person and time that made the most recent modification.

You can click on any previous version to load that version. Planet will warn if you have any current unsaved changes, and you will not lose your latest version if you don't save the newly loaded version. You can look at the preview or other tabs of the previous version and return to your current version. The Cancel button also reloads the latest version.

When reverting to a previous version a few settings are not changed: the page's path, content type and the public and offline options remain the same as the most recent version when you load an older version.

Tab icon

Unless you've specified one in a page's HTML, most browsers will send an extra request for an image named /favicon.ico. This image is used in the browser's tab for your page. Planet will send back this image:

To specify your own image, the easiest is to create a 32x32 pixel PNG and load it into a page with content type Image and name it (e.g.) /Images/favicon-32x32.png. Then link to it in each page's <head> section:

<link rel="icon" type="image/png" href="/Images/favicon-32x32.png" sizes="32x32">

To avoid having to do this for every page, you will need to do it the old way, which is to provide your own /favicon.ico page. Use the Binary content type and load a .ico file for it. Generating an ICO image will require something better than Paint and some skill if you want to put multiple resolution images in it like our favicon.ico above.

An online generator that might be useful is realfavicongenerator.net

QR codes

Planet has a built-in QR code generator. The page is /QRCode and takes two query parameters:

• Code is the value that you want encoded.
• PixelSize is the amount of pixels in the generated image for each block in the QR code.

This example encodes the URL of this documentation. Try scanning it with your phone's camera! (You may need to install Google Lens or a barcode scanner.) The HTML is:

<img src="/QRCode?Code=https://docs.planetgis.org&PixelSize=4">

Attachments

To serve your PlanetGIS attachments as images or download links, there is a page for serving the thumbnail and a page for serving the attachment BLOB:

• /Thumbnail/nnnnnnnnnnnnnn
• /Attachment/nnnnnnnnnnnnnn

nnnnnnnnnnnnnn is the AttachmentId. If you are using Azure for your BLOBs, this simply redirects the browser, otherwise the content is served from your .blobs database. All images in this documentation is served from a PlanetGIS .blobs database on the web server.

To display images in a page, you would use these pages as the src attribute of <img> HTML elements. For example, the following is the HTML for the image in the previous section:

<img src="/Attachment/710587087714313124">

You can also create links that will download attachments (usually if they are not images) so that users can save them to their computers. Here is the HTML for creating a link that can be used to save the image to a user's computer:

The download <a href="/Attachment/710587087714313124" download="Producing PDFs.png" title="Producing PDFs">link</a>

The download link

Maps

shows a map that was rendered on the server a moment ago. To embed live maps into HTML, use /Map as the URL for the <img> element's src or srcset attribute. Since map images are not cached, it is advisable to add the loading="lazy" attribute so that the map is only requested when it comes into view. You can view map images by themselves, and experiment with query parameters by entering map image URLs in your browser's address bar:

Query parameters

The width and height of a map image must be specified as query parameters like this:

<img src="/Map?Width=460&Height=240" loading="lazy">

Remember that query parameters are case-sensitive. Using lowercase will result in a default size for the image. To specify a location on the map, you can use Lat, Lon and Scale to indicate the centre point and extent. Scale must be the number you would normally place after 1:. You can also use Lat and Lon on projected (X,Y) maps (and for such maps you can use X and Y instead, but use cartesian [X=easting, Y=northing] values):

<img src="/Map?Width=400&Height=300&Lat=-26.5&Lon=25&Scale=25000000" loading="lazy">

produces:

You can use a feature in your project as the location (even if it is not displayed on the map), like this:

<img src="/Map?Width=400&Height=300&FeatureId=419225456260227507" loading="lazy">

to get:

With line & polygon features, the extent of the map will be slightly larger than the feature's extent (10% of either the width or height, depending on which dimension has the larger ratio relative to the image's width:height ratio). For a more precise fit, you can add the Zoom query parameter with a value of 0.92:

You can also force a specific scale, but this will rarely be appropriate for features that have varying sizes. For point features, the default scale of 1:5000 is unlikely to be what you want, so you will be specifying a scale in most cases:

<img src="/Map?Width=400&Height=300&FeatureId=419226121981948330&Scale=5000000" loading="lazy">

..centers the map around Pretoria at a scale of 1:5000000:

You can use Scale and Zoom together and the final scale will be close to Scale×Zoom

Scale

Maps are usually rendered with knowledge of the scale of the map (the ratio between the size of features in the image to their actual size in the real world). Layers may not be visible at a certain scale and it is therefore important that the server has an accurate estimation of the final scale of your image. Text height and line widths may be specified in (e.g.) millimetres, so the server also needs an estimation of how many pixels will approximate a millimetre on the receiver's device. Based on the information in the requests in the examples above, the server can only guess that you are using a standard computer screen which has a pixel density of roughly 4 pixels per millimetre.

Cellphones typically have much higher pixel densities and if you have a better computer screen, you have probably set up your computer's operating system to scale text (and therefore most everything else) by a factor of 1.25, 1.5 or more. Web browsers also have their own zoom capability that further affects scale. Pixel density must also be considered when printing or producing PDF documents.

In a later chapter we will look at using JavaScript for making navigable maps, which provides methods to query the browser for scale information. For static map images (and avoiding JavaScript for simplicity), the easiest solution is to provide the browser with a few different URLs to be used at different pixel densities. The following illustrates how pixel density can affect text height and line width while keeping the image sizes the same:

1×:	1.5×	2×:
320×240	480×360	640×480

Note that unless you are viewing this on a large screen, the images in are also scaled to fit, i.e. smaller than their natural size. The Device query parameter tells the server what pixel density to use, relative to a normal screen.

The next thing to understand is that the width and height attributes of the <img> element are not necessarily the pixel (intrinsic) size of the image when rendered. On a good screen, you are likely using 1.25× scaling, and on a great screen or cellphone, a 1.5× or even 2× scaling. Images are quite likely being displayed such that pixels are larger in the images you see than what the screen is capable of displaying (and almost certainly so on a cellphone). For example, all the images in this documentation (other than the maps) are captured on a 4K monitor using a 1.5× scale factor. Each image has a style="max-width:nnnpx" attribute, where nnn is ¹/_1.5 (66.7%) of the actual pixel size. The browser then scales that px^† value, which on another 4K monitor with 1.5 scaling, (normally) produces exactly the optimal level of detail. On a standard screen, images are scaled to fewer pixels and on an even better screen, image pixels still become larger than screen pixels. This is a good compromise without making the images too large in terms of storage and transfer.

The srcset attribute of the <img> element provides the ability to specify different image sources for different resolutions. The web browser will choose only one source to download. The following HTML provides four resolutions and note that the Width and Height query parameters are scaled accordingly:

<img width="400" srcset="/Map?Width=400&Height=300&Zoom=0.75 1x, 
/Map?Width=600&Height=450&Zoom=0.75&Device=1.5 1.5x, 
/Map?Width=800&Height=600&Zoom=0.75&Device=2 2x, 
/Map?Width=1600&Height=1200&Zoom=0.75&Device=4 4x" loading="lazy">

It is important to specify the actual rendered width of the image, 400 scaled pixels in this case, though this could be defined in CSS. You can specify the height, but it is better to leave it to the browser to determine, based on the width:height ratio of the image that is chosen. The srcset attribute contains four options separated by commas and note the 1x (etc.) following each URL, separated by a space. This tells the browser what the relative pixel density will be at each alternate source, so this must match the Device query parameter in the URLs. The following image will be the one that the browser chose to be the best match for your screen:

Your browser chose ? (this information was obtained with JavaScript).

The template tab

The template tab is where your HTML content will go. For CSS, JavaScript and static JSON, the tab simply gets renamed. The content for those types of pages is stored in the same column in the database (pages.Template). Now copy the following HTML from here:

Copy<img src="/Map?Width=640&Height=480">

and paste it into the text box in the Template tab:

The preview tab

Click on the Preview tab to see the rendered HTML:

The View button at the bottom-right serves the same purpose, but launches the page in your default browser.

The SQL tab

The SQL tab is where data extraction is done. As soon as you start entering SQL queries, the JSON tab will become visible, where you will see the results obtained from your SQL queries. For your first page, we will use an SQL query to fetch the FeatureId of the most recently changed feature in your project, and change the template so that that feature will be shown on the map. Copy the following SQL into the $Root node of the SQL tree:

CopySELECT FeatureId FROM features, entities
WHERE features.FeatureId=entities.EntityId AND entities.Track>=0
ORDER BY Timestamp DESC LIMIT 1

Notice that the SQL tab has now become visible.

The JSON tab

The JSON tab shows the results from your SQL queries, as a JSON object:

This is the data object that will be merged into your HTML template, once you turn your static HTML into a Mustache template.

Creating a Mustache template

Now we turn your static HTML into a Mustache template. In the Template tab, change the HTML as follows (the &FeatureId=... is added to the end of the map URL), or copy and replace the entire HTML with this:

Copy<img src="/Map?Width=640&Height=480&FeatureId={{FeatureId}}">

{{FeatureId}} is a Mustache tag which be replaced by the value for Feature in the JSON object:

Now click on the Preview tab to see the result:

The map is now be zoomed to the feature that was modified (geometry or attributes) most recently. also shows that we have finally saved the page (the Pages tree now shows MyPage).

This concludes our Introduction to Pages. In the next chapter we provide a primer on HTML, CSS & JavaScript, followed by a chapter on Mustache templates, before we get to JSON and creating it using SQL queries.