Skip to content

Commit fccfb53

Browse files
MarkRobboMarkRobbo
committed
Add about page with recommended best practices
1 parent 03d7259 commit fccfb53

File tree

3 files changed

+190
-0
lines changed

3 files changed

+190
-0
lines changed

‎src/main/java/org/commonwl/view/PageController.java

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,16 @@ public String homePage(Model model, @RequestParam(value = "url", required = fals
3939
return "index";
4040
}
4141

42+
/**
43+
* About page
44+
* @param model The model for the about page
45+
* @return The view for this page
46+
*/
47+
@GetMapping("/about")
48+
public String about(Model model) {
49+
return "about";
50+
}
51+
4252
/**
4353
* API documentation page
4454
* @param model The model for the API documentation page

‎src/main/resources/templates/about.html

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
<!DOCTYPE html>
2+
<!--
3+
~ Licensed to the Apache Software Foundation (ASF) under one
4+
~ or more contributor license agreements. See the NOTICE file
5+
~ distributed with this work for additional information
6+
~ regarding copyright ownership. The ASF licenses this file
7+
~ to you under the Apache License, Version 2.0 (the
8+
~ "License"); you may not use this file except in compliance
9+
~ with the License. You may obtain a copy of the License at
10+
~
11+
~ http://www.apache.org/licenses/LICENSE-2.0
12+
~
13+
~ Unless required by applicable law or agreed to in writing,
14+
~ software distributed under the License is distributed on an
15+
~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16+
~ KIND, either express or implied. See the License for the
17+
~ specific language governing permissions and limitations
18+
~ under the License.
19+
-->
20+
21+
<html xmlns:th="http://www.thymeleaf.org">
22+
<head>
23+
<meta charset="UTF-8" />
24+
<meta name="viewport" content="width=device-width, initial-scale=1" />
25+
<title>About - Common Workflow Language Viewer</title>
26+
<link rel="stylesheet" th:href="@{/bower_components/bootstrap/dist/css/bootstrap.min.css}" href="../static/bower_components/bootstrap/dist/css/bootstrap.min.css" />
27+
<link rel="stylesheet" th:href="@{/bower_components/highlightjs/styles/github.css}" href="../static/bower_components/highlightjs/styles/default.css" />
28+
<link rel="stylesheet" type="text/css" th:href="@{/css/main-20170616.css}" href="../static/css/main-20170616.css" />
29+
</head>
30+
<body>
31+
32+
<nav th:replace="fragments/header :: navbar"></nav>
33+
34+
<div class="container">
35+
<div class="row">
36+
<div class="col-md-12" role="main" id="main">
37+
<h1>About</h1>
38+
<div style="position:relative;float:right;height:0;padding-bottom:30%;width:50%;margin-left:20px;">
39+
<iframe src="https://www.youtube.com/embed/_yjhVTmvxLU?ecver=2" style="position:absolute;width:100%;height:100%;left:0" allowfullscreen="true"></iframe>
40+
</div>
41+
42+
<p>CWL Viewer is a richly featured web visualisation suite for workflows written in the
43+
<a href="http://www.commonwl.org/">Common Workflow Language</a> with an aim of facilitating sharing,
44+
understanding and discovery as well as encouraging best practices when writing workflows and their
45+
tooling.</p>
46+
47+
<p>Cite as: <code><a href="https://doi.org/10.5281/zenodo.823534">10.5281/zenodo.823534</a></code></p>
48+
49+
<p>A <a href="https://doi.org/10.5281/zenodo.823535">Technical Report for this project can be viewed here</a>.</p>
50+
51+
<p>CWL Viewer also won the <a href="https://f1000research.com/">F1000Research</a> Best Poster Award at
52+
<a href="https://www.iscb.org/ismbeccb2017">ISMB/ECCB 2017</a> for its
53+
<a href="https://doi.org/10.7490/f1000research.1114375.1">poster submission.</a></p>
54+
55+
<p>This project was developed at the <a href="http://www.esciencelab.org.uk/">eScience Lab</a> at
56+
<a href="http://www.manchester.ac.uk/">The University of Manchester</a>, with work supported by
57+
<a href="http://bioexcel.eu/">Bioexcel</a>, funded by the European Union Horizon 2020 program under
58+
<a href="http://cordis.europa.eu/projects/675728">grant agreement 675728.</a></p>
59+
60+
<p>Contributions are welcome in the form of issues and pull requests to the
61+
<a href="https://github.com/common-workflow-language/cwlviewer">Github repository</a>.</p>
62+
63+
<h1>Best Practices</h1>
64+
<p>In order to ensure that your workflow is well presented in CWL Viewer, we recommend the following of
65+
<a href="http://www.commonwl.org/user_guide/rec-practices/">CWL Best Practices</a>. Those which are
66+
specifically relevant to the viewer are detailed below, but it is suggested that you try to meet as
67+
many as possible to include the general quality and reproducibility of your workflows.</p>
68+
<p>Some limitations of the CWL Viewer which you may need to be aware of are also described here.</p>
69+
70+
<h2>Label Strings</h2>
71+
<p class="recommendation">Include a top level short <code>label</code> summarising each tool and workflow</p>
72+
<p class="why">Labels give the user an easy human-readable version of the name for the tool or workflow</p>
73+
<p class="use">For workflows this will be displayed at the top of the page as the title and for tools it will be
74+
displayed in the table and as the name of the step in the visualisation. If a <code>label</code>
75+
is given at the step level, it will take priority over the top level tool <code>label</code>. You can
76+
use this to provide a more descriptive label of the tool's application in the particular step if
77+
preferred.</p>
78+
79+
<h2>Doc Strings</h2>
80+
<p class="recommendation">If useful, include a top level <code>doc</code> string providing a longer, more detailed description
81+
than was provided in the <code>label</code> (see above)</p>
82+
<p class="why">Docs give the user a detailed description of the role a tool or workflow performs</p>
83+
<p class="use">For workflows this will be displayed at the top of the page under the title and for tools it will be
84+
displayed in the table. If a <code>doc</code> string is given at the step level, it will take priority
85+
over the top level tool doc. You can use this to provide a more descriptive label of the tool's
86+
application in the particular step if preferred</p>
87+
88+
<h2>Conceptual Identifiers</h2>
89+
<p class="recommendation">All <code>input</code> and <code>output</code> identifiers should reflect their conceptual identity.
90+
Generic and uninformative names such as <code>result</code> or <code>input</code>/<code>output</code>
91+
should be avoided</p>
92+
<p class="why">Helpful identifiers allow for the links between steps in the CWL file to be easily distinguished</p>
93+
<p class="use">Identifiers are displayed in the tables and are unique to the step. If <code>label</code> or
94+
<code>doc</code> strings are for some reason not provided, the IDs will be used in the visualisation</p>
95+
96+
<h2>Format Specification</h2>
97+
<p class="recommendation">The <code>format</code> field should be specified for all input and output <code>File</code>s</p>
98+
<p class="recommendation_more">
99+
Tools should use format identifiers from a relevant ontology such as the
100+
<a href="http://edamontology.org/format_1915">EDAM Ontology</a> in the case of Bioinformatics tools.
101+
For plain types use the
102+
<a href="http://www.iana.org/assignments/media-types/media-types.xhtml">IANA media type list</a> with
103+
<code>$namespaces: { iana: "https://www.iana.org/assignments/media-types/" }</code>, for example
104+
<code>iana:text/plain</code>, <code>iana:text/tab-separated-values</code>
105+
</p>
106+
<p class="why">The use of formal standards for format fields enables implementations to provide checks
107+
for compatibility in formatting of files</p>
108+
<p class="use">Ontologies will be parsed and the name of and link to the format displayed in the table on workflow
109+
pages. Plain formats will have the iana.org link given but will not display the name of the format.</p>
110+
111+
<h2>Separation of Concerns</h2>
112+
<p class="recommendation">Each <code>CommandLineTool</code> description should focus on a single operation only, even if the
113+
(sub)command is capable of more.</p>
114+
<p class="why">This allows for easier reuse of the tool in other workflows and understanding as to it's purpose</p>
115+
<p class="use">In CWL Viewer this ensures that steps are clear in purpose within the workflow and generated visualisation</p>
116+
117+
<h2>JavaScript Elimination</h2>
118+
<p class="recommendation">Evaluate all use of JavaScript for possible elimination or replacement. For instance, for the
119+
manipulation of <code>File</code> names and paths, often one of the built in <code>File</code>
120+
properties such as <code>basename</code>, <code>nameroot</code>, <code>nameext</code> etc
121+
could be used instead</p>
122+
<p class="why">Tool runners can implement more efficient implementations of built in functionality, which
123+
makes JavaScript expressions a last resort</p>
124+
<p class="use">CWL viewer does not take into account JavaScript expressions when extracting information about your
125+
workflows</p>
126+
127+
<h2>Use of Subworkflows</h2>
128+
<p class="recommendation">CWL implementations which also implement <code>SubworkflowFeatureRequirement</code> can support nesting
129+
workflows as a step within others. Complex workflows with individual components which can be abstracted
130+
should utilise this to make their workflow modular and allow sections of them to be easily reused</p>
131+
<p class="why">Extracting subworkflows enables them to be run, developed on and tested individually. It also makes
132+
them able to be understood more easily</p>
133+
<p class="use">Subworkflows are simplified in the visualisations and are linked as a different workflow in the
134+
<code>Step</code> tables on each workflow page</p>
135+
136+
<h2>Licensing</h2>
137+
<p class="recommendation">Include a <a href="https://opensource.org/licenses">OSI approved open source license</a>
138+
in your workflow and tool descriptions</p>
139+
<p class="recommendation_more">
140+
For example, the following two statements at the top level of a workflow or tool description licenses it
141+
under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache V2.0 License</a>:<br />
142+
<code>
143+
$namespaces: { s: "http://schema.org/" }<br />
144+
s:license: "https://www.apache.org/licenses/LICENSE-2.0"
145+
</code>
146+
</p>
147+
<p class="why">A permissive open source license allows others to remix and use your tooling and workflows
148+
to prevent the community from repeating development effort, allowing everyone to benefit</p>
149+
<p class="use">CWL Viewer is designed to allow people to locate and make use of the workflows developed by
150+
others as well as to share and demonstrate work, and open source licenses promote this goal</p>
151+
152+
<h1>Limitations</h1>
153+
<h2>Packed Workflows</h2>
154+
<p>In the Common Workflow Language, multiple files can be combined into a single one to create a
155+
self-contained document with all the components of a workflow. In the reference implementation
156+
this is done by using <code>cwltool --pack</code>.</p>
157+
<p>CWL Viewer treats each file as an independent workflow and although it can parse a workflow from the file,
158+
it is not possible to choose which and any nested workflows are not able to be viewed.
159+
(<a href="https://github.com/common-workflow-language/cwlviewer/issues/103">see Github issue</a>)</p>
160+
161+
<h2>Research Objects</h2>
162+
<p>Research Objects are constructed from the containing directory of the workflow file. This means tooling
163+
external to the directory but used by the workflow will not be included
164+
(<a href="https://github.com/common-workflow-language/cwlviewer/issues/103">see Github issue</a>)</p>
165+
<p>We recommend that you keep all files in the containing folder for current use of CWL Viewer</p>
166+
167+
<h2>Others</h2>
168+
<p>Other limitations or unimplemented features can be viewed
169+
<a href="https://github.com/common-workflow-language/cwlviewer">on the Github issues page</a></p>
170+
</div>
171+
</div>
172+
</div>
173+
174+
<div th:replace="fragments/footer :: copy"></div>
175+
176+
<script src="/bower_components/requirejs/require.js" data-main="/js/docs.js"></script>
177+
</body>
178+
</html>

‎src/main/resources/templates/fragments/header.html

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,9 +32,11 @@
3232
</a>
3333
<a href="/workflows" class="button navbar-toggle">Explore</a>
3434
<a href="/apidocs" class="button navbar-toggle">API</a>
35+
<a href="/about" class="button navbar-toggle">About</a>
3536
</div>
3637
<div class="collapse navbar-collapse">
3738
<ul class="nav navbar-nav navbar-right">
39+
<li><a href="/about">About</a></li>
3840
<li><a href="/apidocs">API</a></li>
3941
<li><a href="/workflows">Explore</a></li>
4042
</ul>

0 commit comments

Comments
 (0)