Σύστημα συμβάντων

Το σύστημα συμβάντων επιτρέπει προσαρμοσμένο χειρισμό ,επιπλέον ή αντί ,της κανονικής επεξεργασίας για οποιοδήποτε κομμάτι του DokuWiki που σηματοδοτεί την δραστηριότητά του μέσω του συστήματος συμβάντων. Οι προσαρμοσμένοι χειριστές (ή αγκίστρια) , μπορούν να συμπεριληφθούν σε οποιοδήποτε πρόσθετο (plugin) ή σενάριο πρότυπου (template) (ή ακομα και στο ίδιο το DokuWiki). Τα Πρόσθετα ενεργειών έχουν σχεδιαστεί ειδικά για να μπορούν να εκμεταλλεύονται το σύστημα συμβάντων. Εγγυημένα θα φορτωθούν με την αρχή της επεξεργασίας και θα έχουν την ευκαιρία να εγγραφτούν για γεγονότα πριν πραγματοποιηθούν αυτά τα γεγονότα. Άλλα μέρη του DokuWiki ίσως δεν εκτελεστούν άμμεσα ή ακόμα και καθόλου για κάποιες σελίδες και διαδρομες εκτέλεσης.

Είναι ακόμα δυνατό για προσαρμοσμένο περιεχόμενο DokuWiki να δημιουργήσει και να πυροδοτήσει τα δικά του γεγονότα.

Το σύστημα των συμβάντων αποτελείται από τρία μέρη:

Το Aντικείμενο συμβάν.
Το κύριο χειριστή ή ελεγκτή. Αυτός είναι μια καθολική μεταβλητή DokuWiki , η $EVENT_HANDLER. Σενάρια που θέλουν να παραλάβουν ένα συμβάν πρέπει να εγγραφούν δηλώνοντας το ενδιαφέρον τους σε αυτό το αντικείμενο. Όταν πυροδοτείται ένα γεγονός θα περάσει με τη σειρά από ολα τα αγκίστρια κυκλικά (ή χειριστές συμβάντος) δίνοντάς τους με τη σειρά το γεγονός.
Επιμέρους χειριστές γεγονότων ή αγκίστρια. Αυτές είναι λειτουργίες που επιθυμούν να λάβουν ένα συγκεκριμένο γεγονός. Το πρόσθετο ενεργειών είναι όχημα ειδικά για τέτοιες συναρτήσεις,παρόλαυτα μπορούν επίσης να είναι μέρη προτύπων, πρόστετων ή άλλου τύπου σενάρια του DokuWiki .

Αναλυτική πληροφόρηση που περιγράφει όλα τα υπάρχοντα γεγονότα και πότε συμβαίνουν είναι η βικισελίδα events list.

Αντικείμενο συμβάν

όνομα κλάσης Doku_Event

Ένα αντικείμενο συμβάντος αποτελείται από:

PUBLIC (ΔΗΜΟΣΙΕΣ) ιδιότητες
- name, (READONLY-μόνο ανάγνωσης) οι χειριστές πρέπει να τη χρησιμοποιήσουν για εγγραφούν για να επεξεργαστούν κάποιο συμβάν
- data, (READ/WRITE -ανάγνωσης/γραφής) δεδομένα σχετικά με το συμβάν, οι χειριστές έχουν τη δυνατότητα να δούν και να τα τροποποιήσουν
- result, (READ/WRITE-ανάγνωσης/γραφής ) διαθέσιμο ,αφού έχει γίνει η προκαθορισμένη ενέργεια, σε χειριστές που έχουν έγγραφεί για την advise (συμβουλή) after (μετά).
- canPreventDefault, (READONLY -μόνο ανάγνωσης) ενημερώνει έναν χειριστή αν μπορεί ή όχι να εμποδιστεί η εκτέλεση της προκαθορισμένης ενέργειας.
PRIVATE (ΙΔΙΩΤΙΚΕΣ) ιδιότητες
- _default (λογική, αρχική τιμή true(αληθής)), κατά πόσο θα εκτελεστεί ή όχι η προκαθορισμένη ενέργεια που σχετίζεται το συμβάν. Αλλαγή αυτής της ιδιότητας γίνεται μέσω της μεθόδου preventDefault() .
- _continue (bool, αρχική τιμή true(αληθής)), κατά πόσο ή όχι θα συνεχίσει η αποστολή του συμβάντος και σε άλλους εγγεγραμένους χειριστές. Αλλαγή αυτής της ιδιότητας γίνεται μέσω της μεθόδου stopPropagation() .

