veyron-browser: Preliminary Help Content
I am adding some preliminary topics for help content.
We need to plan how to organize this help page.
- Basic help page with a tabbed layout
- Modification of the help page to properly style parsed markdown
- Modification of our custom browserify transform system
- Filler content for each help page
Change-Id: I52a95b48651885d5bb578d27b4f1754a0a77a138
diff --git a/Makefile b/Makefile
index 068f68f..a57e053 100644
--- a/Makefile
+++ b/Makefile
@@ -22,7 +22,7 @@
# All JS and CSS files except build.js and third party.
BROWSERIFY_FILES = $(shell find src -name "*.js" -o -name "*.css")
-BROWSERIFY_OPTIONS = --transform ./css-transform --debug
+BROWSERIFY_OPTIONS = --transform ./main-transform --debug
# All Go and VDL files.
GO_FILES = $(shell find go -name "*.go")
diff --git a/css-transform.js b/css-transform.js
index f94c0e2..ae2ad44 100644
--- a/css-transform.js
+++ b/css-transform.js
@@ -4,23 +4,27 @@
var reworkVars = require('rework-vars');
var reworkImport = require('rework-import');
-module.exports = transform;
+module.exports = {
+ canTransform: isCss,
+ transform: transform
+};
+/*
+ * Transform the given css file by compiling it with rework.
+ */
function transform(file) {
- if (path.extname(file) !== '.css') {
- return through2();
- }
-
var contents = [];
return through2(write, flush);
+ // Simply collect string fragments of the css file.
function write(data, encoding, callback) {
var string = data.toString();
contents.push(string);
callback();
}
+ // Reconstruct the css and then compile it.
function flush(callback) {
var string = contents.join('');
var css = compile(string);
@@ -29,7 +33,7 @@
}
}
-/* Compiles the given CSS string using rework */
+/* Compiles the given CSS string using rework. */
function compile(string) {
var css = rework(string)
.use(reworkImport({
@@ -40,4 +44,9 @@
compress: true
});
return css;
+}
+
+/* Determines if the filetype is css. */
+function isCss(file) {
+ return path.extname(file) === '.css';
}
\ No newline at end of file
diff --git a/main-transform.js b/main-transform.js
new file mode 100644
index 0000000..8e03ea1
--- /dev/null
+++ b/main-transform.js
@@ -0,0 +1,27 @@
+var through2 = require('through2');
+
+module.exports = transform;
+
+/*
+ * A list of specialist transformers targetting specific filetypes.
+ */
+var transformers = Object.freeze([
+ require('./css-transform'),
+ require('./md-transform')
+]);
+
+/*
+ * Apply a transform to any given file. Most files are simply passed through,
+ * but a matching specialist transformer applies its transform function instead.
+ */
+function transform(file) {
+ // Attempt to find a specialist transformer to apply their transformation.
+ for (var i = 0; i < transformers.length; i++) {
+ if (transformers[i].canTransform(file)) {
+ return transformers[i].transform(file);
+ }
+ }
+
+ // If there's no result, pass the file through normally.
+ return through2();
+}
\ No newline at end of file
diff --git a/md-transform.js b/md-transform.js
new file mode 100644
index 0000000..0dba111
--- /dev/null
+++ b/md-transform.js
@@ -0,0 +1,36 @@
+var parseMarkdown = require('marked');
+var path = require('path');
+var through2 = require('through2');
+
+module.exports = {
+ canTransform: isMarkdown,
+ transform: transform
+};
+
+/*
+ * Transform the given markdown file by parsing the markdown file.
+ */
+function transform(file) {
+ var contents = [];
+
+ return through2(write, flush);
+
+ // Simply collect string fragments of the markdown file.
+ function write(data, encoding, callback) {
+ var string = data.toString();
+ contents.push(string);
+ callback();
+ }
+
+ // Reconstruct the markdown and then parse it.
+ function flush(callback) {
+ var string = contents.join('');
+ this.push('module.exports = ' + JSON.stringify(parseMarkdown(string)));
+ callback();
+ }
+}
+
+/* Determines if the filetype is markdown. */
+function isMarkdown(file) {
+ return path.extname(file) === '.md';
+}
\ No newline at end of file
diff --git a/package.json b/package.json
index 5174990..5b0691e 100644
--- a/package.json
+++ b/package.json
@@ -26,6 +26,7 @@
"insert-css": "^0.2.0",
"json-stable-stringify": "^1.0.0",
"localforage": "^1.0.2",
+ "marked": "^0.3.2",
"mercury": "^6.0.1",
"routes": "^1.2.0",
"vis": "^3.1.0",
diff --git a/src/app.js b/src/app.js
index b06e77a..811beab 100644
--- a/src/app.js
+++ b/src/app.js
@@ -1,19 +1,21 @@
var guid = require('guid');
var mercury = require('mercury');
var onDocumentReady = require('./lib/document-ready');
-var viewport = require('./components/viewport/index');
var router = require('./router');
var debug = require('./components/debug/index');
var browse = require('./components/browse/index');
var error = require('./components/error/index');
+var help = require('./components/help/index');
+var viewport = require('./components/viewport/index');
var errorRoute = require('./routes/error');
onDocumentReady(function startApp() {
var browseComponent = browse();
- var viewportComponent = viewport();
var errorComponent = error();
var debugComponent = debug();
+ var helpComponent = help();
+ var viewportComponent = viewport();
// Top level state
var state = mercury.struct({
@@ -28,12 +30,18 @@
*/
pageKey: mercury.value('')
}),
+
/*
- * Veyron Namespace Browsing related states
+ * Veyron Namespace Browsing related state
*/
browse: browseComponent.state,
/*
+ * Veyron Namespace Help related state
+ */
+ help: helpComponent.state,
+
+ /*
* State of the viewport component
*/
viewport: viewportComponent.state,
@@ -62,6 +70,11 @@
'browse',
/*
+ * Veyron Namespace Help related events
+ */
+ 'help',
+
+ /*
* Events of the viewport component
*/
'viewport'
@@ -78,6 +91,7 @@
'navigate'
]);
events.browse = browseComponent.events;
+ events.help = helpComponent.events;
events.viewport = viewportComponent.events;
// Wire Events
@@ -96,8 +110,14 @@
mercury.app(document.body, state, render);
function wireEvents() {
+ // TODO(aghassemi): Make these events global.
+ // Hook up external browse events.
events.browse.error(onError);
events.browse.toast(onToast);
+
+ // Hook up external help events.
+ events.help.navigate = events.navigation.navigate;
+ events.help.error(onError);
}
/*
diff --git a/src/components/browse/index.css b/src/components/browse/index.css
index 6e9b2c1..51bc650 100644
--- a/src/components/browse/index.css
+++ b/src/components/browse/index.css
@@ -25,6 +25,9 @@
background-color: var(--color-grey-light);
box-shadow: none;
}
+.browse-details-sidebar::shadow #dropShadow {
+ display: none;
+}
.browse-details-sidebar::shadow #mainContainer {
background-color: var(--color-grey-light);
border-left: solid 1px var(--color-divider);
diff --git a/src/components/browse/item-details/index.css b/src/components/browse/item-details/index.css
index e34b865..0f74f2e 100644
--- a/src/components/browse/item-details/index.css
+++ b/src/components/browse/item-details/index.css
@@ -1,39 +1,10 @@
@import "common-style/sizes.css";
@import "common-style/theme.css";
-
-.tabs {
- box-shadow: var(--shadow-bottom);
-}
-
-.tabs::shadow #selectionBar {
- background-color: var(--color-bright);
-}
-
-.tab {
- background-color: var(--color-main);
- color: var(--color-text-primary-invert);
-}
-
-.tab::shadow #ink {
- color: var(--color-bright);
-}
-
-.browse-details-sidebar::shadow #dropShadow {
- display: none;
-}
-
-.tab-content {
- padding: 0.5em;
-}
-
-:not(.core-selected).tab-content {
- display: none;
-}
+@import "common-style/tabs.css";
.field {
font-size: 0.9em;
margin-bottom: 0.75em;
-
}
.field h4 {
diff --git a/src/components/common-style/tabs.css b/src/components/common-style/tabs.css
new file mode 100644
index 0000000..931328f
--- /dev/null
+++ b/src/components/common-style/tabs.css
@@ -0,0 +1,26 @@
+@import "./theme.css";
+
+.tabs {
+ box-shadow: var(--shadow-bottom);
+}
+
+.tabs::shadow #selectionBar {
+ background-color: var(--color-bright);
+}
+
+.tab {
+ background-color: var(--color-main);
+ color: var(--color-text-primary-invert);
+}
+
+.tab::shadow #ink {
+ color: var(--color-bright);
+}
+
+.tab-content {
+ padding: 0.5em;
+}
+
+:not(.core-selected).tab-content {
+ display: none;
+}
\ No newline at end of file
diff --git a/src/components/help/constants.js b/src/components/help/constants.js
new file mode 100644
index 0000000..1c8b4a7
--- /dev/null
+++ b/src/components/help/constants.js
@@ -0,0 +1,47 @@
+var helpRoute = require('../../routes/help');
+
+var tabKeys = Object.freeze({
+ MAIN: 'main', // Describes the Veyron Browser to new users.
+ BROWSE: 'browse', // Introduces how to browse the namespace.
+ DETAILS: 'details', // Defines service information and icons.
+ METHODS: 'methods', // Explains how to make RPCs.
+ FAQ: 'faq' // Frequently asked questions and contact information.
+});
+
+var sections = Object.freeze(new Map([
+ [tabKeys.MAIN, {
+ index: 0,
+ header: 'Main Help',
+ markdownContent: require('./content/main.md'),
+ path: helpRoute.createUrl(tabKeys.MAIN)
+ }],
+ [tabKeys.BROWSE, {
+ index: 1,
+ header: 'How to Browse',
+ markdownContent: require('./content/browse.md'),
+ path: helpRoute.createUrl(tabKeys.BROWSE)
+ }],
+ [tabKeys.DETAILS, {
+ index: 2,
+ header: 'What You See',
+ markdownContent: require('./content/details.md'),
+ path: helpRoute.createUrl(tabKeys.DETAILS)
+ }],
+ [tabKeys.METHODS, {
+ index: 3,
+ header: 'Talk to Services',
+ markdownContent: require('./content/methods.md'),
+ path: helpRoute.createUrl(tabKeys.METHODS)
+ }],
+ [tabKeys.FAQ, {
+ index: 4,
+ header: 'FAQ',
+ markdownContent: require('./content/faq.md'),
+ path: helpRoute.createUrl(tabKeys.FAQ)
+ }]
+]));
+
+module.exports = {
+ tabKeys: tabKeys,
+ sections: sections
+};
\ No newline at end of file
diff --git a/src/components/help/content/browse.md b/src/components/help/content/browse.md
new file mode 100644
index 0000000..73f62a4
--- /dev/null
+++ b/src/components/help/content/browse.md
@@ -0,0 +1,14 @@
+How to Browse the Namespace
+===========================
+
+This tab describes the many ways in which the user can browse the namespace. A
+few examples should be included.
+
+Topics
+------
+* namespace items
+* namespace root search box
+* glob search box and how glob works
+* breadcrumbs
+* visualization page
+* how to setup shortcuts
\ No newline at end of file
diff --git a/src/components/help/content/details.md b/src/components/help/content/details.md
new file mode 100644
index 0000000..815e84d
--- /dev/null
+++ b/src/components/help/content/details.md
@@ -0,0 +1,12 @@
+How to Interpret What You See
+=============================
+
+This tab describes what the user will see when looking at a service item and why
+it is important.
+
+Topics
+------
+* its name
+* service types and icons
+* service methods (and output)
+* (potentially more information will be shown later)
\ No newline at end of file
diff --git a/src/components/help/content/faq.md b/src/components/help/content/faq.md
new file mode 100644
index 0000000..6f58912
--- /dev/null
+++ b/src/components/help/content/faq.md
@@ -0,0 +1,25 @@
+Frequently Asked Questions
+==========================
+
+TODO(alexfandrianto): The anchortext links don't work. We should think of an
+alternate FAQ setup or properly handle these links.
+
+1. [I can't do X Y or Z!](#/help/faq/1)
+2. [How can I contribute to the Namespace Browser?](#/help/faq/2)
+3. [How can I learn more about Veyron?](#/help/faq/3)
+
+I can't do X Y or Z!<a name="1"></a>
+--------------------
+
+That's a shame.
+
+How can I contribute to the Namespace Browser?<a name="2"></a>
+----------------------------------------------
+
+Visit us on github to make suggestions, report bugs, or contribute pull
+requests. INSERT A LINK
+
+How can I learn more about Vanadium?<a name="3"></a>
+------------------------------------
+
+Go to the Vanadium website. INSERT A LINK.
\ No newline at end of file
diff --git a/src/components/help/content/main.md b/src/components/help/content/main.md
new file mode 100644
index 0000000..a3f579d
--- /dev/null
+++ b/src/components/help/content/main.md
@@ -0,0 +1,35 @@
+Main Help Page
+==============
+
+Introduction
+------------
+
+The Namespace Browser is a tool to browse and interact with running services.
+
+How to Browse
+-------------
+
+(BRIEF DESCRIPTION ABOUT WHAT EXPLORING THE NAMESPACE IS ABOUT.)
+
+See the [help topic](#/help/browse) for more details.
+
+What You See
+------------
+
+(BRIEF DESCRIPTION ABOUT INFORMATION YOU MIGHT SEE WHILE USING THIS TOOL.)
+
+See the [help topic](#/help/details) for more details.
+
+Talk to Services
+----------------
+
+(BRIEF DESCRIPTION ABOUT WHAT INTERACTING WITH SERVICES INVOLVES.)
+
+See the [help topic](#/help/methods) for more details.
+
+Conclusion
+----------
+
+(SAY SOMETHING REASSURING.)
+
+See the [help topic](#/help/faq) to see a listing of frequently asked questions.
\ No newline at end of file
diff --git a/src/components/help/content/methods.md b/src/components/help/content/methods.md
new file mode 100644
index 0000000..665e638
--- /dev/null
+++ b/src/components/help/content/methods.md
@@ -0,0 +1,11 @@
+How to Talk to Services
+=======================
+
+This tab describes how the user can make method calls to a service item.
+
+Topics
+------
+* how to run simple RPCs
+* how to fill out an RPC form (including syntax)
+* where the output goes
+* how to save invocations
\ No newline at end of file
diff --git a/src/components/help/index.css b/src/components/help/index.css
new file mode 100644
index 0000000..27af845
--- /dev/null
+++ b/src/components/help/index.css
@@ -0,0 +1,32 @@
+@import "common-style/theme.css";
+@import "common-style/tabs.css";
+
+.markdown {
+ padding: 0.5em;
+}
+
+.markdown h1 {
+ text-align: center;
+}
+
+.markdown h2 {
+ margin-top: 0.75em;
+ margin-bottom: 0.25em;
+}
+
+/* Recover some sane version of link color. */
+.markdown a {
+ color: -webkit-link;
+ text-decoration: underline;
+}
+
+/* Recover some sane version of list bullets. */
+.markdown ul, .markdown ol {
+ padding-left: 2em;
+}
+.markdown ul li {
+ list-style: disc outside none;
+}
+.markdown ol li {
+ list-style: decimal outside none;
+}
\ No newline at end of file
diff --git a/src/components/help/index.js b/src/components/help/index.js
index b60b2f0..5e02b3f 100644
--- a/src/components/help/index.js
+++ b/src/components/help/index.js
@@ -1,5 +1,12 @@
var mercury = require('mercury');
var h = mercury.h;
+var AttributeHook = require('../../lib/mercury/attribute-hook');
+var insertCss = require('insert-css');
+var css = require('./index.css');
+var constants = require('./constants.js');
+
+var tabKeys = constants.tabKeys;
+var sections = constants.sections;
module.exports = create;
module.exports.render = render;
@@ -7,9 +14,49 @@
/*
* Help view
*/
-function create() {}
+function create() {
+ var state = mercury.varhash({
+ selectedTab: mercury.value(tabKeys.MAIN)
+ });
+ var events = mercury.input([
+ 'error', // Will be wired up by the application.
+ 'navigate' // Will be wired up by the application.
+ ]);
-function render() {
- // TODO(aghassemi)
- return h('div.empty', 'Help will come one day.');
+ return {
+ state: state,
+ events: events
+ };
+}
+
+/*
+ * Draws the help page, which consists of a tabbed layout and the selected tab's
+ * help content. Content comes from a parsed markdown file.
+ */
+function render(state, events) {
+ insertCss(css);
+
+ // Render each help tab, as defined by the sections.
+ var tabs = [];
+ sections.forEach(function(section, key) {
+ var tab = h('paper-tab.tab', {
+ 'tabKey': key,
+ 'ev-click': mercury.event(events.navigate, {
+ 'path': section.path
+ })
+ }, section.header);
+ tabs.push(tab);
+ });
+
+ // Show the tabs followed by the content of the selected help tab.
+ return [
+ h('paper-tabs.tabs', {
+ 'selectedProperty': new AttributeHook('tabKey'),
+ 'selected': new AttributeHook(sections.get(state.selectedTab).index),
+ 'noink': new AttributeHook(true)
+ }, tabs),
+ h('.tab-content.core-selected', h('.markdown', {
+ 'innerHTML': sections.get(state.selectedTab).markdownContent
+ }))
+ ];
}
\ No newline at end of file
diff --git a/src/components/help/selectTab.js b/src/components/help/selectTab.js
new file mode 100644
index 0000000..f992b7b
--- /dev/null
+++ b/src/components/help/selectTab.js
@@ -0,0 +1,19 @@
+var sections = require('./constants').sections;
+
+module.exports = selectTab;
+
+/*
+ * Exported function that sets the given state to the given tabKey.
+ * If there is an error, however, the error event is run.
+ */
+function selectTab(state, events, tabKey) {
+ // If the tab is invalid, go to the error page.
+ if (sections.get(tabKey) === undefined) {
+ // TODO(aghassemi): Add 404 error.
+ // events.error(type.404);
+ events.error(new Error('Invalid help page: ' + tabKey));
+ } else {
+ // Since the tabKey is valid, the selectedTab can be updated.
+ state.selectedTab.set(tabKey);
+ }
+}
\ No newline at end of file
diff --git a/src/components/main-content/index.js b/src/components/main-content/index.js
index 7fa8521..ebaa676 100644
--- a/src/components/main-content/index.js
+++ b/src/components/main-content/index.js
@@ -44,7 +44,7 @@
case 'browse':
return Browse.render(state.browse, events.browse, events.navigation);
case 'help':
- return Help.render();
+ return Help.render(state.help, events.help);
case 'error':
return ErrorPage.render(state.error);
case 'visualize':
diff --git a/src/routes/help.js b/src/routes/help.js
index ca2add0..7ddad1d 100644
--- a/src/routes/help.js
+++ b/src/routes/help.js
@@ -1,14 +1,26 @@
+var exists = require('../lib/exists');
+
module.exports = function(routes) {
- routes.addRoute('/help', handleHelpRoute);
+ routes.addRoute('/help/:topic?', handleHelpRoute);
};
-module.exports.createUrl = function() {
+module.exports.createUrl = function(topic) {
+ if (exists(topic)) {
+ return '#/help/' + topic;
+ }
return '#/help';
};
-function handleHelpRoute(state) {
+function handleHelpRoute(state, events, params) {
// Set the page to help
state.navigation.pageKey.set('help');
state.viewport.title.set('Help');
+
+ // If given, go to the specified help page tab.
+ if (params.topic) {
+ // Import selectTab here to avoid a cyclical dependency.
+ var selectTab = require('../components/help/selectTab');
+ selectTab(state.help, events.help, params.topic);
+ }
}
\ No newline at end of file
