Annotation of doc/homework/newtag.html, revision 1.1

1.1     ! albertel    1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
        !             2: <html>
        !             3:   <head>
        !             4:     <title>Making a New Tag Handler</title>
        !             5:   </head>
        !             6: 
        !             7:   <body>
        !             8:     <h1>Making a New Tag Handler</h1>
        !             9: 
        !            10:     <h2>Required Actions</h2>
        !            11:     <ul>
        !            12:       <li>
        !            13: 	you will need to call <i>&amp;Apache::lonxml::register()</i>
        !            14: 	to register the tag name and the namespace it is in, most of
        !            15: 	the time this is in the BEGIN block of the handler
        !            16:       </li>
        !            17:       <li>
        !            18: 	you will need to create both <i>&amp;start_newtag()</i> and
        !            19: 	<i>&amp;end_newtag()</i> functions.
        !            20:       </li>
        !            21:       <li>
        !            22: 	these function will need to do one of: 
        !            23: 	<ol>
        !            24: 	  <li>
        !            25: 	    return a non-null string
        !            26: 	  </li>
        !            27: 	  <li>
        !            28: 	    return a null string (and expect that for some targets a
        !            29: 	    default output may be generated for it)
        !            30: 	  </li>
        !            31: 	  <li>
        !            32: 	    return a list containing a null string for the first
        !            33: 	    element and the string 'no' for the second element., this
        !            34: 	    will make sure that the result is a null string and any
        !            35: 	    default action normally taken will be skipped
        !            36: 	  </li>
        !            37: 	</ol>
        !            38:       <li>
        !            39: 	These functions will have six arguments passed to them
        !            40: 	<ol>
        !            41: 	  <li>
        !            42: 	    <i>$target</i> a scalar cotaing the string of the target
        !            43: 	    that is being parsed for. The current possibilities
        !            44: 	    include web, tex, grade, answer, modified, edit, meta,
        !            45: 	    analyze. Although more may be added in the future, you
        !            46: 	    must guarentee that you return a blank string for any
        !            47: 	    target you don't specifically handle.
        !            48: 	  </li>
        !            49: 	  <li>
        !            50: 	    <i>$token</i> a HTML::LCParser token object,You probably
        !            51: 	    want to avoid using the parameter information inside of
        !            52: 	    this, you most likely want to use <i>$paramstack</i> and
        !            53: 	    <i>&amp;Apache::lonxml::get_param()</i>
        !            54: 	  </li>
        !            55: 	  <li>
        !            56: 	    <i>$tagstack</i> a stack pointer of the names of the tags
        !            57: 	    that are currently open, don't modify
        !            58: 	  </li>
        !            59: 	  <li>
        !            60: 	    <i>$paramstack</i> a stack pointer of the parameters
        !            61: 	    passed to the currently open tags, don't modify, and you
        !            62: 	    probably should use this only as a parameter to
        !            63: 	    <i>&amp;Apache::lonxml::get_param</i>
        !            64: 	  </li>
        !            65: 	  <li>
        !            66: 	    <i>$parser</i> a stack pointer of the current stack of
        !            67: 	    HTML::LCParser objects. You probably only want to use the
        !            68: 	    top one. Also your functions may manipulate this object
        !            69: 	    and grab more tokens from it but be carefule about
        !            70: 	    unbalancing it, also avoid calling the ->get_text()
        !            71: 	    routine unless you really not what you are doing
        !            72: 	    (<i>&amp;Apache::lonxml::get_all_text()</i> is probably
        !            73: 	    what you want to use.
        !            74: 	  </li>
        !            75: 	  <li>
        !            76: 	    <i>$safeeval</i> a pointer to the safe space interpreter,
        !            77: 	    You probably don't what to do anything with this directly,
        !            78: 	    <i>&amp;Apache::run::run</i> and other functions need this
        !            79: 	    argument and will use it correctly.
        !            80: 	  </li>
        !            81: 	  <li>
        !            82: 	    <i>$style</i> a Hash reference, it contains mappings
        !            83: 	    between tags and style file definitions. Few functions
        !            84: 	    will need to use this.
        !            85: 	  </li>
        !            86: 	</ol>
        !            87:       </li>
        !            88:       <li>
        !            89: 	if it is a new response tag it needs to
        !            90: 	<ul>
        !            91: 	  <li>
        !            92: 	    call <i>&amp;Apache::response::start_response()</i> in the
        !            93: 	    start_newtag function and
        !            94: 	    <i>&amp;Apache::response::end_response()</i> at the end of
        !            95: 	    the end_newtag function
        !            96: 	  </li>
        !            97: 	  <li>
        !            98: 	    set the required data for a responseid from the
        !            99: 	    datastorage document
        !           100: 	  </li>
        !           101: 	  <li>
        !           102: 	    use the functions
        !           103: 	    <i>&amp;Apache::response::check_for_previous()</i> and
        !           104: 	    <i>&amp;Apache::response::handle_previous()</i> to check
        !           105: 	    if a student's reponse has been submitted before.
        !           106: 	  </li>
        !           107: 	  <li>
        !           108: 	    call <i>&amp;Apache::response::setup_params()</i> if it is
        !           109: 	    expecting external parameters to be set for it.
        !           110: 	  </li>
        !           111: 	</ul>
        !           112:       </li>
        !           113:     </ul>
        !           114:     <h2>Things to not do</h2>
        !           115:     <ul>
        !           116:       <li>
        !           117: 	there is no direct access to the Apache Request object. It is
        !           118: 	<b>very</b> unlikely that you need it, any data you want is
        !           119: 	either in %ENV, a global variable listed below or in the xml
        !           120: 	documentation, or should be gotten through an Apache::lonnet
        !           121: 	function
        !           122:       </li>
        !           123:       <li>
        !           124: 	print, either return it in the result, or use the
        !           125: 	debug/warning/error facility of Apache::lonxml
        !           126:       </li>
        !           127:       <li>
        !           128: 	use the <i>get_text()</i> procedure of the $parser
        !           129: 	HTML::LCParser object
        !           130:       </li>
        !           131:       <li>
        !           132: 	access the paramater attributes of the $token HTML::LCParser
        !           133: 	object
        !           134:       </li>
        !           135:     </ul>
        !           136:     <h2>Interesting Globals</h2>
        !           137:     <ul>
        !           138:       <li> lonhomework globals 
        !           139: 	<ul>
        !           140: 	  <li>
        !           141: 	    <i>%Apache::lonhomework::history</i> the data from a restore
        !           142: 	    call for the current symb
        !           143: 	  </li>
        !           144: 	  <li>
        !           145: 	    <i>%Apache::lonhomework::results</i> the hash that will be
        !           146: 	    cstored at the end of the current execution
        !           147: 	  </li>
        !           148: 	  <li>
        !           149: 	    <i>$Apache::lonhomework::browse</i> the result of an allowed
        !           150: 	    request for the bre priviledge on the current file
        !           151: 	  </li>
        !           152: 	  <li>
        !           153: 	    <i>$Apache::lonhomework::viewgrades</i> the result of an
        !           154: 	    allowed request on the vgr priviledge for the current course
        !           155: 	  </li>
        !           156: 	  <li>
        !           157: 	    <i>$Apache::lonhomework::type</i> the current type of the
        !           158: 	    resource, either '', exam, homework, quiz, form, or survey
        !           159: 	  </li>
        !           160: 	  <li>
        !           161: 	    <i>%Apache::lonhomework::analyze</i> in analyze mode all data
        !           162: 	    to be returned is sotred in here.
        !           163: 	  </li>
        !           164: 	</ul>
        !           165:       </li>
        !           166:       <li>
        !           167: 	inputtag globals
        !           168: 	<ul>
        !           169: 	  <li>
        !           170: 	    <i>@Apache::inputtags::input</i> list of current input ids
        !           171: 	  </li>
        !           172: 	  <li>
        !           173: 	    <i>@Apache::inputtags::inputlist</i> list of all input ids
        !           174: 	    seen in this problem
        !           175: 	  </li>
        !           176: 	  <li>
        !           177: 	    <i>@Apache::inputtags::response</i> list of all current
        !           178: 	    response ids
        !           179: 	  </li>
        !           180: 	  <li>
        !           181: 	    <i>@Apache::inputtags::responselist</i> list of all
        !           182: 	    response ids seen in this problem
        !           183: 	  </li>
        !           184: 	  <li>
        !           185: 	    <i>@Apache::inputtags::previous</i> list of whether or not
        !           186: 	    a specific response was previously used
        !           187: 	  </li>
        !           188: 	  <li>
        !           189: 	    <i>$Apache::inputtags::part</i> id of current part, 0
        !           190: 	    means that no part is current (inside &lt;problem&gt;
        !           191: 	    only)
        !           192: 	  </li>
        !           193: 	  <li>
        !           194: 	    <i>@Apache::inputtags::status</i> list of problem date
        !           195: 	    statuses, the first element is for &lt;problem&gt; if
        !           196: 	    there is a second element it is for the current
        !           197: 	    &lt;part&gt; possible values are CLOSED, CAN_ANSWER,
        !           198: 	    SHOW_ANSWER, UNCHECKEDOUT
        !           199: 	  </li>
        !           200: 	  <li>
        !           201: 	    <i>%Apache::inputtags::params</i> hash of defined params
        !           202: 	    for the current response
        !           203: 	  </li>
        !           204: 	  <li>
        !           205: 	    <i>@Apache::inputtags::import</i> list of all ids, from
        !           206: 	    &lt;import&gt;s, these get join()ed and prepended to the
        !           207: 	    ids in the @Apache::inputtags::response and
        !           208: 	    @Apache::inputtags::responselist variables
        !           209: 	  </li>
        !           210: 	</ul>
        !           211:       </li>
        !           212:     </ul>
        !           213:     <h2>Interesting Function</h2>
        !           214:     
        !           215:       
        !           216:     <hr>
        !           217:     <address><a href="mailto:albertel@msu.edu"></a></address>
        !           218: <!-- Created: Thu Jun  6 03:47:04 EDT 2002 -->
        !           219: <!-- hhmts start -->
        !           220: Last modified: Thu Jun  6 04:46:00 EDT 2002
        !           221: <!-- hhmts end -->
        !           222:   </body>
        !           223: </html>

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>