Making a New Tag Handler

Required Actions

• you will need to call &Apache::lonxml::register() to register the tag name and the namespace it is in, most of the time this is in the BEGIN block of the handler
• you will need to create both &start_newtag() and &end_newtag() functions.
• these function will need to do one of:
  1. return a non-null string
  2. return a null string (and expect that for some targets a default output may be generated for it)
  3. 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
• These functions will have six arguments passed to them
  1. $target 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.
  2. $token a HTML::LCParser token object,You probably want to avoid using the parameter information inside of this, you most likely want to use $paramstack and &Apache::lonxml::get_param()
  3. $tagstack a stack pointer of the names of the tags that are currently open, don't modify
  4. $paramstack 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 &Apache::lonxml::get_param
  5. $parser 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 (&Apache::lonxml::get_all_text() is probably what you want to use.
  6. $safeeval a pointer to the safe space interpreter, You probably don't what to do anything with this directly, &Apache::run::run and other functions need this argument and will use it correctly.
  7. $style a Hash reference, it contains mappings between tags and style file definitions. Few functions will need to use this.
• if it is a new response tag it needs to
  • call &Apache::response::start_response() in the start_newtag function and &Apache::response::end_response() at the end of the end_newtag function
  • set the required data for a responseid from the datastorage document
  • use the functions &Apache::response::check_for_previous() and &Apache::response::handle_previous() to check if a student's reponse has been submitted before.
  • call &Apache::response::setup_params() if it is expecting external parameters to be set for it.

Things to not do

• there is no direct access to the Apache Request object. It is very 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
• print, either return it in the result, or use the debug/warning/error facility of Apache::lonxml
• use the get_text() procedure of the $parser HTML::LCParser object
• access the paramater attributes of the $token HTML::LCParser object

Interesting Globals

• lonhomework globals
  • %Apache::lonhomework::history the data from a restore call for the current symb
  • %Apache::lonhomework::results the hash that will be cstored at the end of the current execution
  • $Apache::lonhomework::browse the result of an allowed request for the bre priviledge on the current file
  • $Apache::lonhomework::viewgrades the result of an allowed request on the vgr priviledge for the current course
  • $Apache::lonhomework::type the current type of the resource, either '', exam, homework, quiz, form, or survey
  • %Apache::lonhomework::analyze in analyze mode all data to be returned is sotred in here.
• inputtag globals
  • @Apache::inputtags::input list of current input ids
  • @Apache::inputtags::inputlist list of all input ids seen in this problem
  • @Apache::inputtags::response list of all current response ids
  • @Apache::inputtags::responselist list of all response ids seen in this problem
  • @Apache::inputtags::previous list of whether or not a specific response was previously used
  • $Apache::inputtags::part id of current part, 0 means that no part is current (inside <problem> only)
  • @Apache::inputtags::status list of problem date statuses, the first element is for <problem> if there is a second element it is for the current <part> possible values are CLOSED, CAN_ANSWER, SHOW_ANSWER, UNCHECKEDOUT
  • %Apache::inputtags::params hash of defined params for the current response
  • @Apache::inputtags::import list of all ids, from <import>s, these get join()ed and prepended to the ids in the @Apache::inputtags::response and @Apache::inputtags::responselist variables

Interesting Function