RFC: Change to Report Options API

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

RFC: Change to Report Options API

Brian Matherly
Based on some developer feedback and my own experience, I've been considering some changes to the report interface. One change affects the way options are handled by reports.

Currently, reports pass a "ReportOptions" class into the report system. That ReportOptions class defines options. If it is invoked by the GUI, it also defines the graphical widgets to display options to the user and adds them to a dialog. It also parses those graphical widgets if it is invoked by the GUI. If it is running as command line, the Widgets are ignored.

I would like change the paradigm slightly to remove some of the responsibilities from the report. I want to move to a model where the options class receives a "menu" class and adds "Options" to it. The report system will be responsible for displaying those options to the user. If it is running as CLI, it will pretty much work the same as it does now. If it is running as GUI, the report system will be responsible for defining the GUI Widgets and parsing the values from them (not the individual report).

Here is some rough code to show how it would work. This code is just meant to illustrate how it could work. It is not complete.

The Menu class is just a collection of options. The category allows the options to be grouped together and categorized by name. A GUI would use this to put the options on different tabs. The CLI could use the categories to format the help screens in an organized manor.

    class Menu:
        def __init__(self):
            self.__options = {}
       
        def add_option(self,category,name,option):
            if not self.__options.has_key(category):
                self.__options[category] = {}
            self.__options[category][name] = option


The various types of options are defined according to their purpose.

Each Option type inherits from the option base class to inherit common functionality. Each option must have a label. A label would show on the GUI and explain the purpose of the option. Each option also has a value (of course). Each option also has a help string which can be used by the CLI when the user invokes help and can be used by the GUI as tooltips.

    class Option:
        def __init__(self,label,value):
            self.__value = value
            self.__label = label
            self.__help_str = ""
       
        def get_value(self):
            return self.__value
   
        def set_value(self,value):
            self.__value = value
       
        def set_help(self,help):
            self.__help_str = help
       
One type of option is a string option. In the GUI, it would be displayed as a single line text box. In the CLI, it would be a quote enclosed string.

    class StringOption(Option):
        def __init__(self):
            pass

The number option would be displayed as a spinbox in the GUI and would be a number option on the CLI. It has a max and min for validation.        

    class NumberOption(Option):
        def __init__(self,label,value,min,max):
            Option.__init__(self,label,value)
            self.__min = min
            self.__max = max

The text option would be displayed as a multi-line text box in a GUI. In the CLI, the user would separate lines with a "\n" in a single string. The user can specify the maximum number of lines for the text.

    class TextOption(Option):
        def __init__(self,label,value,max_lines):
            Option.__init__(self,label,value)
              self.__max_lines = max_lines

The boolean option would be displayed as a check box in a GUI. It would be a number option in the CLI where the only valid options are "0" or "1".        

    class BooleanOption(Option):
        def __init__(self,label,value):
            Option.__init__(self,label,value)

The EnumeratedListOption would be displayed as a combo box in a GUI. It would be a number option in the CLI, but the help will print the text description of each value.

    class EnumeratedListOption(Option):
        def __init__(self):
            self.__items = {}
       
        def add_item(self,value,name):
            self.__items[value] = name


There might be more options that are needed, but I think these are the ones needed by the existing reports.

A report would use these options by adding them to the menu that gets passed to the ReportOptions class. For example, the AncestorChart report option class would look like this:

    class AncestorChartOptions(ReportOptions):

        def __init__(self,name,person_id=None):
            ReportOptions.__init__(self,name,person_id)

        def set_new_options(self,menu):

            max_gen = NumberOption("Generations",10,1,50)
            max_gen.set_help("The number of generations to include in the report")
            menu.add_option("Report","max_gen",max_gen)
       
            disp = TextOption(_("Display Format"),
                              "$n\n%s $b\n%s $d" % (_BORN,_DIED), 4)
            disp.set_help("Display format for the outputbox.")
            menu.add_option("Report","dispf",disp)
       
            scale = BooleanOption(_('Sc_ale to fit on a single page'),True)
            scale.set_help("Whether to scale to fit on a single page.")
            menu.add_option("Report","singlep",scale)
       
            blank = BooleanOption(_('Include Blank Pages'),True)
            blank.set_help("Whether to include pages that are blank.")
            menu.add_option("Report","incblank",blank)
       
            compress = BooleanOption(_('Co_mpress chart'),True)
            compress.set_help("Whether to compress chart.")
            menu.add_option("Report","compress",compress)

