mykomap - A web application for mapping initiatives in the Solidarity & Co-operative Economies
Service: | master |
dev |
---|---|---|
Testing: |
(Also prerequisites section below)
This package is designed to supply the basic source and web assets for a Digital Commons map website. This is tailored for a particular case by a configuration file, and an about.html page, supplied by the consumer site package.
The consumer package should supply a run-script target to build
itself, as in the example below, which uses the mykomap-site-build
script exported by this package.
"scripts": {
"build": "mykomap-site-build -c config -m -s src node_modules/mykomap -d build src/*",
"deploy": "mykomap-site-deploy",
"server": "php -t build/out -S localhost:8080"
},
Additionally, this illustrates two other suggested run-scripts:
deploy
and server
.
The server
run-script illustrates how to run a web server for
testing the site without deploying, for development. It uses the
command-line PHP executable's facility to launch a web
server. (Remember to build the site before running this.)
The deploy
run-script illustrates how to deploy the web site to a
remote location. It uses the mykomap-site-deploy
script, which
internally uses rsync
. (Again, remember to build first.)
Given these, basic usage of a consuming NPM package therefore would look like this:
npm install # Download the dependencies
npm run build # Build and minify the source into builds/out
npm run server # Launch a development web server on http://localhost:8080
And to deploy it, either configure a target specific to your package,
which in this example is called mypackage
:
npm config set mypackage:[email protected]:/some/path
npm run deploy
Or, you can override any configured values via the command line like this:
npm run deploy -- -f some/where -t [email protected]:/some/path
This is to support scripting the deploy step. See the inline documentation within mykomap-site-deploy for further details.
See DEVELOPMENT.md for more information about building and deploying mykomap websites during development of mykomap.
Besides a modern version of NPM and NodeJS, this package needs the following command line tools:
bash
- or possibly any Bourne-shell compatible shell (untested)rsync
- a file transfer utilityphp
- the command-line version of PHP
Additionally, the PHP curl
module needs to be installed.
On Debian and related distros, Bash comes by default, and you can install the others with:
apt install rsync php-cli php-curl
On Windows 10 and above, you can install these via the Windows Subsystem for Linux.
NPM toolchain prerequisites are listed in package.json
and installed
with npm install
.
These need to have a configuration directory containing:
about.html
- containing mark-up which will be displayed on the about tab in the sidebarconfig.json
- configuration parameters, see beloow- <dataset>/ - a directory for each dataset named in the config, containing parameters for the SPARQL query to send to Virtuoso (these will be url-encoded):
query.rq
- thequery
parameter to passdefault-graph-uri.txt
- thedefault-graph-uri
parameter to passendpoint.txt
- the base URL to the Virtuoso server
The NPM mykomap
package needs to be a dependency, which exports the
mykomap-site-build
script.
The package needs to invoke it like this(typically as an npm build script target):
mykomap-site-build -c config -s src -m node_modules/mykomap -d build src/*
Where:
config
is the path to the configuration directory mentioned abovesrc
is an optional path to a custom entry point (index.ts or index.js) and related source codenode_modules/mykomap
is the path to themykomap
package directorybuild
is the directory in which to build the sitesrc/*
expands to a list of directories to include in the build
build
will be populated with two directories:
in
- which contains a RequireJSbuild.js
script and the assets it needs (linked from eleewhere)out
- the generated site content
build/out
can then be served by a (PHP enabled) web server directly,
or packaged for deployment.
This JSON file defines the defaults for a mykomap. Put in at the path
config/config.json
within the NPM project consuming mykomap
(relative to package.json
). Note, because it is JSON, comments are
not allowed and all keys must be delimited by double-quotes. Double
quotes are the only string delimiter.
The valid configuration attributes defined in CONFIG.md.
This is regenerated automatically from the config schema defined in
src/map-app/app/model/config.js) by running the
generate-config-doc
NPM run script. Run this whenever the config changes.
Some of these may be tweaked in various ways, to allow users of the library some flexibility, as follows. Methods are listed in order of increasing priority - if the parameter is defined different ways, the latter override the former.
Only those attributes which are settable (as defined in CONFIG.md) can be overridden. When being set from a context which can only supply string values, these are parsed into a valid value.
For example, you can define the div
like this to override values:
<div id="map-app"
map-app:html-title="My Title"
map-app:initial-bounds="40.712,-74.227,40.774,-74.125"
>
</div>
Here, a config attribute name like initialBounds
should be defined
as map-app:initial-bounds
. There's a namespace prefix to make sure
there can't be clashes with existing HTML attributes. Also,
hyphenation is used instead of capitalisation. The reason for this is
that HTML elements' attributes are case-insensitive. The case can't be
accessed from Javascript because they effectively get downcased before
Javascript even sees them.
For example, you can load the webpage containing the div
with ID
map-app
with query parameters like this:
http://example.com/map?initialBounds=40.712,-74.227,40.774,-74.125
You'll need URL escaping where necessary: a space should be denoted
with a +
, a question mark with %3B
, etc. You can use the
Javascript built-in function encodeURIComponent
to do this. Multiple
parameters should be delimited by ampersands or semi-colons, as usual.
(Note, these parameters are parsed on the client-side in the Javascript, so no extra PHP or Apache scripts needed for it to work.)
The upshot of this is that you can embed the map hosted on (say)
server1.example.com
in a page on server2.example.com
using an
iframe
element in a web page on the latter referring to the
former. The element should set the configuration paramters in the URL
as above. So a super simple example might be:
<!DOCTYPE html>
<html>
<head><!-- ... --></head>
<body>
Blah blah
<iframe src="https://server1.example.com/index.html?initialBounds=40.712,-74.227,40.774,-74.125"></iframe>
</body>
</html>
This example omits all styling and layout, etc., which is out of the scope of this document.
(Note that setting the parent page's title using the htmlTitle
parameter won't work in this context, however, since the title of the
page inside the iframe
isn't visible to the user.)
If you wish to adjust the initial position of the map using the
initialBounds
paramter, here is a rough guide to finding the correct
coordinates.
- Visit https://openstreetmap.org,
- Navigate so that the position of one of the corners of the initial bounds is in view.
- Right-click on the exact location, and
- A pop-up menu appears. Select 'Show address'.
- A side-bar should open showing the latitiude and longitude coordinates of this point.
- Record this, and repeat for the opposite corner.
- Concatenate these numbers with commas, like this:
<lat1>,<long1>,<lat2>,<long2>
- Use this as the
initialBounds
parameter value
If the map-app init()
function defined in app/main.js
is called
directly, a object defining config attributes can be supplied as the
first parameter. From HTML, for example:
<script src="lib/require.js"></script>
<script type="application/javascript">
require(['app/main'], function(main) {
main.init({
initialBounds: [[40.712,-74.227],[40.774,-74.125]],
htmlTitle: "My Title",
});
});
</script>
Note, this actually bypasses any HTML attribute or URL parsing, so if you use this method these won't happen at all. Typically you won't be doing this, as it requires understanding of RequireJS.
Developing mykomap
needs a way to deploy a website using it for
testing. Doing this via a dependency from (say) the mykomap-site-example
project to mykomap
is a bit cumbersome if changes to mykomap
need
to be propagated back to the consuming project via pushing the changes
under test to github.
It is also possible to change a package.json
dependency on mykomap
to a relative path. But this also doesn't work well, because
- This change mustn't be checked in, but more seriously
- It doesn't then pull in the RequireJS dependency correctly.
The latter seems to be a known problem with npm
.
So, a suggested simpler way is to embed a simple project using
mykomap
within a subdirectory ext
, either directly (from within
the same directory as this README):
git clone $PROJECT_URL ext
Or using a symlink:
ln -sf $PROJECT_PATH ext
A pair of npm script tasks to build and serve that directly have been
added to package.json
, so given the above, you can the build and
serve the project like this:
npm install # installs mykomap deps
npm run build # builds the embedded project in ext/build/out/
npm run server # serves the embedded project in ext/build/out/
The website, using the under-development version of mykomap
, will
then be accessible locally via the URL http://localhost:8080
Caveat: the embedded project should not have any extra dependencies
beyond mykomap
, because the npm install
above will not find those.
This package does little in its own right. The following are the script targets it supports.
npm lint
Runs a static analysis of the source, highlighting possible improvements
npm build
Assuming a project consuming mykomap (such as mykomap-site-example)has been
symlinked (or installed) into ext/
, this builds that dependent
project. Primarily for the mykomap developers' convenience, rather
than any users of mykomap.
npm server
As above, a mykomap developers' convenience. Launches a PHP
development web-server, publishing a project consuming mykomap in
ext/
npm generate-config-doc
Developer convenience. Regenerates the documentation for config.json
in CONFIG.md
. Developers should run this when the schema definitions
in config-schema.ts
are changed.
Information which doesn't quite fit in anywhere above.
Sometimes you might want to see just what version a mykomap deployment is, which datasets it is using, or what the SPARQL query is.
Even if this isn't possible to infer from the map, the mykomap configuration resources (described above) can be inspected in a browser.
The following files will be present, at least, and possibly more
with .rq
suffixes, defining other queries.
about.html
config.json
- <dataset>/
query.rq
default-graph-uri.txt
endpoint.txt
The name of the folder <dataset> is up to you, its contents may include additional files, and you may have more than one folder. If the web server does not show file indexes, you will need to know the names of these in advance.
Strictly, the location of these resources is defined
relative to the map-app.js
source code. So using
dotcoop.solidarityeconomy.coop
as an example deployment,
if the map-app.js
file is published here:
https://dotcoop.solidarityeconomy.coop/map-app/map-app.js
...Then the configuration is published in an adjacent directory
configuration
. (Note that the word "configuration" is not
abbreviated here, as it is in the source code directory above.)
Specifically, config.json
will be here:
https://dotcoop.solidarityeconomy.coop/configuration/config.json
So if your app deploys mykomap
code like the example, you can append
configuration/config.json
to the default map URL to find
config.json
and the other resources. Like this:
- https://dotcoop.solidarityeconomy.coop/configuration/about.html
- https://dotcoop.solidarityeconomy.coop/configuration/version.json
- https://dotcoop.solidarityeconomy.coop/configuration/dotcoop/query.rq
- https://dotcoop.solidarityeconomy.coop/configuration/dotcoop/endpoint.txt
- https://dotcoop.solidarityeconomy.coop/configuration/dotcoop/default-graph-uri.txt
Note that before the map-app was converted into this NPM package,
the configuration was located in a slightly different path relative to
map-app/map-app.js
. For example, at the time of writing the Oxford
map predates mykomap
and the configuration can be found here (and the
other files in their respective relative locations):
https://oxford.solidarityeconomy.coop/map-app/configuration/config.json
The location was changed to permit separation of the source code from the configuration files.