Rooba
/
perkeep
mirror of https://github.com/perkeep/perkeep.git
1
1
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Strawman web ui style guide. 

Change-Id: I6d6ee09bb42f79adad8789e6b9cfb5a9f59dc1f2
This commit is contained in:
Aaron Boodman 2013-11-23 00:38:13 -08:00
parent cfd02e6c89
commit 53ae0830c7
2 changed files with 61 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
website/content/docs/index.html
View File

@ -32,4 +32,5 @@ HTML, though:</p>
<li><a href="/docs/prior-art">Prior Art</a>: other projects doing similar stuff</li>
<li><a href="/download">Release History</a>: previous releases and notable features of each</li>
<li><a href="/docs/contributing">Contributing</a>: how to help</li>
<li><a href="/docs/web-ui-styleguide">The style to use when working on the Web UI</a></li>
</ul>

60
website/content/docs/web-ui-styleguide Normal file
View File

@ -0,0 +1,60 @@
<h1>Web UI Styleguide</h1>
<p><em><strong>Note:</strong> The following statements represent how we think
things should be, not how they are. The Web UI is just getting started and
doesn't adhere to all of these goals yet. New code should, though.</em>
<h2>Architecture</h2>
<p>The Camlistore Web UI is an "<a
href="http://en.wikipedia.org/wiki/Ajax_(programming)">AJAX</a>"-style web
application that interacts with Camlistore servers just as any other client
would. It speaks the same HTTP APIs as the Android and iOS clients, for example.
We avoid creating APIs that are specific to one client, instead preferring to
generalize functionality such that all current clients and even unknown future
clients can make use of it.
<p>The Web UI is written almost entirely in JavaScript. We make no effort to
"<a href="http://www.w3.org/wiki/Graceful_degredation_versus_progressive_enhancement">degrade
gracefully</a>" in the absence of JavaScript or CSS support. We try to minimize
usage of literal HTML markup in the source, as it tends to lead to poor
modularity. We instead prefer to construct DOM trees programmatically.
<h2>Paradigm</h2>
<p>Though we are architected mostly as a "<a
href="http://en.wikipedia.org/wiki/Single-page_application">single-page
application</a>", we make extensive use of URLs via
<a href="https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Manipulating_the_browser_history">pushState()</a>.
In general every unique view in the application has a URL that can be used to
revisit that view.
<p>In the same vein, although we are an interactive application, we make
appropriate use of web platform primitives where they exist. We use &lt;a&gt;
tags for clickable things that navigate, so that browser tools like "Open in new
tab" and "Copy link" work as users would expect. Similarly, when we want to
display text, we use HTML text rather than &lt;canvas&gt; or &lt;img&gt; tags
so that selection and find-in-page work.
<h2>Stack</h2>
<p>We use <a href="https://developers.google.com/closure/">Google Closure</a>,
mainly for its excellent dead-code removal and decent standard library. We
use some Closure UI widgets, but are also happy to bypass the Closure UI layer
and implement our own UI directly on the DOM when that's easier.
<h2>Style</h2>
<p>We follow the <a
href="http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml"
>Google JavaScript Styleguide</a> and the <a
href="https://developers.google.com/closure/compiler/docs/js-for-compiler"
>Closure JSDoc Rules</a> for formatting and so-on. Those of us that use Emacs
install <a href="https://code.google.com/p/js2-mode/">Js2Mode</a>.
<h2>Compatibility</h2>
<p>We target the last two stable versions of Desktop Chrome, Firefox, Safari,
IE. We also target the last two stable versions of Safari and Chrome on Android
and iOS tablets. We don't currently target the phone form factor at all, though
it probably sort of works with a lot of zooming and panning.