PUBLIC (ΔΗΜΟΣΙΕΣ) μέθοδοι
- trigger() - αυτόματη αποστολή σήματος συμβάντος. Αυτή η μέθοδος δέχεται δυο προαιρετικές παραμέτρους, την προκαθορισμένη ενέργεια (επανάκληση), και το καταπόσο ή οχι η εκτέλεση της μπορεί να εμποδιστεί (bool-λογική τιμή) και επιστρέφει το αποτέλεσμα του συμβάντος. Επίσης εποπτεύει την όλη διαδικασία του συμβάντος , αποστέλλοντας το σήμα “_BEFORE” advise , ενεργοποιεί-πυροδοτεί- την προκαθορισμένη ενέργεια , και στέλνει το σήμα “_AFTER” advise.
- stopPropagation() - σταμάτημα οποιασδήποτε περαιτέρω επεξεργασίας του συμβάντος από χειριστές συμβάντων. Αυτή η μέθοδος δεν εμποδίζει την εκτέλεση της προκαθορισμένης ενέργειας.e
- preventDefault() - αποτροπή εκτέλεσης της προκαθορισμένης ενέργειας.
advise_*() μέθοδοι - χρησιμοποιείται όταν το σενάριο που στέλνει το σήμα επιθυμεί να χειριστεί την συνολική διαδικασία σηματοδοσίας ( ίσως όταν δεν ενδύκνυται ή μετατροπή σε συνάρτησης μιας προκαθορισμένης ενέργειας.)
- advise_before() - δέχεται μια παράμετρο, λογική, που δηλώνει κατά πόσο η προκαθορισμένη ενέργεια μπορεί να αποτραπεί, στέλνει το σήμα “_BEFORE” .
- advise_after() - στέλνει το σήμα “_AFTER” .

Εγγραφή για αποδοχή συμβάντος

Η εγγραφή ενός χειριστή για να δεχτεί ένα γεγονός ,γίνεται μέσω της κλήσης της μεθόδου register_hook() του $EVENT_HANDLER. Τα πρόσθετα ενεργειών μπορούν να το κάνουν αυτό χρησιμοποιώντας την παράμετρο $controller με την δική τους μέθοδο register() . Άλλα μέρη του DokuWiki πρέπει να σιγουρέψουν ότι είναι είτε σε καθολική εμβέλεια ή να δηλώσουν το $EVENT_HANDLER σαν καθολική. π.χ.

global $EVENT_HANDLER;
$EVENT_HANDLER->register_hook( ... )

Για ενημερωμένες λεπτομέρειες σχετικά με τη συνάρτηση register_hook και τις παραμέτρους της κοιτάξτε τη δήλωσή της στο inc/events.php. Την 2006-04-26 ή δήλωση της είναι

  /**
   * register_hook
   *
   * register a hook for an event
   *
   * @PARAM  $event   (string)   name used by the event
   * @PARAM  $advise  (string)   ''BEFORE'' or ''AFTER'', the advise the hook wished to receive
   * @PARAM  $obj     (obj)      object in whose scope method is to be executed, 
   *                             if NULL, method is assumed to be a globally available function
   * @PARAM  $method  (function) event handler function
   * @PARAM  $param   (mixed)    (optional) data to be passed to the event handler
   */ 
  function register_hook($event, $advise, &$obj, $method, $param)