This would pretty much be it from a report writing perspective. The "add_user_options" and "parse_user_options" would go away. Compare it to the existing Ancestor report options class and you can see that it is much simpler.

I would be very interested in anyone's comments, questions and suggestions about this idea.

Thanks,

~Brian



-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Gramps-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/gramps-devel
Reply | Threaded
Open this post in threaded view
|

Re: RFC: Change to Report Options API

Stéphane Charette-2
> This would pretty much be it from a report writing perspective. The
>"add_user_options" and "parse_user_options" would go away. Compare it to
>the existing Ancestor report options class and you can see that it is much
>simpler.

Any chance of leaving the original interface intact as well?  This
would allow existing "unsupported" plugins to continue to work.

In my case, I also use controls such as TreeViews and ColorButtons,
which aren't listed in your e-mail.  I don't fully understand the
implications of your e-mail -- would we have a way to continue to
instantiate and use these controls?

Stephane

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Gramps-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/gramps-devel
Reply | Threaded
Open this post in threaded view
|

Re: RFC: Change to Report Options API

Brian Matherly
In reply to this post by Brian Matherly
Stephane,

>> This would pretty much be it from a report writing perspective. The
>>"add_user_options" and "parse_user_options" would go away. Compare it to
>>the existing Ancestor report options class and you can see that it is much
>>simpler.

>Any chance of leaving the original interface intact as well?  This
>would allow existing "unsupported" plugins to continue to work.

I wasn't planning on it. But that doesn't mean we can't. It just means more complex code to maintain and document. We might also lose part of the advantage of improving the API. We would just be adding to it instead. It is my hope that we can remove the old way of adding options and that the new way will be so easy that anyone could update the old reports to support the new method.

>In my case, I also use controls such as TreeViews and ColorButtons,
>which aren't listed in your e-mail.

At this point, I only plan on having this affect the reports. I think the "tool" plugins would continue to define their own GUI widgets for now - as they typically have more demanding needs for displaying information. If you use TreeViews and ColorButtons for a report, how does it work from the CLI? Could you use comoboxes instead? If you NEED those controls, we could add them. I just wrote the ones I could think of.

>I don't fully understand the implications of your e-mail
> -- would we have a way to continue to
>instantiate and use these controls?

The goal is to create a common set of "option types" for report authors to choose from. The report system would determine how best to present these options to the user (which widgets to use, etc). If we need to add more option types, we can always do that.

Thanks for your questions. I hope I answered them clearly. This is exactly the kind of dialog I'm looking for.

~Brian




-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Gramps-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/gramps-devel
Reply | Threaded
Open this post in threaded view
|

Re: RFC: Change to Report Options API

bm-5
Quoting Brian Matherly <[hidden email]>:

> Stephane,
>
>>> This would pretty much be it from a report writing perspective. The
>>> "add_user_options" and "parse_user_options" would go away. Compare it to
>>> the existing Ancestor report options class and you can see that it is much
>>> simpler.
>
>> Any chance of leaving the original interface intact as well?  This
>> would allow existing "unsupported" plugins to continue to work.
>
> I wasn't planning on it. But that doesn't mean we can't. It just
> means more complex code to maintain and document. We might also lose
> part of the advantage of improving the API. We would just be adding
> to it instead. It is my hope that we can remove the old way of adding
> options and that the new way will be so easy that anyone could update
> the old reports to support the new method.

Some points:

* code generation report (graphviz) is overruling some of the common
options in
reports. It looks a bit ugly as it is done in my opinion. I started writing
also such a report (for googleearth). Should we make those a tool
instead? Or a
separate class or reports writing to a file format for use in other programs.
The narative website is also in this section. Styles, print options,
... of the
other reports have no meaning. So perhaps a base class for these, and a
derived
class adding all the printing options

* filter support. Options to define filters are important, and specifically
easily preset filters. I'm thinking of a person filter, but also a
note/place/attribute... filter to combine with that, think a narrative website
where you say these people, and print only notes that satisfy a note
filter and
attributes satisfying yet another filter.
So a premade 'filter' tab with some logic predone to easily set this

* I agree to dropping the old api if a new one is presented, however, dropping
the old api looks more like something for a 3.0 version of GRAMPS, and
not 2.4.

* option parsing is needed, no? If you say :
TextOption(_("Display Format"),
                              "$n\n%s $b\n%s $d" % (_BORN,_DIED), 4)
why not allow to set a parsing function testing if the input of the user is
valid? This would remove this logic from the report which I think is cleaner
code.

