Enable browsing of projects by date and category

Screenshot. With incorrect breadcrumb, confirming that this is indeed rough!

Don't know what void the attachments disappeared into. Here, for what it's worth, is the pre-forms api changes patch I posted before. I'm hoping to get time to work on this next week, and will post an improved patch as soon as I can.

Okay, here's a more polished patch. The trickiest part was ensuring that paths are set correctly to conform with MENU_DEFAULT_LOCAL_TASKs. A $base_url variable is used, and added to selectively, i.e., only when the url fragment in question isn't the default local task and therefore needs to be included.

Sort option is a configuration option. Setting it to 'categories' will bring up the category navigation by default.

As well as the local tasks, I've added in a block for category navigation (this was issue #32394). The block displays only when we are browsing projects by category, and lists available categories by version.

Testing steps:
* apply patch
* ensure you have some test projects, ideally with versioned releases
* click the 'projects' link in navigation

A test version is up temporarily at:

http://www.islandnet.com/~nedjo/costarica/?q=project

I've done some basic testing but more would be great. E.g., I haven't looked closely at how this works when taxonomy is disabled, or when we are not browsing by version.

How does the basic approach look? Any suggested tweaks, or wish list items for what this doesn't do?

Bugfix in block (and leaving out release.inc changes from previous patch, designed to refresh cached release version listing as needed--this should be a separate issue.).

Thanks for the cogent comments.

Under categories, when I click on the "cvs" revision, and click one of the categories listed there (utility, widgets) I get the error:

Thanks, fixed in attached patch.

