Warning: Can't synchronize with repository "(default)" (Unsupported version control system "svn": No module named svn). Look in the Trac log for more information.

Ticket #1778 (closed documentation: fixed)

Opened 11 years ago

Last modified 9 years ago

1.0/RoughDocs/GettingStartedTemplate Document Review: A replacement for 1.0/GettingStarted/Kid

Reported by: randomandy Owned by: Chris Arndt
Priority: normal Milestone: 1.1.x bugfix
Component: Documentation Version: 1.0
Severity: normal Keywords: doc review
Cc:

Description

This is intended to go along with  Getting Started: Controller and to replace  GettingStarted/Kid.

Please check for accuracy. My knowledge is still rather shallow.

Change History

comment:1 Changed 11 years ago by randomandy

Here is a link to the  new document submitted for review.

comment:2 Changed 11 years ago by Chris Arndt

I only skimmed over the documents so far, but here are some initial remark:

  1. The introduction should start with an explanation what templates are for (namely, to display the interface of your app with dynamically created HTML).
  1. The "Using Genshi now" section should be moved to the end. The default for TG 1.0 is Kid and works well, so readers should not be confused by immediately telling them to replace it. Also, in the introduction, Genshi should not be mentioned in the first sentence but later, as a newer alternative to Kid.

3.

Most TG Widgets were written for and only work in Kid. You can explicitly use Kid in these cases with an @expose(template="kid:example.templates.foobar").

You don't need to use Kid for your template just to use widgets, just the widgets will use Kid templates, so you will still need to have Kid installed (TG 1.0 doesn't install without it anyway). But in Genshi templates you have to wrap widgets with ${ET(widget.display())}.

  1. In section "Substitution" add a warning about the possibility of XSS-Attacks when using ${XML()} on un-sanitized values provided by user, maybe with a link to the Wikipedia XSS article).
  1. A section about the templates created by quickstart and their purpose would be good.
  1. The links to the Kid and Genshi documentation should be (also) placed in a "References" section at the end. There should be links to the usage manuals as well, not only the syntax refernces.
  1. In the "Namespace" section, make the distinction between which namespace is for Kid and which one is for Genshi clear. Put Kid first.
  1. The "Important Tips" section applies to Genshi as well as Kid, so just remove "on Kid Templates" from the title.
  1. Add a reference to the "Standard template variables" page.

comment:3 Changed 10 years ago by jorge.vargas

  • Milestone changed from __unclassified__ to 1.x

comment:4 Changed 10 years ago by Chris Arndt

  • Status changed from new to assigned
  • Milestone changed from 1.x to 1.1

This could still be used as a basis for the template section of the TG 1.1 Getting Started Guide (see #2370)

comment:5 Changed 10 years ago by Chris Arndt

  • Type changed from defect to task

comment:6 Changed 10 years ago by Chris Arndt

  • Type changed from task to documentation

comment:7 Changed 10 years ago by Chris Arndt

  • Milestone changed from 1.1 to 1.1.x bugfix

comment:8 Changed 9 years ago by chrisz

  • Status changed from assigned to closed
  • Resolution set to fixed

Made some changes and merged it with  http://docs.turbogears.org/1.0/GettingStarted/Kid.

Note: See TracTickets for help on using tickets.