From 53ae0830c723a8a366f38197f2d9359268b6258b Mon Sep 17 00:00:00 2001 From: Aaron Boodman Date: Sat, 23 Nov 2013 00:38:13 -0800 Subject: [PATCH] Strawman web ui style guide. Change-Id: I6d6ee09bb42f79adad8789e6b9cfb5a9f59dc1f2 --- website/content/docs/index.html | 1 + website/content/docs/web-ui-styleguide | 60 ++++++++++++++++++++++++++ 2 files changed, 61 insertions(+) create mode 100644 website/content/docs/web-ui-styleguide diff --git a/website/content/docs/index.html b/website/content/docs/index.html index 8e57f3286..cd0826795 100644 --- a/website/content/docs/index.html +++ b/website/content/docs/index.html @@ -32,4 +32,5 @@ HTML, though:

  • Prior Art: other projects doing similar stuff
  • Release History: previous releases and notable features of each
  • Contributing: how to help
    • +
  • The style to use when working on the Web UI
    • diff --git a/website/content/docs/web-ui-styleguide b/website/content/docs/web-ui-styleguide new file mode 100644 index 000000000..7134f63fa --- /dev/null +++ b/website/content/docs/web-ui-styleguide @@ -0,0 +1,60 @@ +

    Web UI Styleguide

    + +

    Note: 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. + +

    Architecture

    + +

    The Camlistore Web UI is an "AJAX"-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. + +

    The Web UI is written almost entirely in JavaScript. We make no effort to +"degrade +gracefully" 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. + +

    Paradigm

    + +

    Though we are architected mostly as a "single-page +application", we make extensive use of URLs via +pushState(). +In general every unique view in the application has a URL that can be used to +revisit that view. + +

    In the same vein, although we are an interactive application, we make +appropriate use of web platform primitives where they exist. We use <a> +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 <canvas> or <img> tags +so that selection and find-in-page work. + +

    Stack

    + +

    We use Google Closure, +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. + +

    Style

    + +

    We follow the Google JavaScript Styleguide and the Closure JSDoc Rules for formatting and so-on. Those of us that use Emacs +install Js2Mode. + +

    Compatibility

    + +

    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.