More flexible configuration of browser quickjump facility

[Ryan Ollos <ryano@…>]

This ticket summarizes the discussion starting in comment:3:ticket:4223.

The proposed enhancement is to create a [browser-quickjump] section in trac.ini, which will be used to configure the quickjump facility in TracBrowser. A screen capture of the current quickjump facility on a Trac instance with a Subversion repository is shown below.

In the case of a Subversion backend, the browser quickjump facility is currently configured in TracIni#svn-section. I'm told that no configuration is required for a Mercurial back-end, and I'm not sure how other repositories might be configured.

The current limitations are:

• It is not possible to define your own group headings. For an svn back-end the group headings are branches and tags.
• It is not possible to have a list of entries with no group heading.

The proposal is to define a new section:

[browser-quickjump]
Common = /Common/*
Utilities = /Utilities/*
Test and Measurement = /Test and Measurement/*

Product =  /Presto/Product/Software/*,
           /Presto/Product/Docs/Released/*

Prototypes = /Presto/Prototype/Verasonics Matlab Simulator/*,
             /Presto/Prototype/PSI Development/*

R&D = /Presto/R&D/Software/*

The text to the left of the equals sign would define a section heading for the corresponding list of paths.

Comments and other ideas are welcome and appreciated.

[Ryan Ollos <ryano@…>]

If someone takes a look at this and immediately knows how it could be done, and would be willing to give me a 2-3 sentence description of were I need to look to implement this, that would really help me out! I know shell scripting/C++/C#/MATLAB very well, but I don't know much python or the internals of Trac, and I'm looking to start contributing. It's just a bit overwhelming at first, even given the developer documentation that exists.

[cboos]

Generic tip: start with the page demonstrating the feature you'd like to modify, look at the source, lookup the corresponding Genshi template, see which data fields are being used, look them up in the corresponding module in the Python code, and from there you should be able to follow the code dependencies.

In this case, this translates to:

/browser/trunk's XHTML:

<div id="jumploc"> 
        <form action="" method="get"> 
          <div class="buttons"> 
            <label for="preselected">Visit:</label> 
            <select id="preselected" name="preselected"> 
              <option selected="selected"></option> 
              <optgroup label="branches"> 
                <option value="/browser/trunk">trunk</option><option value="/browser/branches/0.5- ...

Which corresponds to source:trunk/trac/versioncontrol/templates/browser.html@8515:61-75#L33​

      <div py:if="quickjump_entries" id="jumploc">
62              <form action="" method="get">
63                <div class="buttons">
64                  <label for="preselected">Visit:</label>
65                  <select id="preselected" name="preselected">
66                    <option selected="selected" />
67                    <optgroup py:for="category, locations in groupby(quickjump_entries, key=lambda q: q[0])"
68                      label="${category}">
69                      <option py:for="_, name, path, rev in locations" value="${href.browser(path, rev=rev)}">$name</option>
70                    </optgroup>

So, you need to find how quickjump_entries is defined, and this is in source:trunk/trac/versioncontrol/web_ui/browser.py@8515:352-366#L363​:

 'quickjump_entries': xhr or list(repos.get_quickjump_entries(rev)),

which leads you to source:trunk/trac/versioncontrol/api.py@8515:222-230:#L222​

    def get_quickjump_entries(self, rev):
        """Generate a list of interesting places in the repository. 
        ...
        The generated results must be of the form (category, name, path, rev).
        """
        return []

This means that currently this is a no-op, that backends are free to implement the way they wish.

Now here we're talking about extending this feature in a way that would benefit to all backends. We can't extend directly Repository.get_quickjump_entries as this would imply having all the backends modified to call the overriden method.

So we need to put the code in web_ui/browser.py, maybe in a new helper method.

    'quickjump_entries': xhr or self.get_extended_quickjump_entries(rev),

That BrowserModule.get_extended_quickjump_entries method would do:

   entries = list(repos.get_quickjump_entries(rev))

And then we would have to read the new config section:

   browser_quickjump = self.config['browser-quickjump']

Look at source:trunk/trac/config.py@8515​ for the API of Configuration, Section and Option.
You can simply iterate through the entries:

    for key in browser_quickjump:
        for pattern in browser_quickjump.getlist(key):
            path, rev = pattern.split('@', 1)
            if '*' in path:
                self.log.warning("fnmatch pattern support not implemented")
                # see trac/versioncontrol/svn_fs.py for hints
            else:
                entries.append((key, path, path, rev))

Something like that ...

Happy hacking, and don't worry, most of us here started "diving into Python" just because of Trac ;-)

[Ryan Ollos <ryano@…>]

Thanks for the excellent overview! I think I would have been fairly confused, particularly by the no-op. I'll get back to you soon after I've made a couple of attempts at this ...

[cboos]

Milestone 2.0 deleted