Step By Step Guide: How To create your custom Group Content Type and its Browsing Widget Tab

This is a duplicate of #2069851: How to add custom tab to commons browsing widget.

I am going to add a basic step-by-step guide in a second. This issue seemed to be the best place to put it. Therefore I am going to mark the other issues addressing the same topic accordingly.

FYI: this how-to does not explain how to create a new group-type

This how-to does explain the single steps to take in order to implement a custom content type, which
can be associated with groups (group content). In order to achieve this task you are going to
create a custom feature you can keep in version control, export to another drupal commons site or what so ever.

Today we are going to create a custom issue tracker like the one your are visiting right now. [at least we do the first few steps :)]
Actually the beginning is pretty basic stuff only, so if you just want to know how to create your custom tab hop on to #5. (or better just have a look at #1782922: Document pattern for creating Commons-compatible group content type features)

1. Create your custom content type, e.g. "issue" (admin/structure/tpyes/add); set up as desired

2. Specify as group content (admin/structure/types/manage/issue -> organic groups)
a) select "group content" (Set the content type to be a group content, that can be associated with groups.)
b) select target type "node"; target bundles "group"

3. Create custom feature "issue" [not needed, but it's a good starting point for your custom module]
(admin/structure/features/create)
a) pick a fancy name and package, but remember to use a meaningful namespace, e.g. "My Issue Tracker"
b) always make use of the description field
c) -> components -> content types -> "issue"
d) if applicable select other related stuff like dependecies, field-instances, permissions (later on you can pick other components related to your new module, right away this should suffice)
d) -> advanced options -> generate feature [if your installation is set up correctly (write permissions etc), a new feature will be created in a accordingly named subfolder under the default export path]
e) -> manage; find your new feature and enable it -> save settings.
[TODO: put in a link to 'features', to 'custom modules creation']

4. have a look into the newly created folder; there you should find
a) my_issue_tracker.info: general information about your module
b) my_issue_tracker.module: your module's core. At the very moment it just contains one include_once statement including the following
c) my_issue_tracker.features.inc:

/**
 * Implements hook_node_info().
 */
function my_issue_tracker_node_info() {
  $items = array(
    'issue' => array(
      'name' => t('Issue'),
      'base' => 'node_content',
      'description' => t('A single issue which can be tracked, assigned to people, got different states and so on.'),
      'has_title' => '1',
      'title_label' => t('Title'),
      'help' => '',
    ),
  );
  return $items;
}

I guess, this is self-explaining.

d) maybe some other .inc files, according to the stuff you added to your feature on 3.d); e.g. my_issue_tracker.features.field_instances.inc if you added some custom fields to your new content type and selected them on feature construction.

5. Go back to your .module-file and add following code at the "bottom" of the file (i.e. after the include_once statement) to introduce your new content type to the commons browsing widget.

/**
* Implements hook_commons_bw_group_widget().
*/
function my_issue_tracker_commons_bw_group_widget() {
  return array(
    'my_issue_tracker' => array(
      'title' => t('Issues'),
      'type' => 'view',
      'vid' => 'commons_bw_posts', // we are going to change that to 'my_issue_tracker_group_' later
      'display' => 'default',
      'weight' => -1,
      'bundle' => 'post', // we are going to change that to 'issue' later
    ),
  );
}

FYI:
* At the moment I don't know if other types other than views are supported. I do remember a feature request for adding the ability to add other types... anyways,
* "vid" is the view id (= machine_name) of a view; We are going to change that "vid" soon to get some custom "issue" content on the page.
* "display" is the display of the view, use 'default' for now
* "weight" (as used elsewhere in drupal) specifies how 'heavy' an item is, i.e. how low it sinks down a list.
* "bundle": that's the node-bundle, i.e. your content-type. We are going to change that later.

6. right now you got your new TAB on the commons_browsing_widget, hurray! But wait... it doesn't show your "issues" but some "posts"...

7. We need to get a new view working: the fastest way is to clone an existing one at (admin/structure/views) or have a look at the following excursion for a diy
a) for example look for: Commons Browsing Widget - Posts -> dropdown next to edit -> clone
b) give a meaningful new view name respecting the namespace [see #2142593: Harmonise view names, view tags and view pane categories for some propositions]: "My Issue Tracker: Browsing Widget (Group)" [FYI: Package:"My" Module:"Issue Tracker" Function:"Browsing Widget" Scope:"Group" Base:"Content"; don't put base in view name as it is added automatically to the views overview title]; remember the machine_name ! -> continue
c) -> save
d) change the content type filter to "issue": -> Master [=default view] -> Filter criteria -> "Content:Type (=Post)" -> deselect "Post" -> select "issue" -> apply
e) delete the view's header: -> "partial node form" -> remove -> save (!) [saves the view & calls a cache clear]
f) you are almost done: skip the excursion and read #9!