How does the "recent" list get its date/time value? Is it based on when the project was created, when the project description was last updated? Or (most peoples' preference, but may not be achievable) on when the last CVS commit was issued to the project?

When the patch at http://drupal.org/node/37927 is committed (reviews anyone?), we'll be able to sort by CVS commit change date.

that if there aren't any "xml" projects, "xml" shouldn't be displayed in the category list, else it's just a click that goes nowhere

Good point. The code does do this check. I think we're seeing the result of some data anomoly from my various previous test projects, i.e., a project categorized as xml whose manually-created release doesn't have a file and so isn't showing up.

As more reviews come in I'll work on revisions including suggestions like showing dates/categories.

Here's an updated patch implementing many of the suggestions/requests. The updated demo is at (same place):

http://www.islandnet.com/~nedjo/costarica/?q=project

The main visible changes are:

* implemented category choices as tertiary/third-level local tasks
* breadcrumbs (I think) fixed, redundant labels/titles eliminated
* primary task tabs read 'browse by category', 'browse by date', etc.
* &tid=x removed from url
* browse by date shows last changed time
* deleted the block

Changes in coding approach:

* factored out sorting methods into a single hook function project_project_sort_methods(). This provides a clear basis for later adding in further sorting methods.

Problems at this point:

* When browsing by category, the secondary local task tabs don't register the 'active' task (except when the third-level local task is the DEFAULT_LOCAL_TASK). I'm having a hard time troubleshooting this problem, as I don't follow well how menu.inc handles determination of what is on the active path. Help on this from a menu guru would be very welcome.

Comments:

* It's a challenge to get these sorting methods to work in all the various scenarios possible in project.module: taxonomy is enabled or not, we're browsing by version or not, etc. I've taken the approach of introducing full functionality for the drupal.org configuration- taxonomy enabled, browsing by version - and then selectively disabling methods in other configurations when enabling them is too difficult. E.g., I've disabled browsing by category when we have browsing by version disabled.

Found the local tasks solution (thanks to Richard Archer for troubleshooting help). It was a css issue that should probably be fixed in drupal.css, so I posted a patch, http://drupal.org/node/38862. Failing that I could just add a couple of lines to project.css. The test site is now displaying correctly.

at least it should remember my last chosen version and choose that as default on another tab

Sounds useful. Would I do this through sessions?

I beleive we need to have more then one vocabulary

I'm thinking of this as only one way of categorizing the content. We can add additional vocabs as well, but it would seem messy to mix them into this same interface.

Thanks for comments, I'll get coding. Some quick thoughts/questions meantime.

When I click on 'browse by category' I expect my focus to be drawn to a list of available categories. Instead several layers of tabs pop up. Where are the categories?

Would it help if we presented the categories differently, e.g., as a list? The certainly don't have to be tabs.

When I click on 'browse by date' I expect my focus to be drawn on dates. I think there should be <h2>$date</h2> tags separating projects by date. Right now, the Last changed changed date is tiny. The Last change date should be added to the project overview page.

Can do. This would be consistent with cvslog. (Maybe I'll look there to crib code.)

What is the "3.x | 5.x | hello | 4.x | cvs" abount? I think that bar should go on all pages. It gets in the way and is seriously distracting.

What I've done is retain the browsing by version that's currently in the module as a second-level local task. Dries, are you saying you'd prefer to ax this altogether, and have lists that mixed versions? E.g., if we're viewing modles in a particular category, we'd see a list of modules that could be any version, then we'd pull up specific listings and see if they included the version we're looking for?

I agree this would make the presentation simpler. But I'm thinking of Ber's point above,

I beleive the primary browsing method is the version

. Eliminating the version altogether from browsing/sorting would have some cost in terms of user expectations. And it will require a lot of recoding :). Maybe I'm just feeling lazy, but I'm wondering if we can get some user feedback on this before stripping out the version browsing. Maybe I'll post a question to the development list.

The breadcrumbs/title on ?q=node/1/release are not correct.

I don't *think* that's caused by this patch. I'll take a look and maybe open another issue (or eat my words).

Sometimes one horizontal rulers is emitted, sometimes two rulers are emitted.

On my demo site, I think this just reflects empty data (lack of categorized themes).

Here's a fixed up patch. Changes:

* Eliminated version local tasks. We now have a select control, labeled "Filter by version", that can be used to select a particular version. As per Ber's suggestion, once set, the version persists across a session. (If the configuration option for browsing by version is set to disabled, this control disappears.)

* When browsing by category, available categories are in collapsible fieldset, expanded when no term has been selected and collapsed when there is a term selected. This way users can easily switch to a different category, but screen space isn't cluttered. Added list-style-image to visually identify the active category in the list. Added numbers of projects next to the categories.

* Added links to categories to project view. Disabled the regular $node->taxonomy links, as they lead to the taxonomy/term/tid path, not useful in this case.

* Added date headline separator when browsing by date.

* Added block for quickly navigating to a particular project. This addresses the "I already know what project I want, I just want to get to it" need. It can also be a quick way to browse all projects by name.

* Several minor formatting and similar changes.

Updates viewable at:

http://www.islandnet.com/~nedjo/costarica/?q=project/Modules/

Fix to a couple of errors in the previous patch, e.g., sort order in listings (I'd used n.title DESC instead of ASC), plus a bit of cleanup.

Here's a new patch addressing issues and suggestions. There are two areas I'd like some final guidance on (see end of this post).

Changes made:

css names should not use underscores. Use dashes instead.

I couldn't find a place where I had done this.

Do we need the new CSS definiations? Can we reuse the normal arrows? Just making sure we're not mixing styles.

I had used the new styles to further highlight the currently selected term, but for simplicity and consistency I've dropped this.

I think you can drop the 'quick' from the project block.

Done

The project settings page (admin/settings/project) could use some fieldsets.

Separate issue, not done here.

The following code looks somewhat hairy -- and possibly dangerous. You're doing a goto to user-supplied data. Better make sure it's 100% secure and that it can't be used for XSS attackes. It's a bad idea in general.
+function project_goto() {
+ if ($_POST['edit']['project_goto']) {
+ drupal_goto($_POST['edit']['project_goto']);
+ }
+ else {
+ drupal_goto($_POST['edit']['caller']);
+ }
+}

Hmm. What I'm doing is not much different from the drupal_goto(), which goes to a REQUEST (hence, user-supplied) variable. I'm not sure offhand how to improve this.

Ditto for the following code. Be careful with storing user-supplied data in session variables. Normally, you should not use $_POST. Instead you should use the filtered/validated data that is given to you by the forms API (typically, $form_values).
+ if ($_POST['edit']['rid']) {
+ $version = $_POST['edit']['rid'];
+ $_SESSION['project_version'] = $version;
+ }
+ else if ($_SESSION['project_version']) {
+ $version = $_SESSION['project_version'];
+ }
+ else {
+ $version = variable_get('project_release_overview', -1);
+ }

I've reworked this to use $form_values.

- You might need a check_plain() here (XSS):
+ $output .= '

' . $term->description . '

';

Done.

Make sure arg(3) is an integer:
+ $tid = arg(3) ? arg(3) : project_default_tid();
+ $term = taxonomy_get_term($tid);

Done.

Is $sort_method in project_page_overview() validated? Looks like you might be using raw user data without xss checking.

$sort_method isn't user-supplied here.

Can't you use the built-in destination-stuff instead of the newly introduce caller stuff?
+ $form['caller'] = array(
+ '#type' => 'hidden',
+ '#value' => $_REQUEST['q']
+ );

Yes, done.

For security, you might want to do a check_url() on + $output .= ">$link

\n";.

Done.

$link is not defined? You'll want to use check_plain() and check_url() here.
+function theme_project_type($term) {
+ $link = l($term->name, 'project/'. $term->name);
+ $output = '

' . $link . '

';
+ if ($term->description) {
+ $output .= '

' . $term->description . '

';
+ }
+ return $output;
+}

Done.

when i click "widgets" the ones listed under " handy widgets" should appear too

It's a good suggestion, but would require a bunch of recoding. I also noticed that how I had done this, with indenting of second+ level terms, didn't work because e.g. a project categorized into "mail" and "handy widgets" made it look like "handy widgets" was a subcategory of "mail". So, for now, I've just dropped the indenting. I suggest we keep this question in mind for a later patch.

Could you also auto-alias "/project/foo" to "/projects/foo".

Good idea, not done here.

the breadcrumb links don't seem to be of much use navigating.

This was a leftover problem from the taxonomy changes--project.inc chose the first matching term for the breadcrumb. I've fixed this in project_project_set_location().

i'd like the project's node view to display the node's versions

Yes, not done here.

i wonder if empty categories should be listed

Hmm. I'm hoping this won't be an issue on drupal.org, as we'll fill categories as we create them.

Remaining issues

1. While what we've done here should work fine for modules and themes, it's not going to work for the Drupal project, since that single project doesn't need categorization etc. Here's how the page looks on my test site:

http://www.islandnet.com/~nedjo/costarica/?q=project/Drupal+project

How should we handle this?

2. We really need to improve the display at /project. Here's my test site:

http://www.islandnet.com/~nedjo/costarica/?q=project

We should be showing information (at least descriptions) of each project type. What else? First few listings from each browsing sort_option (category, date, name), with link to more?

Attached is the version of this large patch that I just applied. There were no remaining errors on testing, but no doubt it will need further tweaks as it is used and extended.

Significant changes since the previous version of this patch:

1. SQL for browsing queries reworked to be generated on the basis of nested arrays (somewhat comparable to Forms API). This allows cleaner implementation.

2. Previously projects were first selected and then a second query was done on each project in the result set to see if there was a release. We now test for releases (if appropriate) in the initial query, so these costly extra queries have been eliminated.

3. The project_sort_options hook options have been simplified/reduced in number.

4. We use a _term_path() hook so provide the correct path for terms in the projects vocabulary.

(The patch included a couple of unrelated cleanup details.)

I'll be available for fixes as necessary later in the week (I'm on the road for the next couple of days).

The handling is different depending on whether or not you're browsing by release, and wheter taxonomy is enabled. It may be that I've made an error when no releases are present, or when we are not browsing by releases.

Do you have taxonomy enabled? If so, have you created multi-level categories in the Projects vocabulary, and do you have projects categorized by top-level and secondary-level category? (Category options will only appear when browsing by category if there are categories with projects assigned to them.)

What are your settings at administer > settings > project for

* Browse projects by releases
* Default release overview

And have you run cron or scanned for releases? Do you have projects with releases (and accompanying files)?

The issue you report should be resolved by the recent fix for issue #48054. If not, please reopen that issue.