Improve User Relationships Documentation [#1229446]

I noticed there are no longer any tpl files included in the module so nothing to copy over to theme. I've been looking at various theme related issues in the queue but don't see anything particularly helpful in terms of documenting the theming of this module. There are a few good posts (more people seem concerned with getting a user avatar to display) but overall theming every aspect of the module and/or providing embed codes don't seem to show up anywhere.

Basically, what I'm looking for is the ability to alter the theme of user/uid/relationships as well as the display on user/uid account page. For example, I don't want the default table on user/uid/relationships and more of a grid display with names and pictures.

BTW, how can I get the module to recognize the URL patterns I have set on the site? For example, my patterns are set like site/user/user-name but navigating to the relationships tab is site/user/6/relationships.

Thanks. Even if there are no docs on this, if you know of any discussions on this off the top of your head I'd appreciate it.

Comments

Comment #1

RKS CreditAttribution: RKS commented 26 July 2011 at 04:21

I've been trying to get into this myself by bypassing everything and going to views. Is there any docs on your views actions? I don't mean to criticize but everything in there seems very counterintuitive and it's confusing as to what I need to add in order to accomplish what I want.

For example, adding the contextual filter of "is a relationship" should be very intuitive and describes exactly what you want to filter, the user's relationships. Instead, there are things like RFID, UR: Requester, UR: Requestee, etc.

You have over a thousand issues and some of these issues could have been solved by simply having thorough documentation. For example, embedding the "add to [relationship]" on a custom user profile is a popular issue and documentation could discuss this and get rid of marking duplicate issues, answering more and more people asking about it, etc.

So are there any resources to my original question or anything on bypassing your defaults using views?

Comment #2

mrf CreditAttribution: mrf commented 26 July 2011 at 16:16

Title:

Any docs on D7 theming?

» Improve User Relationships Documentation

The Drupal 7 version of the module is still changing so the best source of documentation right now is probably code comments and the d7 issues themselves. I've mainly focused on the d6 version so I can't help too much with d7.

That being said, all the documentation for user relationships is really limited and out of date, and any help there would be hugely appreciated. Just go in and start posting new pages and making edits, when I first encountered the project a year ago most of the docs were still referencing the Drupal 5 version and I've just made a few small edits to try and get it a little more current and remove things that were blatantly wrong.

If someone takes the time to get the basic stuff down, I'll make sure I find the time to review any new documentation pages and answer questions along the way.

How about leave this issue open and we can use it as a meta issue for tracking documentation.

Comment #3

RKS CreditAttribution: RKS commented 26 July 2011 at 23:14

I can help out where I can. What are you priorities for D7 docs right now?

Comment #4

mrf CreditAttribution: mrf commented 27 July 2011 at 16:54

I think documenting all of the add-on modules and what you can do with the module out of the box without any custom code is probably the biggest need right now.

Comment #5

mrf CreditAttribution: mrf commented 27 July 2011 at 17:37

Just went through and re-organized renamed and cleaned up some of the existing pages. Hopefully this structure will make it easier for people to find the part of the docs they are looking for.

Comment #6

RKS CreditAttribution: RKS commented 27 July 2011 at 19:24

I was reading through last night just to get a feel for what you're doing there. I didn't do anything spectacular since I just wanted to get a good outline but I did change some of your misspelled words :) (I know they're not YOUR misspelled words but you know what I mean.)

As for add on modules, I still have to explore them all since I haven't been using them all.

Comment #7

Berdir

German

Switzerland

CreditAttribution: Berdir commented 18 September 2011 at 19:31

Yeah, 7.x is still a moving target, especially regarding theming.

I think the documentation pages here on d.o aren't the perfect place for API/Developer documentation. I'm trying to get that into code, similar to what you have on http://api.drupal.org. The advantage of that is that it is easier to keep documentation up to date, because it can be done with the same patch that also changes something. However, the disadvantage is that changes need to happen through patches :)

In fact, I've already extended my personal API site (which contains the API documentation of all my projects) with UR: http://api.worldempire.ch/api/user_relationships.

However, as you can see there, documentation is sparse yet there. I'd be lovely if someone can/wants to work on this, here are some things that can be done:

1. The first step is to add a add @mainpage block to the user_relationships.api.php file (not necessary there, but I think it makes the most sense there). Here is an example from Userpoints, which I just recently started: http://api.worldempire.ch/api/userpoints/userpoints.api.php/7-2 (click on "view source"). It should give a developer-facing introduction to the module followed by list of topics/groups.

2. Then, start adding @group's, the obvious one would be API, but a theming group would also be important. Again, give a basic introduction to the topic, see http://api.worldempire.ch/api/privatemsg/privatemsg.theme.inc/group/them... for an example and then tag all hooks/functions which are related to this group by adding a @ingroup name to their docblock.

3. Improve existing docblocks or add ones to functions which don't have one, explain the arguments, add examples, ... Hooks are documented in the mentioned api.php file, preferable with a usage example directly in the function body. Some already have that, others don't.

All of this can be done in small steps, with separate patches, either in this issue or in separate issues.