Merge pull request #75 from Smithsonian/bug-fixes

Bug fixes and updates

docs/config.toml

@@ -36,7 +36,6 @@ pygmentsUseClasses = true
     url = "/document/"
     weight = 6
 
-
 [params]
     mainSections = ["docs", "explorer", "explorer/api", "story", "document"]
     github_link = "https://github.com/smithsonian/dpo-voyager"

docs/content/explorer/api-examples/_index.md

@@ -0,0 +1,9 @@
+---
+title: "API Examples"
+weight: 230
+---
+
+Below are some functional examples of the Voyager Explorer API in use.
+
+
+

docs/content/explorer/api-examples/background/_index.md

@@ -0,0 +1,44 @@
+---
+title: "API Example: Background Properties"
+summary: "How to use change the component background properties using the API"
+weight: 130
+---
+
+#### Try it out:
+
+{{< explorer "d8c636ce-4ebc-11ea-b77f-2e728ce88125" >}}  <br>
+
+Set a new background style (Solid, LinearGradient, RadialGradient) and click 'Set Style' to apply it to the component.
+Depending on the active style, set the primary and secondary colors and click 'Set Color' to apply.
+{{< option-submit "Style" "Set Style" "setBackgroundStyle" "Solid" "LinearGradient" "RadialGradient">}}
+
+{{< two-color-submit "Color0" "Color1" "setBackgroundColor" "Set Color">}}
+
+#### How it works:
+Below we will break down the javascript from this page that makes use of the [setBackgroundColor() and setBackgroundStyle()](../../api) API functions.
+
+Note that in each case the respective HTML input elements are passed in to provide access to the user input.
+
+{{<highlight js>}}
+function setBackgroundStyle(style) {
+	// Get reference to the Explorer element by id
+	var voyagerElement = document.getElementById("voyager");
+
+	// Call the style function with the value of the 
+	// option input element as the parameter
+	voyagerElement.setBackgroundStyle(style.value);
+}
+{{</highlight>}}
+
+To set the color we follow the same pattern. Pass in the two color inputs and find the Explorer element.  
+
+{{<highlight js>}}
+function setBackgroundColor(color0,color1) {
+	// Get reference to the Explorer element by id
+	var voyagerElement = document.getElementById("voyager");
+
+	// Call the color function with the color input
+	// element current values
+	voyagerElement.setBackgroundColor(color0.value, color1.value);
+}
+{{</highlight>}}

docs/content/explorer/api-examples/camera-orbit/_index.md

@@ -0,0 +1,48 @@
+---
+title: "API Example: Camera Orbit"
+summary: "Use API functions to get or set the Explorer active camera orbit."
+weight: 130
+---
+
+#### Try it out:
+
+{{< explorer "d8c636ce-4ebc-11ea-b77f-2e728ce88125" >}}  <br>
+
+Orient the seen above to the desired view and then click the button below to get the yaw and pitch values.  
+
+{{< control-div "orbit-wrapper" >}}
+	{{< function-button "Get Camera Orbit" "getCameraOrbit" "orbitDisplay">}}
+{{< /control-div >}}  
+
+{{< control-div "orbitDisplay" >}}{{< /control-div >}}  <br>
+
+Enter yaw and pitch angles (degrees) in the boxes below and click the button to immediately update the camera orbit in the example.
+
+{{< input-submit "Set Camera Orbit" "setCameraOrbit" "Yaw" "Pitch">}}  <br>
+
+#### How it works:
+See the annotated javascript from this page below for one way to use the ['get' and 'set' camera orbit functions](../../api).
+
+Getting and displaying camera orbit:
+{{<highlight js>}}
+function getCameraOrbit(displayElement) {
+	// Get Explorer element by id
+	var voyagerElement = document.getElementById("voyager");
+	// Call getCameraOrbit() on the object and store the resulting array
+	const orbitAngles = voyagerElement.getCameraOrbit();
+
+	// Format the angles and assign to the inner text of
+	// the passed in display element
+	displayElement.innerText = "Yaw: " + orbitAngles[0] + "	Pitch: " + orbitAngles[1];
+}
+{{</highlight>}}
+
+Setting new camera orbit values:
+{{<highlight js>}}
+function setCameraOrbit(yaw, pitch) {
+	// Get Explorer element by id
+	var voyagerElement = document.getElementById("voyager");	
+	// Call setCameraOrbit() on the object with the values
+	// of the yaw and pitch input elements as params
+	voyagerElement.setCameraOrbit(yaw.value, pitch.value);
+}{{</highlight>}}

