[LON-CAPA-cvs] cvs: doc /homework newtag.html

albertel lon-capa-cvs@mail.lon-capa.org
Thu, 06 Jun 2002 08:43:24 -0000


albertel		Thu Jun  6 04:43:24 2002 EDT

  Added files:                 
    /doc/homework	newtag.html 
  Log:
  - most of a document outlining what needs to be done to add a basic tag
  
  -still missing 
         - useful helper function descriptions
         - edit mode
              - insertlist.tab
         - analyze mode
         
  
  

Index: doc/homework/newtag.html
+++ doc/homework/newtag.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <title>Making a New Tag Handler</title>
  </head>

  <body>
    <h1>Making a New Tag Handler</h1>

    <h2>Required Actions</h2>
    <ul>
      <li>
	you will need to call <i>&amp;Apache::lonxml::register()</i>
	to register the tag name and the namespace it is in, most of
	the time this is in the BEGIN block of the handler
      </li>
      <li>
	you will need to create both <i>&amp;start_newtag()</i> and
	<i>&amp;end_newtag()</i> functions.
      </li>
      <li>
	these function will need to do one of: 
	<ol>
	  <li>
	    return a non-null string
	  </li>
	  <li>
	    return a null string (and expect that for some targets a
	    default output may be generated for it)
	  </li>
	  <li>
	    return a list containing a null string for the first
	    element and the string 'no' for the second element., this
	    will make sure that the result is a null string and any
	    default action normally taken will be skipped
	  </li>
	</ol>
      <li>
	These functions will have six arguments passed to them
	<ol>
	  <li>
	    <i>$target</i> a scalar cotaing the string of the target
	    that is being parsed for. The current possibilities
	    include web, tex, grade, answer, modified, edit, meta,
	    analyze. Although more may be added in the future, you
	    must guarentee that you return a blank string for any
	    target you don't specifically handle.
	  </li>
	  <li>
	    <i>$token</i> a HTML::LCParser token object,You probably
	    want to avoid using the parameter information inside of
	    this, you most likely want to use <i>$paramstack</i> and
	    <i>&amp;Apache::lonxml::get_param()</i>
	  </li>
	  <li>
	    <i>$tagstack</i> a stack pointer of the names of the tags
	    that are currently open, don't modify
	  </li>
	  <li>
	    <i>$paramstack</i> a stack pointer of the parameters
	    passed to the currently open tags, don't modify, and you
	    probably should use this only as a parameter to
	    <i>&amp;Apache::lonxml::get_param</i>
	  </li>
	  <li>
	    <i>$parser</i> a stack pointer of the current stack of
	    HTML::LCParser objects. You probably only want to use the
	    top one. Also your functions may manipulate this object
	    and grab more tokens from it but be carefule about
	    unbalancing it, also avoid calling the ->get_text()
	    routine unless you really not what you are doing
	    (<i>&amp;Apache::lonxml::get_all_text()</i> is probably
	    what you want to use.
	  </li>
	  <li>
	    <i>$safeeval</i> a pointer to the safe space interpreter,
	    You probably don't what to do anything with this directly,
	    <i>&amp;Apache::run::run</i> and other functions need this
	    argument and will use it correctly.
	  </li>
	  <li>
	    <i>$style</i> a Hash reference, it contains mappings
	    between tags and style file definitions. Few functions
	    will need to use this.
	  </li>
	</ol>
      </li>
      <li>
	if it is a new response tag it needs to
	<ul>
	  <li>
	    call <i>&amp;Apache::response::start_response()</i> in the
	    start_newtag function and
	    <i>&amp;Apache::response::end_response()</i> at the end of
	    the end_newtag function
	  </li>
	  <li>
	    set the required data for a responseid from the
	    datastorage document
	  </li>
	  <li>
	    use the functions
	    <i>&amp;Apache::response::check_for_previous()</i> and
	    <i>&amp;Apache::response::handle_previous()</i> to check
	    if a student's reponse has been submitted before.
	  </li>
	  <li>
	    call <i>&amp;Apache::response::setup_params()</i> if it is
	    expecting external parameters to be set for it.
	  </li>
	</ul>
      </li>
    </ul>
    <h2>Things to not do</h2>
    <ul>
      <li>
	there is no direct access to the Apache Request object. It is
	<b>very</b> unlikely that you need it, any data you want is
	either in %ENV, a global variable listed below or in the xml
	documentation, or should be gotten through an Apache::lonnet
	function
      </li>
      <li>
	print, either return it in the result, or use the
	debug/warning/error facility of Apache::lonxml
      </li>
      <li>
	use the <i>get_text()</i> procedure of the $parser
	HTML::LCParser object
      </li>
      <li>
	access the paramater attributes of the $token HTML::LCParser
	object
      </li>
    </ul>
    <h2>Interesting Globals</h2>
    <ul>
      <li> lonhomework globals 
	<ul>
	  <li>
	    <i>%Apache::lonhomework::history</i> the data from a restore
	    call for the current symb
	  </li>
	  <li>
	    <i>%Apache::lonhomework::results</i> the hash that will be
	    cstored at the end of the current execution
	  </li>
	  <li>
	    <i>$Apache::lonhomework::browse</i> the result of an allowed
	    request for the bre priviledge on the current file
	  </li>
	  <li>
	    <i>$Apache::lonhomework::viewgrades</i> the result of an
	    allowed request on the vgr priviledge for the current course
	  </li>
	  <li>
	    <i>$Apache::lonhomework::type</i> the current type of the
	    resource, either '', exam, homework, quiz, form, or survey
	  </li>
	  <li>
	    <i>%Apache::lonhomework::analyze</i> in analyze mode all data
	    to be returned is sotred in here.
	  </li>
	</ul>
      </li>
      <li>
	inputtag globals
	<ul>
	  <li>
	    <i>@Apache::inputtags::input</i> list of current input ids
	  </li>
	  <li>
	    <i>@Apache::inputtags::inputlist</i> list of all input ids
	    seen in this problem
	  </li>
	  <li>
	    <i>@Apache::inputtags::response</i> list of all current
	    response ids
	  </li>
	  <li>
	    <i>@Apache::inputtags::responselist</i> list of all
	    response ids seen in this problem
	  </li>
	  <li>
	    <i>@Apache::inputtags::previous</i> list of whether or not
	    a specific response was previously used
	  </li>
	  <li>
	    <i>$Apache::inputtags::part</i> id of current part, 0
	    means that no part is current (inside &lt;problem&gt;
	    only)
	  </li>
	  <li>
	    <i>@Apache::inputtags::status</i> list of problem date
	    statuses, the first element is for &lt;problem&gt; if
	    there is a second element it is for the current
	    &lt;part&gt; possible values are CLOSED, CAN_ANSWER,
	    SHOW_ANSWER, UNCHECKEDOUT
	  </li>
	  <li>
	    <i>%Apache::inputtags::params</i> hash of defined params
	    for the current response
	  </li>
	  <li>
	    <i>@Apache::inputtags::import</i> list of all ids, from
	    &lt;import&gt;s, these get join()ed and prepended to the
	    ids in the @Apache::inputtags::response and
	    @Apache::inputtags::responselist variables
	  </li>
	</ul>
      </li>
    </ul>
    <h2>Interesting Function</h2>
    
      
    <hr>
    <address><a href="mailto:albertel@msu.edu"></a></address>
<!-- Created: Thu Jun  6 03:47:04 EDT 2002 -->
<!-- hhmts start -->
Last modified: Thu Jun  6 04:46:00 EDT 2002
<!-- hhmts end -->
  </body>
</html>