What's the right way to start building a stack?

+2 votes
asked Jan 6, 2015 in Stacks API by q2aadmin (6,045 points)

1 Answer

+1 vote
answered Jan 6, 2015 by isaiah (13,745 points)
selected Jan 6, 2015 by q2aadmin
Best answer

I like to work from a functional prototype. I build my prototype outside of RapidWeaver to ensure it's all working. Then gradually move it into RapidWeaver, then into Stacks, and then add Stacks-API features.

Create a Prototype

  1. Create a page in Coda (or whatever web dev tool you prefer).
  2. Add your stack's content to that page. Include jQuery, js, and css calls if necessary.
  3. Just use defaults for where you will be adding custom controls.
  4. Ensure that it is error and warning free and saved to a place you can refer to while you're building a stack.

Stop. If you can't get your prototype error and warning free, then your project is infeasible. Moving forward is a waste of time and energy.

Move it into RW

  1. Open RW and create a new project file.
  2. Make sure the theme is set to a well understood trivial theme that is unlikely to interact with anything you're doing. I use Alpha.
    NB: You don't have to use Alpha, but keep in mind most 3rd party themes add lots of nice features -- which makes them poorly suited for development work.
  3. Create an HTML page. (you read it right, not a stacks page.)
  4. Copy the code from your prototype into the HTML page.
  5. Ensure that things are working well in the HTML page and are error and warning free.

Stop. If you can't get the prototype into an HTML page, then your project is infeasible. Moving forward is a waste of time and energy.

Create a static stack

  1. Create a bare bones stack.
  2. Copy your HTML page content into the stack's HTML template.
    NB: don't add custom controls, call jQuery and js exactly as you did in your HTML page and prototype. Literally just copy the HTML over.
  3. Create a stacks page and add your stack. It should be very similar to the HTML page (plus a few extra stacks divs).
  4. Ensure the page is error and warning free

Stop. If you can't get the basic prototype in a static stack, then your project is infeasible. Moving forward is a waste of time.

Add stacks features

  • Remove your jQuery call and add convert to the stacks built in call.
  • Move your js to the stacks js closure.
  • Move shared resources to site-assets.
  • Add custom controls.
  • Polish the edit-mode UI to make it friendly.

After each change check for warnings and errors. If you find warnings and errors, stop, step back, and try to fix those errors before moving forward. Using a revision control tool like Git and committing each error free change will make it easy to step back when things get too broken.