docs/content/explorer/api-examples/get-content/_index.md

@@ -0,0 +1,45 @@
+---
+title: "API Example: Get Content"
+summary: "Use API functions to pull content info from the active Voyager scene."
+weight: 130
+parent: 'api-examples'
+---
+
+#### Try it out:
+
+{{< explorer "d8c646aa-4ebc-11ea-b77f-2e728ce88125" >}}  <br>
+
+Click below to pull article data from the example scene and display a list of the article titles.
+
+{{< control-div "article-wrapper" >}}
+{{< function-button "Get Articles" "getArticles" "articleDisplay">}}
+{{< /control-div >}}
+
+{{< control-div "articleDisplay" >}}{{< /control-div >}}  <br>
+
+#### How it works:
+The annotated javascript below shows how to call the [getArticleData()](../../api) function on the Voyager Explorer object and then parses the response for display. The articles are returned as an array of [Article data objects](https://github.com/Smithsonian/dpo-voyager/blob/master/source/client/models/Article.ts).
+
+{{<highlight js>}}
+function getArticles(displayElement) {
+	// Get Explorer element by id
+	var voyagerElement = document.getElementById("voyager");
+	// Call getArticles() on the object and store the resulting array
+	const articles = voyagerElement.getArticles();
+
+	// For each article in the array, grab the title attribute 
+	// and add it to a string.
+	var articleNames = "";
+	articles.forEach(article => {
+		articleNames += article.title.length > 0 ? article.title 
+			: article.titles["EN"];
+		articleNames += " | ";
+	});
+
+	// Set the innerText of the passed in display element to 
+	// the string of titles.
+	displayElement.innerText = articleNames;
+}
+{{</highlight>}}
+
+

docs/content/explorer/api-examples/toggles/_index.md

@@ -0,0 +1,42 @@
+---
+title: "API Example: Toggle Displays"
+summary: "Use API functions to turn on/off functionality without the native UI"
+weight: 130
+---
+
+#### Try it out:
+
+{{< explorer "d8c62be8-4ebc-11ea-b77f-2e728ce88125" >}}  <br>
+
+Click any of the buttons below to toggle on and of the respective functionality. This is especially useful if you [launch Explorer without the related UI visible](../ui-config/).  
+
+{{< control-div "toggle-wrapper" >}}
+{{< function-button "Annotations" "toggleAnnotations" >}}
+{{< function-button "Tours" "toggleTours" >}}
+{{< function-button "Reader" "toggleReader" >}}
+{{< function-button "Tools" "toggleTools" >}}
+{{< /control-div >}}
+
+#### How it works:
+Each toggle button function starts with finding the Voyager Explorer element based on id and then calls the relevant function on the object. Code examples from this page shown below.
+
+{{<highlight js>}}
+function toggleAnnotations() {
+	var voyagerElement = document.getElementById("voyager");
+	voyagerElement.toggleAnnotations();
+}
+function toggleReader() {
+	var voyagerElement = document.getElementById("voyager");
+	voyagerElement.toggleReader();
+}
+function toggleTours() {
+	var voyagerElement = document.getElementById("voyager");
+	voyagerElement.toggleTours();
+}
+function toggleTools() {
+	var voyagerElement = document.getElementById("voyager");
+	voyagerElement.toggleTools();
+}
+{{</highlight>}}
+
+

docs/content/explorer/api-examples/ui-config/_index.md

@@ -0,0 +1,27 @@
+---
+title: "API Example: UI Configuration"
+summary: "How to use the 'uiMode' attribute to customize the UI displayed on initial load of Explorer."
+weight: 130
+---
+
+#### Try it out:
+
+{{< explorer "d8c636ce-4ebc-11ea-b77f-2e728ce88125" >}}  <br>
+
+Enter any combination of [EUIElements](https://github.com/Smithsonian/dpo-voyager/blob/master/source/client/components/CVInterface.ts) values (none, menu, title, logo, language) in the input box below and click "Update UI" to refresh the page with that UI config. Use “|” to concatenate multiple options.
+{{< input-submit "Update UI" "updateUI" "Elements" >}}
+
+#### How it works:
+The 'uiMode' attribute can either be set directly on the Voyager Explorer component, or can be passed in as a URL parameter. For this example we chose to do the latter and append the parameter to the window location and refresh the page.
+
+{{<highlight js>}}
+function updateUI(textinput) {
+	window.location = window.location.pathname + "?uiMode=" + textinput.value;
+}
+{{</highlight>}}
+
+The code below shows option two with the example tag uiMode attribute directly set to display no UI.  
+
+{{<highlight html>}}
+<voyager-explorer style="display: block; position: relative; height: 450px" root="https://3d-api.si.edu/content/document/d8c636ce-4ebc-11ea-b77f-2e728ce88125/document.json" uiMode="none" dracoroot="https://voyager-dev.glitch.me/draco/" document="document.json"></voyager-explorer>
+{{</highlight>}}

docs/content/explorer/api/_index.md

@@ -1,5 +1,6 @@
 ---
 title: "API Overview"
+summary: A description of the attributes and methods that help you to externally configure and control Voyager Explorer.
 weight: 130
 ---
 
@@ -16,7 +17,8 @@ These attributes configure the initial object load of the component.
 | model        | Valid URL         | URL of a model (supported formats: gltf, glb) to load and display at startup (relative to the root folder).         |
 | geometry     | Valid URL         | URL of a geometry (supported formats: obj, ply) to load and display at startup (relative to the root folder).       |
 | texture      | Valid URL         | If a geometry URL is given, optional URL of a color texture to use with the geometry (relative to the root folder). |
-| dracoRoot	   | Valid URL		   | Absolute path to the Draco compression libraries used for glTF models.
+| dracoRoot	   | Valid URL		   | Absolute path to the Draco compression libraries used for glTF models. Defaults to release package path.
+| fontRoot	   | Valid URL		   | Absolute path to the folder containing bitmap fonts for the app. Defaults to release package path.
 
 ### UI Attributes
 

docs/content/explorer/overview/index.md

@@ -1,7 +1,7 @@
 ---
 title: Overview
 summary: Voyager Explorer - 3D interactive web viewer
-weight: 100
+weight: 120
 ---
 
 The Smithsonian Voyager web explorer has been created specifically for displaying, exploring, and sharing rich 3D data

docs/layouts/index.html

@@ -1,4 +1,4 @@
-{{ define "title" }}Cook Documentation{{ end}}
+{{ define "title" }}Voyager Documentation{{ end}}
 {{ define "header_css" }}{{ end }}
 {{ define "body_classes" }}page-home{{ end }}
 {{ define "header_classes" }}{{ end }}

docs/layouts/shortcodes/control-div.html

@@ -0,0 +1,3 @@
+<div style="text-align: center" {{ printf "id=%s" (.Get 0) | safeHTMLAttr }}>
+{{ .Inner }}
+</div>

docs/layouts/shortcodes/explorer.html

@@ -0,0 +1,65 @@
+<link href="https://3d-api.si.edu/resources/fonts/fonts.css" rel="stylesheet">
+<link href="https://voyager-dev.glitch.me/voyager-explorer.min.css" rel="stylesheet">
+<script src="https://code.jquery.com/pep/0.4.3/pep.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/[email protected]/build/three.min.js"></script>
+<script type="text/javascript" src="https://voyager-dev.glitch.me/voyager-explorer.dev.js"></script>
+<!--script type="text/javascript" src="https://3d-api.si.edu/resources/js/voyager-explorer.min.js"></script-->
+<script>
+var l ="https://3d-api.si.edu/content/document/"+{{ .Get 0 }}+"/document.json";
+document.addEventListener("DOMContentLoaded", function(){
+    document.getElementById("explorer_wrapper").innerHTML = "<voyager-explorer id='voyager' style='display: block; position: relative; height: 450px' root='"+l+"' dracoRoot='https://voyager-dev.glitch.me/draco/' fontRoot='https://3d-api.si.edu/resources/fonts/' document='document.json'></voyager-explorer>";
+});
+</script>
+<div id="explorer_wrapper" width="600" height="450">
+</div>
+<script>
+function updateUI(textInput) {
+	window.location = window.location.pathname + "?uiMode=" + textInput.value;
+}
+function setBackgroundColor(color0,color1) {
+	var voyagerElement = document.getElementById("voyager");
+	voyagerElement.setBackgroundColor(color0.value, color1.value);
+}
+function setBackgroundStyle(style) {
+	var voyagerElement = document.getElementById("voyager");
+	voyagerElement.setBackgroundStyle(style.value);
+}
+function toggleAnnotations() {
+	var voyagerElement = document.getElementById("voyager");
+	voyagerElement.toggleAnnotations();
+}
+function toggleReader() {
+	var voyagerElement = document.getElementById("voyager");
+	voyagerElement.toggleReader();
+}
+function toggleTours() {
+	var voyagerElement = document.getElementById("voyager");
+	voyagerElement.toggleTours();
+}
+function toggleTools() {
+	var voyagerElement = document.getElementById("voyager");
+	voyagerElement.toggleTools();
+}
+function getCameraOrbit(displayElement) {
+	var voyagerElement = document.getElementById("voyager");
+	const orbitAngles = voyagerElement.getCameraOrbit();
+
+	displayElement.innerText = "Yaw: " + orbitAngles[0] + "	Pitch: " + orbitAngles[1];
+}
+function setCameraOrbit(yaw, pitch) {
+	var voyagerElement = document.getElementById("voyager");	
+	voyagerElement.setCameraOrbit(yaw.value, pitch.value);
+}
+function getArticles(displayElement) {
+	var voyagerElement = document.getElementById("voyager");
+	const articles = voyagerElement.getArticles();
+
+	var articleNames = "";
+	articles.forEach(article => {
+		articleNames += article.title.length > 0 ? article.title : article.titles["EN"];
+		articleNames += " | ";
+	});
+
+	displayElement.innerText = articleNames;
+}
+</script>

docs/layouts/shortcodes/function-button.html

@@ -0,0 +1 @@
+<button class="sc-button" style="display: inline-block;" {{ printf "onclick=%s(%s)" (.Get 1) (.Get 2)| safeHTMLAttr }}>{{ .Get 0 }}</button>

docs/layouts/shortcodes/input-submit.html

@@ -0,0 +1,9 @@
+<div style="text-align: center">
+	{{ $fields :=  after 2 .Params }}
+	{{ $fieldString := delimit $fields "," }}
+	{{ range $fields }}
+	<label style="display: inline-block;" {{ printf "for=%s" (.) | safeHTMLAttr }}>{{ . }}:</label>
+	<input class="sc-param" style="display: inline-block;" {{ printf "id=%s" (.) | safeHTMLAttr }}></input>
+	{{ end }}
+	<button class="sc-button" style="display: inline-block;" {{ printf "onclick=%s(%s)" (.Get 1) $fieldString | safeHTMLAttr }}>{{ .Get 0 }}</button>
+</div>

docs/layouts/shortcodes/option-submit.html

@@ -0,0 +1,11 @@
+<div style="text-align: center"> 
+  <div style="display: inline-block">
+	<select {{ printf "id=%s" (.Get 0) | safeHTMLAttr }}>
+	  {{ $options :=  after 3 .Params }}
+	  {{ range $options }}
+	  <option value="{{.}}">{{.}}</option>
+	  {{ end }}
+	</select>
+  </div>
+  <button class="sc-button" style="display: inline-block;" {{ printf "onclick=%s(%s)" (.Get 2) (.Get 0)| safeHTMLAttr }}>{{ .Get 1 }}</button>
+</div>

docs/layouts/shortcodes/two-color-submit.html

@@ -0,0 +1,7 @@
+<div style="text-align: center">
+	<label style="display: inline-block;" for="color0">{{ .Get 0 }}:</label>
+	<input style="display: inline-block;" type="color" {{ printf "id=%s" (.Get 0) | safeHTMLAttr }}>
+	<label style="display: inline-block;" for="color1">{{ .Get 1 }}:</label>
+	<input style="display: inline-block;" type="color" {{ printf "id=%s" (.Get 1) | safeHTMLAttr }}>
+	<button class="sc-button" style="display: inline-block; margin-right: 10px" {{ printf "onclick=%s(%s,%s)" (.Get 2) (.Get 0) (.Get 1) | safeHTMLAttr }}>{{ .Get 3 }}</button>
+</div>