******* EXCURSION ********
Do It Yourself: at (admin/structure/views/add)
a) set a View Name with a meaningful namespace (!)
b) remember the automatically created machine_name of your view! [edit it right away if you want to, you won't be able to edit it 'ever again']
b) add a short description
c) -> show "content" -> of type "Issue" -> sorted by "newest first"
d) deselect "Create Page" [you could use one indeed, but we don't want to blur this how-to]
e) -> continue & edit

8. Edit your new view as desired:
a) -> Master -> Format -> Show: select "content" -> and select the desired view_mode (you can set up custom view modes with view_modes if you need to); I choose "Teaser" and I don't want to display the links (e.g. follow)
b) now we need to set up the relationship between our "issues" and the current "group" viewed
aa) -> Advanced -> Relationships -> Add -> Filter -> OG membership -> select: "OG membership: OG membership from Node" [it is important to get the correct one!] -> Add and configure relationships

FYI: the structure behind the scenes looks like this: content [= the node (of type issue)] <-> OG membership <-> Group <-> OG membership <-> User; so in order to get the group the content is associated with, we have to get the proper OG membership including the right direction; as we are currently viewing our content type (issue) we can get the OG membership from a node. From there we can get the Group ID.

bb) select "require this relationship" -> apply [if for some reason an issue-node had no relation to a group (i.e. there is no OG membership) then we don't want that node in our view for a specific group]

-----EDIT-----
c) unfortuanetely (for this how-to) we have to add another relationship to get it working right now;
aa) Relationships -> Add -> Filter -> Flags -> select: "Flags: Node flag" -> Add and configure relationships; deselect "include only flagged content"; select "other content" -> apply [commons_bw expects acceess to information abbout following; that's why you could rename the identifier of this relation to "following"]
bb) and to get the related table loaded by views we need to add a filter for example; Filter criteria -> Add -> Filter -> Flags -> select: Flags: Flagged -> Add and configure
cc) select "expose" if you want the site user to be able to change that filter.
[At the moment I'm not quite sure, why this is really needed, but without this filter I get some bad errors, like table missing... maybe I'll check that some time later]
--END OF EDIT--

d) now it's time for the basic filtering via contextual filters
aa) -> contextual filters -> add -> filter -> OG membership -> select: OG membership: Group ID [this will filter the results for a Group ID passed to the view (by the commons_bw)] -> add and configure contextual filters

bb) Relationship -> "do not use..." -> OG membership from node [that's the relation we just added]

cc) What to do if the filter is not available: select "display all results..." [if the view is viewed without a contextual filter, i.e. on the starting page and without a Group ID getting passed to it, it will show the unfiltered view, i.e. all "issues" in all groups] -> apply

dd) one more thing: set a filter: Filter criteria -> Add -> Filter -> OG membership -> select: OG membership Group_type -> Add an configure filter criteria; Relationship -> change to: OG membership from node -> choose: is one of -> node [there are two different kinds of groups: node groups and user groups; we have to make sure that the relation we added earlier only connects to node-groups; we could have set this up in the contextual filter as well, but due to the fact that we allow the cf to be missing, we need this proper filter to be set.] -> apply.

ee) at this point you could add some more sophisticated stuff like (exposed) filters, (exposed) sort criteria, set pager settings, include a partial node form (as it is used by commons_bw and so on. Today we won't - it's getting late.

ff) important: click save! [actually you should have done that several times before, but I am not your mummy]

if you had some "issue-content already you could have a nice preview of your data and could test your contextual filter... but you don't. So we are going to change that.
***********************************

9. but first we go back to the .module-file once more:
a) remember the "vid"? that line should read now:

'vid' => 'my_issue_tracker_group_',  // or your view's machine_name if it differs

b) and, of course, we change the bundle used to:

 'bundle' => 'issue',

c) if you want to move the tab left/right (up/down) use the weight.

10. goto your homepage or a group's landing page: et voilà ! YOU GOT YOUR CUSTOM TAB WORKING!

Things to-do:
1. add some styling
2. add custom fields to your content-type
3. add custom filters, sorting and so on to your view
4. maybe add some custom view-modes and use them for display

Do some 'advanced' stuff: --> have a look here
1. insert a short node form for quick content creation
2. do some pre_rendering()
3. expose your content type to commons radioactivity
4. expose your content type to "liking" via commons like
5. panelize your content type landing page as a submodule
6. ...

updating title to better fit the guide's content

This is a duplicate of #1782922: Document pattern for creating Commons-compatible group content type features.

See the Commons Browsing Widget User Interface module which provides a simple user interface for configuring the browsing widget.