|
1 | 1 | # Interactive Jobs |
2 | 2 |
|
3 | | -test |
| 3 | +Sometimes you have a task that will run for a while or just produce a lot of logging output as it executes to let the user know what's going on. it is very easy to keep the user up to date with the print helper like so: |
| 4 | + |
| 5 | +```text |
| 6 | +print.greenLine( 'Step 57 complete!' ); |
| 7 | +``` |
| 8 | + |
| 9 | +This can create a lot of output however which can look a little messy. Plus if you have a task that runs another task or command, all the output from each steps gets mixed together. This is where Interactive Jobs help you harness the power of redrawing the console over and over to nicely format what steps have completed and have logging for each step that goes away once the step is complete. |
| 10 | + |
| 11 | +Interactive Jobs are best if you have a small enough number of jobs that they can all fit on one screen. Since the output of the jobs is updated in real time, it doesn't scroll past the bottom of the terminal and CommandBox will just truncate any extra text. |
| 12 | + |
| 13 | +## Job DSL |
| 14 | + |
| 15 | +We have a nice DSL you can call that signals the start and end of each job. Every job has a name, zero or more log messages, and a final status of whether it was successful. The ~~`job`~~ variable is automatically available for custom commands and Task Runners. |
| 16 | + |
| 17 | +```javascript |
| 18 | +job.start( 'This is my job to run' ); |
| 19 | + sleep( 2000 ); |
| 20 | +job.complete(); |
| 21 | +``` |
| 22 | + |
| 23 | +The log messages will show up in the order they appear, but once you complete the job, the log messages are hidden and only a single, green line shows to represented the completed job regardless of how many steps it had in the meantime. Do not output normal text with the `print` helper if possible. Once you've started the job, use the `job.addLog()` calls. |
| 24 | + |
| 25 | +## Log Messages |
| 26 | + |
| 27 | +You can log the individual steps of your job for instant user feedback: |
| 28 | + |
| 29 | +```javascript |
| 30 | +job.start( 'This is my job to run' ); |
| 31 | + sleep( 2000 ); |
| 32 | + job.addLog( 'Still going...' ); |
| 33 | + |
| 34 | + sleep( 2000 ); |
| 35 | + job.addLog( 'Now we''re getting somewhere.' ); |
| 36 | + |
| 37 | + sleep( 2000 ); |
| 38 | + job.addLog( 'Almost done!' ); |
| 39 | + |
| 40 | + sleep( 2000 ); |
| 41 | +job.complete(); |
| 42 | +``` |
| 43 | + |
| 44 | +Feel free to add ANSI formatting to your log messages, but we have some convenience method for you already. |
| 45 | + |
| 46 | +```javascript |
| 47 | +job.addLog( 'I will print white text' ); |
| 48 | +job.addSuccessLog ( ' I will print green text' ); |
| 49 | +job.addWarnLog( ' I will print yellow text' ); |
| 50 | +job.addErrorLog( ' I will print red text' ); |
| 51 | +``` |
| 52 | + |
| 53 | +By default, a job will only show the last 5 log lines to keep things tidy. Configure this when you start the job. |
| 54 | + |
| 55 | +```javascript |
| 56 | +job.start( name='My job', lineSize=10 ); |
| 57 | +``` |
| 58 | + |
| 59 | +## Ending the Job |
| 60 | + |
| 61 | +All good things must come to an end. use the `complete()` method to show that your job has finished successfully. use the `error()` method to show your job has ended but with issues. |
| 62 | + |
| 63 | +```javascript |
| 64 | +job.start( 'I have a good feeling about this' );if( warmFuzzy ) { job.complete();} else { job.error( 'I''ve lost that loving feeling.' );} |
| 65 | +``` |
| 66 | + |
| 67 | +The `job.error()` method can take an optional message to describe what happened which will remain on the screen. If a Task Runner has an unhandled error or the user interrupts execution with Ctrl-C, CommandBox will end the job for you as an error. The exception message will be passed to the `job.error()` call for you so the user can see what happened. |
| 68 | + |
| 69 | +### Dump Log Messages |
| 70 | + |
| 71 | +If you want to have a verbose mode in your task that dumps out all the log messages at the end you can do that by passing `dumpLog` as true in your `job.complete()` or `job.error()` calls. This is great for debugging tasks that ran on a CI server. This dumps ALL logging lines regardless of what your `logSize` was set to. `logSize` is only used for the interactive output during execution to keep things clean. |
| 72 | + |
| 73 | +```text |
| 74 | +job.complete( dumpLog=true ); |
| 75 | +``` |
4 | 76 |
|
0 commit comments