Constitution: a Method

Systematic web apps development (notes towards…). The method I follow with my still work in progress Constitution stack.

  1. TOC

    1. Introduction
    2. Init
    3. SDLC
    4. Styleguide
    5. Topics…
      1. Editable
      2. i18n/L10n
      3. Auth²
  2. Init

    Initialize codebase, workflow.

    1. Skeletons
    2. Git/flow
    3. Install
    4. Run

    (The least important step. Nu, from a marketing perspective (funnel), assuming a long tail distribution of adoption (time spent with this stack), it makes sense to emphasize painless installation and… but, at what price? I do 1,000 hours scale projects. It’s astonishing how frameworks fuss about the first five minutes, and hardly give thought to the rest. Market failure much?)

  3. Skeletons

    (Forthcoming)

    1. Copy repository: download as zip, and unzip it.
    2. Or, clone it:
      $ mkdir $PROJECT/Code; cd $PROJECT/Code
      $ git clone $SKELETON .

      But, don’t need history:

      $ git clone --depth 1 --branch master $SKELETON .

      Records cloned remote as “origin”. Remove, or keep and rename that remote, so can diff against future skeleton updates?

      $ git remote rename origin skeleton
    3. .gitignore (GitHub can generate it, if repo created there.)
    4. README.md (or index.html for GHP? Separate branch?)…
  4. From scratch

  5. Git/flow

    1. Have Gitflow installed globally.
    2. Initialize:
      $ git flow init --defaults

      creates a local development repo, if wasn’t cloned from a skeleton or GitHub. Switches branch to develop.

  6. Remote

    1. GitHub: create repo (https://github.com/new), then copy canonical URL.
    2. Set remote:
      $ git remote add origin https://github.com/$ACCOUNT/$PROJECT.git
    3. Use canonical URLs in package.json (homepage, repository, bugs), etc.
  7. Setup Git

    Useful .git/config, or global, settings:

    1. Cache passwords:
      $ git config --global credential.helper "cache --timeout=9999"

      Cf git help credential-cache (or man git-credential-cache).

    2. Force HTTPS for when (public) Wi-Fi blocks SSH port:
      $ git config --global url.https://.insteadof git://

      Cf git help config.

      $ git config push.default current

      so can just “git push” from separate local clones of different branches, particularly “gh-pages”.

    3. Bash aliases, prompt, and completion fix.

    Etc.

  8. Go public

    $ go master; git merge develop; git tag 0.0.1
    $ git push --force
  9. SDLC

    1. Dependencies
    2. Config
    3. It works!
    4. Wireframes
    5. APIs
    6. Continuous
    7. Styleguide
  10. Dependencies

    package.json (NPM), bower.json…

    1. Project’s metadata: edit package.json. What about duplication in bower.json? DRY!
    2. CDN URLs? See, under SPA templates, Double Macchiato helper “cdn_script”.
  11. Config

    config.coffee, ecosystem.coffee (config for PM2): environmental defaults, feature toggling…

  12. It works!

  13. Wireframes

    1. Content
    2. POP
    3. Screens
    4. URLs
    5. Navigation
    6. SPAs
    7. Grayscreening
    8. Layouts
  14. Content

  15. POP

    1. Prototyping on paper (POP)
    2. Extremes first: what I call “deep RWD”, instead of narrow first, aka mobile first, in the olden days of shallow RWD.
    3. Input methods: pointer/touch (adapt/consolidate?).
  16. Screens

    1. List screens. Per SPA. (“Screen” includes modals, mutations… anything that’s recorded in navigation history, ie back button applies. At least?)
    2. Widgets: inventory (sub)components of screens; separate list for recurring.
  17. URLs

  18. Specifications

    Screen URL Selector
    Favorites /favs #favs
    Item /items/:id #item
    Catalog /items/ #catalog Listing. (Redirect if missing trailing slash.)
  19. Navigation

    1. Nav conceptual structure/organization; cf “lost in hyperspace”.
    2. Also: redirections (eg root(s), auth’ dependent), screens without URLs (no history tracking)…
  20. SPAs

    1. Single Page App: combine screens into (one or more) SPAs to avoid full page rendering.
    2. Eg: public.html, logged-in.html, admin.html, landing.html.
    3. When/where to render?
    4. Templates
    5. Routing
    6. History API
  21. When/where to render?

    1. Server-side or in browser?
    2. Build-time or run-time? Both?
  22. Templates

    1. Per SPA; eg: public.html.coffee, logged-in.html.coffee, admin.html.coffee, landing.html.coffee.
    2. i18n/L10n: rendered into static assets once; eg app.language.html.coffee will be rendered into app.en.html, app.es.html, etc.
    3. CoffeeScript modules exporting an HTML renderer:
      # public.-.html.coffee
      module.exports=renderable (lang)->
      	html5bp {lang},->
      		title 'Skeleton (Public)'
      		#…
      

      (See skeleton for useful “templates”.)

  23. Routing

    1. Express routing: order significant: decreasing specificity
    2. Route all URLs to corresponding SPA, so they can be bookmarked, shared.
      app # Express.
      # Public (anonymous) SPA.
      .all /\/(..)\/(|login|logout|terms)$/,(req,res)->res.sendFile ASSETS+"/public.#{req.params[0]}.html"
      # Admin SPA.
      .all /\/(sys|error)$/,(req,res)->res.sendFile ASSETS+'/admin.html'
      
    3. Redirects: eg, to pick language prefix:
      .all /\/([a-z]{2})?$/i,(req,res)->res.redirect "/#{pick_language req}/"

      (Redirect to appropriate SPA based on optional path parameter, session (cookie), or UA preferences.)

    4. Directories in URL path, for namespacing collections:
      # Directories: redirect to append slash.
      .all /\/(..)\/(items|profiles|help)$/,(req,res)->res.redirect req.path+'/'

      allowing for URLs like /en/items/foo and /en/items/, not /en/items.

    5. (Server/client side (SS/CS) scaffolding, helpers… forthcoming.)
  24. History API

    Capture navigation “internal” to an SPA; eg:

    ## app.coffee
    page.base "/#{lang}"
    page '/favs',->show_screen '#favs'; set_title 'Favorites'
    page '/i/',->show_screen '#dir'; set_title 'Directory'
    page '/i/:id',->show_screen '#item'; set_title 'Item'
    
    1. Render absolute URLs, so can navigate up/down the URL path, eg app.-.html.coffee:
      a href:"/#{lang}/i/123",'Item'
      a href:"/#{lang}/help/me",->i '.fa.fa-question';text 'Help'
      a href:"/#{lang}/flow",->i '.fa.fa-shopping-cart';text 'Workflow'
      
    2. Screens (HTML <section>s) have unique IDs, which show_screen copies to an attribute on <body>:
      $('body').attr 'data-screen',p

      so can easily target screens in CSS, eg (Stylus):

      a
      	header &
      		color inherit
      		[data-screen="#favs"] &.fa-star
      		[data-screen="#profile"] &.fa-user
      			color white
      

      (But, second thoughts about this example: mixing state with styling smells…)

  25. Grayscreening

    Mockups that work in browser!

    Top-down…

    1. Nav links (backdoor)
  26. Layouts

    1. RWD, eg:
      1. Narrow (single column): questionnaire screen has outline/nav in collapsed drawer, sliding in from right (align:end)
      2. Wide (double): questionnaire in right column, outline/nav in left, always expanded
      3. Huge (triple): wide, plus preview of results in a third column
    2. Patterns…
    3. Widgets
      1. Nav bars, dropdowns, modals…
  27. APIs

  28. Continuous

  29. Styleguide

  30. Editing (WYSIWYG)

  31. i18n/L10n

  32. Data Modeling and I/O

  33. Auth²



Comments are closed.