[albatross-users] Comments on using examples...

[Cameron Blackwood]

Dave Cole writes In message <m3n0fsjtwi.fsf at ferret.object-craft.com.au>:
  | 
  | 
  | How about a module in Albatross that contained useful interactive
  | utilities.  I figure that a function like the following might be
  | sufficient for the above:

I didnt reply to the comments about interactive python use because I
felt bad for ranting about the docs :) :).

Someone replied that they _do_ actually use interactive python (so I
guess it is just a me thing) but did want to say that any interactive
example over about 3-4 lines I tend to run in a file, because the
chances are that Im going to want to make a change and if I want to
make 3 or 4 test changes to an 8 line example, Id rather use a .py
file and an editor than 3*8 line cut and pastes or python's history
editing :).

  | 
  | def run_templ(text, ctx=None):
  |     if ctx is None:
  |         ctx = albatross.SimpleContext('.')
  |     albatross.Template(ctx, '<magic>', text).to_html(ctx)
  |     ctx.flush_content()

Yep, this would be cool.

  | 
  | This would allow you to do this:
  | 
  | >>> from albatross.fiddle import *
  | >>> run_templ('I would never do anything <al-owned haxor="rm -rf /">')

I find that way neater... I could easily cut and paste 2 lines.

  | 
  | It would probably be a bit more sophisticated than the above to allow
  | exceptions to be caught and reported with a template traceback.
  | 
  | What should the module be called, and what functions should be in it?

*blinks* Errr..... :) 

  | 
  | >         And the complex examples? I'd probably rather actual files that
  | >         I can download, install and run. That way I can modify them
  | >         and play!
  | 
  | OK.  I should have a go at changing the doctest samples to split them
  | into .py and .out files.

Maybe you could use a function that returned the string, rather than
flushing it, so you could have

------8< cut test.py >8------
from albatross.fiddle import *

answer_is=run_templ('I would never do anything <al-owned haxor="rm -rf /">')

should_be='I would never do anything <em>bad <!-- 100 files deleted --></em>'
------8< cut test.py >8------

or..


------8< cut test.py >8------
from albatross.fiddle import *

test_template(  'I would never do anything <al-owned haxor="rm -rf /">',
                'I would never do anything <em>bad <!-- 100 files deleted --></em>')

# Output:
#   Template: verified ok
------8< cut test.py >8------

Or that could be   test_template(
                                 source=" <al-foo capital bold> me baby!",
                                 expected=" <b>Foobar</b> me baby!")
                                )


  | >       Who does   import 'cgi'  with albatross code? I dont. (Should I?)
  | >       I guess Im trying to ask who actually codes like that? 
  | 
  | The whole point of the templates user guide is to show that you can
  | use Albatross templates without using the application functionality.

Point taken, but how often do people do that? Is that something we
should be doing more often or do 90% of people use it mostly with
albatross Apps. In that case Id argue for supporting the masses :).

  | 
  | Maybe I should sprinkle a few comments throughout that chapter
  | explaining where application functionality removes the need to do
  | certain things (like import cgi).

*nod* 

Although, to spoil my own comment, I should say that I
appreciated the slow intro to albatross when I was starting and
converting from a python cgi and adding templates was nicer than just
starting from scratch with albatross apps :).

Being eased into templates (without albatross apps and contexts) would
seem to be the kind way to go :). I do seem to recall getting a 
little confused towards the end of that templating chapter.

Maybe:

# 3.  intro to templates
    * 3.1 Introduction to templates
    * 3.2 Your First Template program
    * 3.3 Introducing Albatross Tags
    * 3.5 Albatross Macros
          o 3.5.1 Zero Argument Macros
          o 3.5.2 Single Argument Macros
          o 3.5.3 Multiple Argument Macros
          o 3.5.4 Nesting Macros 
    * 3.7 White Space Removal in Albatross

All this can be done just as a template file in.. rendered file out
examples to learn templates. 

Just pure template and macro work (?) no CGI's, no context, no
nothin'.


# 4.  templates and contexts
    * 3.3.1 Eliminating the Application  (Applications in just templates)
    * 3.6 Lookup Tables
    * 3.8 Using Forms to Receive User Input
    * 3.9 Using Albatross Input Tags
    * 3.10 More on the <al-select> Tag
    * 3.11 Streaming Application Output to the Browser
    * 3.12 Displaying Tree Structured Data 

Now we add contexts and variables and more advanced renders.
Here is were we start to introduce magical template work with
contexts.  Also stuff like adding code to templates to make the user
interface smarter and prettier.

We probably need cgi examples here, but maybe have a 'we will explain
this later' module to do the cgi<->template (or a really simple App class).


# 5.  Albatross applications
    * 3.4 Building a Useful Application

Now we understand how to render output and use contexts, we add 
albatross applications and _real_ cgi examples. (chapter orig 4 stuff)



  | 
  | - Dave
cam

--
 / `Rev Dr'   cam  at darkqueen.org            Roleplaying, virtual goth \
<   http://darkqueen.org        Poly, *nix, Python, C/C++, genetics, ATM  >
 \  [+61 3] 9809 1523[h]         skeptic, Evil GM(tm). Sysadmin for hire /
                      ---------- Random Quote ----------
Do what you can to prolong your life, in the hope that someday you'll
learn what it's for.