* Allow all reports to be automatically usable for CLI. The only thing missing
to do this is that in the report sometimes a warning dialog, an error
dialog or
a progress dialog is shown. Making special report versions of these
would allow
the report writer to forget if it is CLI or not that runs the program: he gets
the options, the report is run, if a warning needs to be shown, you call
ReportWarning('warning') and this automatically translates to CLI or GUI
depending of how the report is called

>> In my case, I also use controls such as TreeViews and ColorButtons,
>> which aren't listed in your e-mail.
>
> At this point, I only plan on having this affect the reports. I think
> the "tool" plugins would continue to define their own GUI widgets for
> now - as they typically have more demanding needs for displaying
> information. If you use TreeViews and ColorButtons for a report, how
> does it work from the CLI? Could you use comoboxes instead? If you
> NEED those controls, we could add them. I just wrote the ones I could
> think of.
>
>> I don't fully understand the implications of your e-mail
>> -- would we have a way to continue to
>> instantiate and use these controls?
>
> The goal is to create a common set of "option types" for report
> authors to choose from. The report system would determine how best to
> present these options to the user (which widgets to use, etc). If we
> need to add more option types, we can always do that.
>
> Thanks for your questions. I hope I answered them clearly. This is
> exactly the kind of dialog I'm looking for.
>
> ~Brian
>
>
>
>
> -------------------------------------------------------------------------
> This SF.net email is sponsored by DB2 Express
> Download DB2 Express C - the FREE version of DB2 express and take
> control of your XML. No limits. Just data. Click to get it now.
> http://sourceforge.net/powerbar/db2/
> _______________________________________________
> Gramps-devel mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/gramps-devel
>



----------------------------------------------------------------
This message was sent using IMP, the Internet Messaging Program.

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Gramps-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/gramps-devel
Reply | Threaded
Open this post in threaded view
|

Re: RFC: Change to Report Options API

Brian Matherly
In reply to this post by Brian Matherly
Benny,

>* code generation report (graphviz) is overruling some of the common
>options in
>reports. It looks a bit ugly as it is done in my opinion. I started writing
>also such a report (for googleearth). Should we make those a tool
>instead? Or a
>separate class or reports writing to a file format for use in other programs.
>The narative website is also in this section. Styles, print options,
>... of the
>other reports have no meaning. So perhaps a base class for these, and a
>derived
>class adding all the printing options

It sounds like you read my mind. This is another part of the report system that I want to change. I think we will have a "Report" class which will be used by stand-alone reports like the GraphViz and Narrative Web, and a "GeneratedReport" class that has styles, BaseDoc and whatever else. That's one of the next issues I want to tackle, but isn't part of this RFC. Right now I'm just concentrating on report options. In the context of report options, I want to make sure that the new API supports the graphviz and narrativeweb type reports as well as the ones the use BaseDoc to generate reports.

>* filter support. Options to define filters are important, and specifically
>easily preset filters. I'm thinking of a person filter, but also a
>note/place/attribute... filter to combine with that, think a narrative website
>where you say these people, and print only notes that satisfy a note
>filter and
>attributes satisfying yet another filter.
>So a premade 'filter' tab with some logic predone to easily set this

Right now, the reports implement filter selection with a combobox. Following that convention, in the proposed API, they would work the same, but the report would add the filters to an "EnumeratedListOption". The report system would worry about how to render that to the user. But I can see the advantage of having a specific "FilterOption" type of option. I'll look into adding that.

>* I agree to dropping the old api if a new one is presented, however, dropping
>the old api looks more like something for a 3.0 version of GRAMPS, and
>not 2.4.

*wink*

>* option parsing is needed, no? If you say :
>TextOption(_("Display Format"),
>                              "$n\n%s $b\n%s $d" % (_BORN,_DIED), 4)
>why not allow to set a parsing function testing if the input of the user is
>valid? This would remove this logic from the report which I think is cleaner
>code.

Parsing would be done by the report system because the GUI will be parsed much differently than the CLI. But VALIDATION should be done by the report. So I could add a "validate" method to the option. Good thinking.

>* Allow all reports to be automatically usable for CLI. The only thing missing
>to do this is that in the report sometimes a warning dialog, an error
>dialog or
>a progress dialog is shown. Making special report versions of these
>would allow
>the report writer to forget if it is CLI or not that runs the program: he gets
>the options, the report is run, if a warning needs to be shown, you call
>ReportWarning('warning') and this automatically translates to CLI or GUI
>depending of how the report is called

