Web Project workflow Creation through to Deployment - tooltwist/documentation GitHub Wiki

Here we describe the steps for a simple web design project, from creation through to deployment, using the ToolTwist v8.3.

Prerequisites

  • Java 1.7+
  • NodeJs and npm
  • ImageMagick
  • Ruby

Check the Designer runs

If you've already run the Standalone Designer on your machine you can skip this step.

Install the Standalone Designer:

$ npm install -g tooltwist

Test it with the demo project:

$ export dir=${HOME}/Development/myProject  
$ mkdir -p $dir  
$ cd $dir  
$ tooltwist init designer  
$ tooltwist designer

This will check the webdesign project for ttdemo out of Github, then build and run the ToolTwist Designer. You can run the Designer in your browser at http://localhost:8080/ttsvr/login.

First time you log in the images will be missing. They can be created using the menu option misc->Generate Images.

Once you finish, stop the Designer server using Ctrl-C.

Creating a new Web Design project

These steps create a default web design project, then add it to a repository

Check out the script

$ cd /tmp  
$ git clone [email protected]:tooltwist/new-webdesign-project.git

Create the project and push to Github

The following examples create a new project named myProject, but replace this with your own project name.

  1. Create the webdesign files:

     $ cd new-webdesign-project  
 $ npm update  
 $ node new-webdesign-project.js templates/demo-site $dir/.tooltwist/webdesign-projects myProject

  2. Check the project dependencies and add any needed extension projects.

     $ vi $dir/.tooltwist/webdesign-projects/myProject/project.json

  3. Create the project named myProject at http://www.github.com, without a README file. Take note of the http URL it uses for the repository.

  4. Push the project to Github:

     $ cd $dir/.tooltwist/webdesign-projects/myProject  
 $ git init; git add .; git commit -m "first commit"  
 $ git remote add origin <repository-url>
 $ git push -u origin master

Run the Designer on the new Project

  • Run the designer for this project

      # cd $dir  
  # vi tooltwist.js     <-- update the "repo" property  
  # tooltwist designer

  • Click on the project name (i.e. ttdemo) and select the new project.

  • Run Misc->Generate Images.

  • Click on Navpoints on the left, and then on the Navpoint tab click Generate Hierarchy. This will generate every navpoint. Close the window once it's run.

  • Click on Home and then the Test tab. The home page should be displayed, and you should be able to navigate through all the pages of the site.

Create a Page Template

Page templates provide the options provided on the File->New... dialog. They should be created sparingly. The best starting point is to copy an existing page template. In this case we'll copy the default Mustache page template.

There are two widgets that must be copied. The first is the entry that provides the layout, snippets, etc. The second is the entry that adds it to the menu.

  1. Copy an existing page widget Start a new Terminal session.

     $ project=myProject
 $ pageWidget=myPageWidget   <-- the new template's name
 $ cd $dir
 $ cp -R .tooltwist/extension-projects/ttWbd/widgets/toolbox/mustachePage .tooltwist/webdesign-projects/${project}/widgets/${project}_pages/${pageWidget}

  2. Create the entry for File->New...

     - Copy the template for the existing page widget

 $ cp -R .tooltwist/extension-projects/ttWbd/widgets/toolbox/mustachePage_template .tooltwist/webdesign-projects/${project}/widgets/${project}_pages/${pageWidget}_template

  3. Update the template

     $ vi .tooltwist/webdesign-projects/${project}/widgets/${project}_pages/${pageWidget}_template/*/conf.xml

    • Change the entry for <linkedWidget> to refer to your new widget <linkedWidget>myProject_pages.pageLayout1</linkedWidget>.

    • Update label and description, according to how you would like it to appear in the File->New... dialog.

  4. (Optional) Replace the icon shown in the File->New... dialog (if required), by changing tooltwist/webdesign-projects/myProject/widgets/myProject_pages/pageLayout1_template/0.1/THUMBNAIL.png.

  5. In the Designer, reload the cache, using _Misc->Reload Cache`.

You should now see the page layout widget under Web Design Assets/myProject/myProject_pages/myPageLayout. On the File->New... dialog you should also see the option.

Note: A template may be used by many pages, and if the template is changed, all the pages that use it will also change. For this reason, great care is needed while working on templates.

If you look at template.mustache, you will see several lines such as [[PAGE:importCode]]. These lines are important, and give the code generator the location to insert code required by the widgets placed on the page.

The [[^PAGE:DESIGNER_MODE]] and [[/PAGE:DESIGNER_MODE]] tags are used to delineate code that should not be output on the Edit tab of the Designer. On this tab the page HTML is inserted as part of the Designer page, rather than in an iFrame, so it must not contain <html>, <head>, or <body> elements.

The [[&PAGE:GENERATED_HTML_FOR_CHILD]] tag gets replaced with the code generated by the children of the page. i.e. By the widgets placed on the page.

Create a page using the new template

  1. Create the new page using File->New..., and selecting your new template. Set the library name to myProject_pages and set the name to myPage.

  2. Click on Navpoints, then press the + button to add a new navpoint. On the Navpoint tab set the label to myPage and set the Page Widget to the page you just created (i.e. myProject_pages.myPage).

  3. On the Edit tab, click on the "Show layout grid" button (top right next to the trash can), and you can see the region on the page where widgets can be dropped. This is actually a grid widget, so extra columns and rows can be added.

  4. Drag a Page Title widget onto the page.

You can now experiment with changing the page, and also changing the template. Try the Test tab to see how the HTML looks, and use the Source tab to see the output of the generator. Note in particular how the [[&PAGE:GENERATED_HTML_FOR_CHILD]] and other tags get replaced.

Create a Mustache widget

  1. From File->New... select Mustache Widget. Select myProject.widgets for the library name and myWidget as the widget name.

  2. On the template.mustache tab, change the Newly created mustache widget text to something different, then click on the Edit tab to see it changed. (Don't forget to press save).

  3. Drag the new widget on to the myPage page you created above, and observe it on the Edit, Test and Source tabs.

Push changes to the repository

IGNORE THIS First we need to set the git username and password to be used to sync back to git.

$ mkdir tooltwist.templates
$ cp tooltwist/site-conf/conf/wbd.conf tooltwist.templates/template.wbd.conf
$ vi tooltwist.templates/template.wbd.conf

Check the following are set (probably near the end of the file).

\# Set these values to allow syncing to git from the Designer
gitUsername=XXX
gitPassword=XXX

DOWN TO HERE

In the Designer, select Repository->Sync With Repository.... This should display a list of widget and navpoint changes. Select the changes you wish to accept and press Submit.

Note: If an error dialog is displayed, click on the details link. If the error message mentions "undefined method 'each'" then you might need to upgrade to Ruby version 1.9 or higher.

Deploy using Controller v8.3

Set up a Staging Server

todo

  • push ttWbd
  • check which repo is used
  • move git password to a separate file in site-conf (maybe a DB?)
  • don't save password to Github!!!!
  • check ruby version in tooltwist-cli
  • get files from artifactory (on tooltwist server?)
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️