Ενεργοποιώντας ένα συμβάν

Ένα συμβάν μπορεί να ενεργοποιηθεί με τρεις τρόπους.

Ο απλούστερος είναι να κλειθεί η συνάρτηση περίβλημα trigger_event. Αυτή η συνάρτηση δέχεται όλες τις απαραίτητες παραμέτρους για να δημιουργήσει ένα συμβάν και να το ενεργοποιήσει-πυροδοτήσει.

/**
 *  trigger_event
 *
 *  function wrapper to process (create, trigger and destroy) an event
 *
 *  @PARAM  $name               (string)   name for the event
 *  @PARAM  $data               (mixed)    event data
 *  @PARAM  $action             (callback) (optional, default=NULL) default action, a php callback function
 *  @PARAM  $canPreventDefault  (bool)     (optional, default=true) can hooks prevent the default action
 *
 *  @RETURN (mixed)                        the event results value after all event processing is complete
 *                                         by default this is the return value of the default action however
 *                                         it can be set or modified by event handler hooks
 */
function trigger_event($name, &$data, $action=NULL, $canPreventDefault=true)

με χρήση της μεθόδου trigger . Αυτή δεν συνίσταται καθώς είναι καλύτερο να χρησιμοποιηθεί η συνάρτηση περίβλημα trigger_event() που περιγράψεμε παραπάνω.
```
  $evt = new Doku_Event(<event_name>,<event_data>);
  $evt->trigger(<default action>,<can prevent default>);
  unset($evt);
```
διαχείριση της όλης διαδικασίας αποστολής σημάτων. Χρησιμοποίησε αυτή την μέθοδο όταν υπάρχει προκαθορισμένη ενέργεια αλλά δεν είναι δυνατό να την πακετάρεις σαν συνάρτηση επανάκλησης php .
```
  $evt = new Doku_Event(<event name>, <event data>);
  if ($evt->advise_before(<can prevent default>)) {
    // default action code block
  }
  $evt->advise_after();
  unset($evt);
```

Παραδείγματα

(αυτά είναι μόνο παραδείγματα που μπορεί να υπάρχουν ή όχι στο DokuWiki)

Κατά την αποθήκευση βικισελίδας

// event(συμβάν):  'IO_WIKIPAGE_SAVE'
// data(δεδομένα):   array(file name, the raw wiki page)
// action(ενέργεια): αποθήκευση τη ακατέργαστης βικισελίδας στο όνομα αρχείου
// return(επιστρεφόμενη τιμή): λογική τιμή,  αποθήκευση σελίδας
$ok = trigger_event('SAVE_WIKIPAGE', array($id,$wikitext), io_savewikipage)

possible handlers, indexers, translaters

Προσθήκη/Αντικατάσταση do ενεργειών

// events:  'ACTION_ACT_PREPROCESS' & 'TPL_ACT_UNKNOWN'
// data:    $ACT  (value of the ''do'' query string variable)
// action:  none, handled by signalling script

// στο αρχείο''inc/actions.php act_dispatch()''
$evt = new Doku_Event('ACTION_ACT_PREPROCESS', $ACT);  
if ($evt->advise_before()) { 
   /* process $ACT normally */ 
}
$evt->advise_after();
unset($evt);

// in ''inc/template.php tpl_content()''
default: /* unrecognised $ACT value */
  $evt = new Doku_Event('TPL_ACT_UNKNOWN', $ACT);
  if ($evt->advise_before()) { 
     print "unknown action"; 
  }
  $evt->advise_after();
  unset($evt);

possible handlers, customer form processing, additional do commands from template UI.

On handler instruction list completion

// event:  ''PARSER_HANDLER_DONE''
// data:   the handler, including the completed instruction list
// action: none

// in ''inc/parser/handler.php  _finalize()
trigger_event('PARSER_HANDLER_DONE',$this);

possible handlers, footnote replacement plugins, enhanced TOC handlers