Mercurial > p > roundup > code
comparison doc/customizing.txt @ 4921:8430576a5625
doc: Reverse engineer extension handling and add separate chapter
for them
| author | anatoly techtonik <techtonik@gmail.com> |
|---|---|
| date | Wed, 20 Aug 2014 11:41:27 +0300 |
| parents | ad3d628e73f2 |
| children | b76710818d31 |
comparison
equal
deleted
inserted
replaced
| 4920:854238f78026 | 4921:8430576a5625 |
|---|---|
| 20 Customisation of Roundup can take one of six forms: | 20 Customisation of Roundup can take one of six forms: |
| 21 | 21 |
| 22 1. `tracker configuration`_ changes | 22 1. `tracker configuration`_ changes |
| 23 2. database, or `tracker schema`_ changes | 23 2. database, or `tracker schema`_ changes |
| 24 3. "definition" class `database content`_ changes | 24 3. "definition" class `database content`_ changes |
| 25 4. behavioural changes, through detectors_ | 25 4. behavioural changes, through detectors_ and extensions_ |
| 26 5. `security / access controls`_ | 26 5. `security / access controls`_ |
| 27 6. change the `web interface`_ | 27 6. change the `web interface`_ |
| 28 | 28 |
| 29 The third case is special because it takes two distinctly different forms | 29 The third case is special because it takes two distinctly different forms |
| 30 depending upon whether the tracker has been initialised or not. The other two | 30 depending upon whether the tracker has been initialised or not. The other two |
| 46 tracker is initialised. | 46 tracker is initialised. |
| 47 db/ Holds the tracker's database | 47 db/ Holds the tracker's database |
| 48 db/files/ Holds the tracker's upload files and messages | 48 db/files/ Holds the tracker's upload files and messages |
| 49 db/backend_name Names the database back-end for the tracker | 49 db/backend_name Names the database back-end for the tracker |
| 50 detectors/ Auditors and reactors for this tracker | 50 detectors/ Auditors and reactors for this tracker |
| 51 extensions/ Additional web actions and templating utilities. | 51 extensions/ Additional actions and `templating utilities`_ |
| 52 html/ Web interface templates, images and style sheets | 52 html/ Web interface templates, images and style sheets |
| 53 lib/ optional common imports for detectors and extensions | 53 lib/ optional common imports for detectors and extensions |
| 54 =================== ======================================================== | 54 =================== ======================================================== |
| 55 | 55 |
| 56 | 56 |
| 938 ``send_message()`` are used to generate nosy messages, and may generate | 938 ``send_message()`` are used to generate nosy messages, and may generate |
| 939 messages which only consist of a change note (ie. the message id parameter | 939 messages which only consist of a change note (ie. the message id parameter |
| 940 is not required - this is referred to as a "System Message" because it | 940 is not required - this is referred to as a "System Message" because it |
| 941 comes from "the system" and not a user). | 941 comes from "the system" and not a user). |
| 942 | 942 |
| 943 | |
| 944 Extensions - adding capabilities to your tracker | |
| 945 ================================================ | |
| 946 .. _extensions: | |
| 947 | |
| 948 While detectors_ add new behavior by reacting to changes in tracked | |
| 949 objects, `extensions` add new actions and utilities to Roundup, which | |
| 950 are mostly used to enhance web interface. | |
| 951 | |
| 952 You can create an extension by creating Python file in your tracker | |
| 953 ``extensions`` directory. All files from this dir are loaded when | |
| 954 tracker instance is created, at which point it calls ``init(instance)`` | |
| 955 from each file supplying itself as a first argument. | |
| 956 | |
| 957 Note that at this point web interface is not loaded, but extensions still | |
| 958 can register actions for in tracker instance. This may be fixed in | |
| 959 Roundup 1.6 by introducing ``init_web(client)`` callback or a more | |
| 960 flexible extension point mechanism. | |
| 961 | |
| 962 | |
| 963 * ``instance.registerUtil`` is used for adding `templating utilities`_ | |
| 964 (see `adding a time log to your issues`_ for an example) | |
| 965 | |
| 966 * ``instance.registerAction`` is used to add more actions to instance | |
| 967 and to web interface. See `Defining new web actions`_ for details. | |
| 968 Generic action can be added by inheriting from ``action.Action`` | |
| 969 instead of ``cgi.action.Action``. | |
| 943 | 970 |
| 944 Database Content | 971 Database Content |
| 945 ================ | 972 ================ |
| 946 | 973 |
| 947 .. note:: | 974 .. note:: |
| 2526 =============== ========================================================= | 2553 =============== ========================================================= |
| 2527 | 2554 |
| 2528 | 2555 |
| 2529 The utils variable | 2556 The utils variable |
| 2530 ~~~~~~~~~~~~~~~~~~ | 2557 ~~~~~~~~~~~~~~~~~~ |
| 2558 .. _templating utilities: | |
| 2531 | 2559 |
| 2532 This is implemented by the | 2560 This is implemented by the |
| 2533 ``roundup.cgi.templating.TemplatingUtils`` class, but it may be extended | 2561 ``roundup.cgi.templating.TemplatingUtils`` class, which may be extended |
| 2534 as described below. | 2562 with additional methods by extensions_. |
| 2535 | 2563 |
| 2536 =============== ======================================================== | 2564 =============== ======================================================== |
| 2537 Method Description | 2565 Method Description |
| 2538 =============== ======================================================== | 2566 =============== ======================================================== |
| 2539 Batch return a batch object using the supplied list | 2567 Batch return a batch object using the supplied list |
| 2541 html_quote quote some text as safe in HTML (ie. <, >, ...) | 2569 html_quote quote some text as safe in HTML (ie. <, >, ...) |
| 2542 html_calendar renders an HTML calendar used by the | 2570 html_calendar renders an HTML calendar used by the |
| 2543 ``_generic.calendar.html`` template (itself invoked by | 2571 ``_generic.calendar.html`` template (itself invoked by |
| 2544 the popupCalendar DateHTMLProperty method | 2572 the popupCalendar DateHTMLProperty method |
| 2545 =============== ======================================================== | 2573 =============== ======================================================== |
| 2546 | |
| 2547 You may add additional utility methods by writing them in your tracker | |
| 2548 ``extensions`` directory and registering them with the templating system | |
| 2549 using ``instance.registerUtil`` (see `adding a time log to your issues`_ for | |
| 2550 an example of this). | |
| 2551 | 2574 |
| 2552 | 2575 |
| 2553 Batching | 2576 Batching |
| 2554 :::::::: | 2577 :::::::: |
| 2555 | 2578 |