Synopsis

[jqxhr=] loadcmd(command [,target] [,filter] [,timeout])

The loadcmd() function executes a shell command or evaluates javascript code with asynchronous streaming of the output into a target element or onto a function.

Basic Usage

As this is the underlying function for command buttons, basic usage is very similar, but fully scriptable:

Show boot status

    
As with command buttons, you can append the output by prefixing the target
      selector with "+". You can omit the output by passing null as the target. If target
      is a DOM element, loadcmd automatically sets the loading class on the
      target while the command is processed.

    
The target element's min-height is automatically fixed to the current height
      of the target before the output is set. This avoids page layout jumps when
      reusing a target for commands.

    
If the target is scrollable and the content exceeds the visible area, the
      element is automatically scrolled to show the new content, unless the user has
      done a manual scrolling on the element.

    
If the command output stops for timeout seconds, the request is
      aborted and a timeout error is shown. Default timeout is 20 seconds for standard
      commands, 300 seconds for known long running commands.


    
Evaluate Javascript Code

    
To execute Javascript, either pass an object instead of the command string,
      containing the command as property "command" and a second property "type" with
      value "js", or simply use the wrapper call loadjs(). Example:

    

      
        Show vehicle type
      
    
    

    
Javascript evaluation is not limited to a single command or line. Hint: to avoid
      encoding complex JS code in the onclick attribute, store the code in some hidden
      DOM element and read it via $(…).text().


    
Output Encoding & Binary Streams

    
To allow binary data to be sent by a command and to enable processing of the
      result by Javascript on the browser without character encoding issues, the command
      API supports output "binary" mode.
    
    
Primary application for this is exchanging CBOR encoded objects between the
      module and the web frontend. To fully support this, the OVMS web frontent includes
      the CBOR library by Patrick Gansterer. Example use:

    
    loadjs({ command: "auxbatmon.dump('CBOR')", output: "binary" }).done((data) => {
      history = CBOR.decode(data);
    });
    

    
See the AuxBatMon and PwrMon OVMS plugins for full examples.

    
output modes supported by the command API are:
    
    

      
text → Content-Type: text/plain; charset=utf-8
      
json → Content-Type: application/json; charset=utf-8
      
binary → Content-Type: application/octet-stream; charset=x-user-defined
      
default/other → Content-Type: application/octet-stream; charset=utf-8
    


    
jqXHR Object

    
loadcmd() returns the jqXHR (XMLHttpRequest) object in charge for
      the asynchronous execution of the request. This can be used to track the results
      of the execution, check for errors or to abort the command.

    

      Start chargen
      Abort chargen
    
    

    
The jQuery XHR object is also a "thenable", so actions to be performed after
      the command execution can simply be chained to the object. Example:

    
Show stat

    
See jQuery
      documentation for full details and options.


    
Filter / Process Output

    
Supply a filter function to hook into the asynchronous output stream. Use filters
      to filter (ahem…) / preprocess / reformat the command output, scan the stream for some
      info you'd like to know as soon as possible, or completely take over the output
      processing.

    
The filter function is called when a new chunk of output has arrived or when
      a stream error has occurred. The function gets a message object containing
      the request object and either a text for normal outputs
      or an error, which is a preformatted error output you can use or
      ignore.

    
If the filter function returns a string, that will be added to the output target.
      If it returns null, the target will remain untouched.

    
Hint: if you just want to scan the text for some info, you can pass on the message
      after your scan to the default standardTextFilter().

    
Example: let's reformat a can status dump into a nice Bootstrap table:

    
CAN1 status

    

      

        
Key
Value