Another excellent idea that, I think, falls just outside of this conversation. But your comment definitely shows that we are in sync in the way we are thinking about improvements to the system.

Thanks for taking the time to comment. I really value your insight.

~Brian





-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Gramps-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/gramps-devel
Reply | Threaded
Open this post in threaded view
|

Re: RFC: Change to Report Options API

Stéphane Charette-2
In reply to this post by Brian Matherly
On 5/5/07, Brian Matherly <[hidden email]> wrote:

> Stephane,
>
> >> This would pretty much be it from a report writing perspective. The
> >>"add_user_options" and "parse_user_options" would go away. Compare it to
> >>the existing Ancestor report options class and you can see that it is much
> >>simpler.
>
> >Any chance of leaving the original interface intact as well?  This
> >would allow existing "unsupported" plugins to continue to work.
>
> I wasn't planning on it. But that doesn't mean we can't. It just means more complex code to maintain and document. We might also lose part of the advantage of improving the API. We would just be adding to it instead. It is my hope that we can remove the old way of adding options and that the new way will be so easy that anyone could update the old reports to support the new method.
>
> >In my case, I also use controls such as TreeViews and ColorButtons,
> >which aren't listed in your e-mail.
>
> At this point, I only plan on having this affect the reports. I think the "tool" plugins
>would continue to define their own GUI widgets for now - as they
typically have more
>demanding needs for displaying information. If you use TreeViews and
ColorButtons
>for a report, how does it work from the CLI? Could you use comoboxes
instead? If you
>NEED those controls, we could add them. I just wrote the ones I could think of.

Please download the FamilyLines.py plugin and take a look.

http://charette.no-ip.com:1234/Charette/FamilyLines.py

It is a report, not a tool.  It'll show up in the same category as the
existing Graphviz plugin.  No, I don't believe the treeviews I use can
be replaced with comboboxes.  I don't know how to use plugins from the
CLI, and I didn't fully understand how NarrativeWeb.py and the
Graphviz plugin supported this, so I don't spend much time trying to
support this functionality.

Stephane

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Gramps-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/gramps-devel
Reply | Threaded
Open this post in threaded view
|

Re: RFC: Change to Report Options API

Brian Matherly
In reply to this post by Brian Matherly
Stephane,

>> >In my case, I also use controls such as TreeViews and ColorButtons,
>> >which aren't listed in your e-mail.
>>
>> At this point, I only plan on having this affect the reports. I think the "tool" plugins
>>would continue to define their own GUI widgets for now - as they
>typically have more
>>demanding needs for displaying information. If you use TreeViews and
>ColorButtons
>>for a report, how does it work from the CLI? Could you use comoboxes
>instead? If you
>>NEED those controls, we could add them. I just wrote the ones I could think of.

>Please download the FamilyLines.py plugin and take a look.
>
>http://charette.no-ip.com:1234/Charette/FamilyLines.py
>
>It is a report, not a tool.  It'll show up in the same category as the
>existing Graphviz plugin.  No, I don't believe the treeviews I use can
>be replaced with comboboxes.  

In order to support your list of "people of interest", I think we would have to implement a "PersonListOption" class. In a GUI environment, the Report system would implement it just like you did (using the Person Selection dialog). The CLI would probably just allow the user to enter a list of comma separated gramps ids.

Your color selection is a bit different. My first impression (not knowing all the use cases for this report) would be to suggest that you drastically reduce the flexibility that you offer the user. For example, instead of allowing the user to select any possible color for each surname and family element, you could just have a checkbox option called "color code families". If the user selects that option, the report would automatically select a new complimentary color for each family. This is how the fan chart report works, and I like it. But like I said, I don't know the exact needs of the users for this report.

Fundamentally, I think we could find a way to support the options you need for this report. But the way you do things now does make it more difficult.

>I don't know how to use plugins from the
>CLI, and I didn't fully understand how NarrativeWeb.py and the
>Graphviz plugin supported this, so I don't spend much time trying to
>support this functionality.

It sounds like you are EXACTLY the kind of person who would benefit from an improved API. This is the whole reason I'm doing this. Another reason that you would benefit from this proposed API is that your report is almost unusable in Windows because of some slight differences in GTK between Windows and Linux. If the GUI elements were handled by the report system, you wouldn't have to worry about it.

Thanks for bringing your report to my attention. I'll certainly take it into consideration as I proceed. Feel free to stay as involved as you want during this process.

~Brian




-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Gramps-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/gramps-devel