From 0491b526427c357404eb6215a3b3a12853b8381d Mon Sep 17 00:00:00 2001 From: pietervdvn Date: Wed, 24 Mar 2021 02:01:04 +0100 Subject: [PATCH] Add doc generation --- Customizations/JSON/LayerConfig.ts | 14 +++++---- Customizations/JSON/LayoutConfig.ts | 2 +- Docs/CalculatedTags.md | 31 +++++++++++++++++++- Docs/CalculatingExtraTags.md | 22 --------------- Logic/MetaTagging.ts | 44 +++++++++++++++++++++++++++-- Logic/SimpleMetaTagger.ts | 2 +- scripts/generateDocs.ts | 8 ++++-- 7 files changed, 87 insertions(+), 36 deletions(-) delete mode 100644 Docs/CalculatingExtraTags.md diff --git a/Customizations/JSON/LayerConfig.ts b/Customizations/JSON/LayerConfig.ts index d8401ea..edcb072 100644 --- a/Customizations/JSON/LayerConfig.ts +++ b/Customizations/JSON/LayerConfig.ts @@ -54,8 +54,8 @@ export default class LayerConfig { tagRenderings: TagRenderingConfig []; constructor(json: LayerConfigJson, - official: boolean= true, - context?: string) { + context?: string, + official: boolean = true,) { context = context + "." + json.id; const self = this; this.id = json.id; @@ -92,7 +92,9 @@ export default class LayerConfig { this.calculatedTags = undefined; if (json.calculatedTags !== undefined) { - console.warn("Unofficial theme with custom javascript! This is a security risk") + if (!official) { + console.warn(`Unofficial theme ${this.id} with custom javascript! This is a security risk`) + } this.calculatedTags = []; for (const key in json.calculatedTags) { this.calculatedTags.push([key, json.calculatedTags[key]]) @@ -212,11 +214,11 @@ export default class LayerConfig { } - public CustomCodeSnippets(): string[]{ - if(this.calculatedTags === undefined){ + public CustomCodeSnippets(): string[] { + if (this.calculatedTags === undefined) { return [] } - + return this.calculatedTags.map(code => code[1]); } diff --git a/Customizations/JSON/LayoutConfig.ts b/Customizations/JSON/LayoutConfig.ts index b5da631..7e587ae 100644 --- a/Customizations/JSON/LayoutConfig.ts +++ b/Customizations/JSON/LayoutConfig.ts @@ -106,7 +106,7 @@ export default class LayoutConfig { } // @ts-ignore - return new LayerConfig(layer, official,`${this.id}.layers[${i}]`) + return new LayerConfig(layer,`${this.id}.layers[${i}]`, official) }); // ALl the layers are constructed, let them share tags in now! diff --git a/Docs/CalculatedTags.md b/Docs/CalculatedTags.md index 8c16b1f..9731592 100644 --- a/Docs/CalculatedTags.md +++ b/Docs/CalculatedTags.md @@ -1,3 +1,8 @@ +Metatags +-------- + +Metatags are extra tags available, in order to display more data or to give better questions.The are calculated automatically on every feature when the data arrives in the webbrowser. This document gives an overview of the available metatags + ### \_lat, \_lon The latitude and longitude of the point (or centerpoint in the case of a way/area) @@ -24,4 +29,28 @@ Legacy for a specific project calculating the needed width for safe traffic on a ### \_now:date, \_now:datetime, \_loaded:date, \_loaded:\_datetime -Adds the time that the data got loaded - pretty much the time of downloading from overpass. The format is YYYY-MM-DD hh:mm, aka 'sortable' aka ISO-8601-but-not-entirely \ No newline at end of file +Adds the time that the data got loaded - pretty much the time of downloading from overpass. The format is YYYY-MM-DD hh:mm, aka 'sortable' aka ISO-8601-but-not-entirely + +Calculating tags with Javascript +-------------------------------- + +In some cases, it is useful to have some tags calculated based on other properties. Some useful tags are available by default (e.g. **\_lat**, **lon**, **\_country**), as detailed above. + +It is also possible to calculate your own tags - but this requires some javascript knowledge. + +Before proceeding, some warnings: + +* DO NOT DO THIS AS BEGINNER +* **Only do this if all other techniques fail**. This should _not_ be done to create a rendering effect, only to calculate a specific value +* **THIS MIGHT BE DISABLED WITHOUT ANY NOTICE ON UNOFFICIAL THEMES**. As unofficial themes might be loaded from the internet, this is the equivalent of injecting arbitrary code into the client. It'll be disabled if abuse occurs. + +In the layer object, add a field **calculatedTags**, e.g.: + +"calculatedTags": { "\_someKey": "javascript-expression", "name": "feat.properties.name ?? feat.properties.ref ?? feat.properties.operator", "\_distanceCloserThen3Km": "feat.distanceTo( some\_lon, some\_lat) < 3 ? 'yes' : 'no'" } + +### distanceTo + +Calculates the distance between the feature and a specified point + +* longitude +* latitude \ No newline at end of file diff --git a/Docs/CalculatingExtraTags.md b/Docs/CalculatingExtraTags.md deleted file mode 100644 index 93dd92b..0000000 --- a/Docs/CalculatingExtraTags.md +++ /dev/null @@ -1,22 +0,0 @@ -# Extra, automatically created tags - -In some cases, it is useful to have some tags calculated based on other properties. - -Some useful tags are available by default (e.g. `_lat`, `_lon`, `_country`) and are always available (have a lookt at [CalculatedTags.md](CalculatedTags.md) to see an overview). - -It is also possible to calculate your own tags - but this requires some javascript knowledge. - -Before proceeding, some warnings: - -- **DO NOT DO THIS AS BEGINNER** -- **Only do this if all other techniques fail**. This should _not_ be done to create a rendering effect, only to calculate a specific vaue -- **THIS MIGHT BE DISABLED WITHOUT ANY NOTICE ON UNOFFICIAL THEMES**. As unofficial themes might be loaded from the internet, this is the equivalent of injecting arbitrary code into the client. It'll be disabled if abuse occurs. - -In the layer object, add a field `calculatedTags`, e.g.: - -``` - "calculatedTags": { - "_someKey": "javascript-expression", - "name": "tags.name ?? tags.ref ?? tags.operator" - } -``` diff --git a/Logic/MetaTagging.ts b/Logic/MetaTagging.ts index 8867146..2249471 100644 --- a/Logic/MetaTagging.ts +++ b/Logic/MetaTagging.ts @@ -1,10 +1,35 @@ import {GeoOperations} from "./GeoOperations"; import LayerConfig from "../Customizations/JSON/LayerConfig"; import SimpleMetaTagger from "./SimpleMetaTagger"; +import {UIElement} from "../UI/UIElement"; +import Combine from "../UI/Base/Combine"; export class ExtraFunction { - static readonly doc: string = "When the feature is downloaded, some extra tags can be calculated by a javascript snippet. The feature is passed as 'feat'; there are a few functions available on it to handle it - apart from 'feat.tags' which is a classic object containing all the tags." + static readonly intro = `

Calculating tags with Javascript

+ +

In some cases, it is useful to have some tags calculated based on other properties. Some useful tags are available by default (e.g. _lat, lon, _country), as detailed above.

+ +

It is also possible to calculate your own tags - but this requires some javascript knowledge.

+ +Before proceeding, some warnings: + + +In the layer object, add a field calculatedTags, e.g.: + +
+ "calculatedTags": { + "_someKey": "javascript-expression", + "name": "feat.properties.name ?? feat.properties.ref ?? feat.properties.operator", + "_distanceCloserThen3Km": "feat.distanceTo( some_lon, some_lat) < 3 ? 'yes' : 'no'" + } +
+` + private static DistanceToFunc = new ExtraFunction( "distanceTo", "Calculates the distance between the feature and a specified point", @@ -16,7 +41,7 @@ export class ExtraFunction { } } ) - private static readonly allFuncs : ExtraFunction[] = [ExtraFunction.DistanceToFunc]; + private static readonly allFuncs: ExtraFunction[] = [ExtraFunction.DistanceToFunc]; private readonly _name: string; private readonly _args: string[]; private readonly _doc: string; @@ -36,6 +61,21 @@ export class ExtraFunction { } } + public static HelpText(): UIElement { + return new Combine([ + ExtraFunction.intro, + ...ExtraFunction.allFuncs.map(func => + new Combine([ + "

" + func._name + "

", + func._doc, + "" + ]) + ) + ]); + } + public PatchFeature(feature: any) { feature[this._name] = this._f(feature); } diff --git a/Logic/SimpleMetaTagger.ts b/Logic/SimpleMetaTagger.ts index d303654..d5ae1bd 100644 --- a/Logic/SimpleMetaTagger.ts +++ b/Logic/SimpleMetaTagger.ts @@ -309,7 +309,7 @@ export default class SimpleMetaTagger { static HelpText(): UIElement { const subElements: UIElement[] = [ new Combine([ - "

Metatags

", + "

Metatags

", "Metatags are extra tags available, in order to display more data or to give better questions.", "The are calculated automatically on every feature when the data arrives in the webbrowser. This document gives an overview of the available metatags" ]) diff --git a/scripts/generateDocs.ts b/scripts/generateDocs.ts index 6633223..4f29928 100644 --- a/scripts/generateDocs.ts +++ b/scripts/generateDocs.ts @@ -1,10 +1,13 @@ import {Utils} from "../Utils"; +Utils.runningFromConsole = true; import SpecialVisualizations from "../UI/SpecialVisualizations"; import {writeFileSync} from "fs"; import {UIElement} from "../UI/UIElement"; import SimpleMetaTagger from "../Logic/SimpleMetaTagger"; +import {ExtraFunction} from "../Logic/MetaTagging"; +import Combine from "../UI/Base/Combine"; + -Utils.runningFromConsole = true; const TurndownService = require('turndown') @@ -15,8 +18,7 @@ function WriteFile(filename, html: UIElement) : void { } WriteFile("./Docs/SpecialRenderings.md", SpecialVisualizations.HelpMessage) -WriteFile("./Docs/CalculatedTags.md", SimpleMetaTagger.HelpText()) - +WriteFile("./Docs/CalculatedTags.md", new Combine([SimpleMetaTagger.HelpText(), ExtraFunction.HelpText()])) console.log("Generated docs")