Mercurial > p > roundup > code
comparison doc/customizing.txt @ 6292:1e5ed659e8ca issue2550923_computed_property
Initial implementation of Computed property
It supports query/display in html, rest and xml interfaces.
You can specify a cache parameter, but using it raises
NotImplementedError.
It does not support: search, sort or grouping by the computed field.
Checking in on a branch to get more eyeballs on it and maybe some
people to help.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Fri, 27 Nov 2020 18:09:00 -0500 |
| parents | a67e2b559e8d |
| children | 1a15089c2e49 |
comparison
equal
deleted
inserted
replaced
| 6291:a67e2b559e8d | 6292:1e5ed659e8ca |
|---|---|
| 739 properties are for storing arbitrary-length strings. | 739 properties are for storing arbitrary-length strings. |
| 740 Password | 740 Password |
| 741 properties are for storing encoded arbitrary-length strings. | 741 properties are for storing encoded arbitrary-length strings. |
| 742 The default encoding is defined on the ``roundup.password.Password`` | 742 The default encoding is defined on the ``roundup.password.Password`` |
| 743 class. | 743 class. |
| 744 Computed | |
| 745 properties invoke a python function. The return value of the | |
| 746 function is the value of the property. Unlike other properties, | |
| 747 the property is read only and can not be changed. Use cases: | |
| 748 ask a remote interface for a value (e.g. retrieve user's office | |
| 749 location from ldap, query state of a related ticket from | |
| 750 another roundup instance). It can be used to compute a value | |
| 751 (e.g. count the number of messages for an issue). The type | |
| 752 returned by the function is the type of the value. (Note it is | |
| 753 coerced to a string when displayed in the html interface.) At | |
| 754 this time it's a partial implementation. It can be | |
| 755 displayed/queried only. It can not be searched or used for | |
| 756 sorting or grouping as it does not exist in the back end | |
| 757 database. | |
| 744 Date | 758 Date |
| 745 properties store date-and-time stamps. Their values are Timestamp | 759 properties store date-and-time stamps. Their values are Timestamp |
| 746 objects. | 760 objects. |
| 747 Interval | 761 Interval |
| 748 properties store time periods rather than absolute dates. For | 762 properties store time periods rather than absolute dates. For |
| 4044 to the columns and columns_showall lists in your ``page.html``:: | 4058 to the columns and columns_showall lists in your ``page.html``:: |
| 4045 | 4059 |
| 4046 columns string:id,activity,due_date,title,creator,status; | 4060 columns string:id,activity,due_date,title,creator,status; |
| 4047 columns_showall string:id,activity,due_date,title,creator,assignedto,status; | 4061 columns_showall string:id,activity,due_date,title,creator,assignedto,status; |
| 4048 | 4062 |
| 4063 Adding a new Computed field to the schema | |
| 4064 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 4065 | |
| 4066 Computed properties are a bit different from other properties. They do | |
| 4067 not actually change the database. Computed fields are not contained in | |
| 4068 the database and can not be searched or used for sorting or | |
| 4069 grouping. (Patches to add this capability are welcome.) | |
| 4070 | |
| 4071 In this example we will add a count of the number of files attached to | |
| 4072 the issue. This could be done using an auditor (see below) to update | |
| 4073 an integer field called ``filecount``. But we will implement this in a | |
| 4074 different way. | |
| 4075 | |
| 4076 We have two changes to make: | |
| 4077 | |
| 4078 1. add a new python method to the hyperdb.Computed class. It will | |
| 4079 count the number of files attached to the issue. This method will | |
| 4080 be added in the (possibly new) interfaces.py file in the top level | |
| 4081 of the tracker directory. (See interfaces.py above for more | |
| 4082 information.) | |
| 4083 2. add a new ``filecount`` property to the issue class calling the | |
| 4084 new function. | |
| 4085 | |
| 4086 A Computed method receives three arguments when called: | |
| 4087 | |
| 4088 1. the computed object (self) | |
| 4089 2. the id of the item in the class | |
| 4090 3. the database object | |
| 4091 | |
| 4092 To add the method to the Computed class, modify the trackers | |
| 4093 interfaces.py adding:: | |
| 4094 | |
| 4095 import roundup.hyperdb as hyperdb | |
| 4096 def filecount(self, nodeid, db): | |
| 4097 return len(db.issue.get(nodeid, 'files')) | |
| 4098 setattr(hyperdb.Computed, 'filecount', filecount) | |
| 4099 | |
| 4100 Then add:: | |
| 4101 | |
| 4102 filecount = Computed(Computed.filecount), | |
| 4103 | |
| 4104 to the existing IssueClass call. | |
| 4105 | |
| 4106 Now you can retrieve the value of the ``filecount`` property and it | |
| 4107 will be computed on the fly from the existing list of attached files. | |
| 4108 | |
| 4109 This example was done with the IssueClass, but you could add a | |
| 4110 Computed property to any class. E.G.:: | |
| 4111 | |
| 4112 user = Class(db, "user", | |
| 4113 username=String(), | |
| 4114 password=Password(), | |
| 4115 address=String(), | |
| 4116 realname=String(), | |
| 4117 phone=String(), | |
| 4118 office=Computed(Computed.getOfficeFromLdap), # new prop | |
| 4119 organisation=String(), | |
| 4120 alternate_addresses=String(), | |
| 4121 queries=Multilink('query'), | |
| 4122 roles=String(), | |
| 4123 timezone=String()) | |
| 4124 | |
| 4125 where the method ``getOfficeFromLdap`` queries the local ldap server to | |
| 4126 get the current office location information. The method will be called | |
| 4127 with the Computed instance, the user id and the database object. | |
| 4128 | |
| 4049 Adding a new constrained field to the classic schema | 4129 Adding a new constrained field to the classic schema |
| 4050 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 4130 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 4051 | 4131 |
| 4052 This example shows how to add a new constrained property (i.e. a | 4132 This example shows how to add a new constrained property (i.e. a |
| 4053 selection of distinct values) to your tracker. | 4133 selection of distinct values) to your tracker. |