This change notice https://drupal.org/node/1800686 talks about the routing changes, but not all the other things that used to be in hook_menu() including local tasks, local actions, contextual links, menu links and theme negotiation per path.

Either update that change notice to be more comprehensive, or (better) put more compete documentation in the handbook such as under https://drupal.org/update/modules/7/8 and link to it from the change notice.

Comments

xjm’s picture

Priority: Normal » Critical
Issue summary: View changes
Issue tags: -beta target +beta blocker, +Missing change record

Yep.

pwolanin’s picture

Issue summary: View changes

see also: https://drupal.org/node/2228089 as a starting point for menu links documentation (though the changes for those are still in progress)

xjm’s picture

xjm’s picture

Local tasks are covered in https://drupal.org/node/2044515 which I think is out of date? -- we should probably consolidate an updated version of that into the main one.

jhodgdon’s picture

We need to cover this stuff *both* in the change notice (briefly) and under drupal.org/developing/api (more comprehensively).

drupalshrek’s picture

Issue summary: View changes
dawehner’s picture

So we end up with 3 places to document everything? a.do.org, handbooks, changenotices and kind of issue summaries?

jhodgdon’s picture

Change notices are specifically to notify people who maintain modules/themes about changes to the API they are using. So they need to be done when APIs change, and should have D7 and D8 examples of how to make a module to do the same thing in both.

https://drupal.org/developing/api is about how to develop code with the current API, and should contain tutorials about the major APIs of Drupal. It shouldn't compare between versions, just present how to do something in D8.

Topics on api.drupal.org are shorter explanations that hit only the major points, and since this documentation is in the Drupal Core code base, it has the advantage of being available if you are not connected to the Internet. Also shouldn't compare to previous versions, and doesn't require step-by-step. Should link to developing/api pages as appropriate.

All of them are important, and each serves a different purpose.

jhodgdon’s picture

Title: Document in WSCCI change notice or handbook all the menu changes (tasks, actions, contextual links, menu links) from 7 to 8 » Document in WSCCI change notice (possibly with link to handbook) all the menu changes (tasks, actions, contextual links, menu links) from 7 to 8

I will just add that the only part of this that is *critical* is the change notice. Clarifying title

Also, the api.drupal.org topic and the Handbook are separate issues: see #2046367: Document the internals of the router -- this issue is only about making sure we have a change notice where people can find out what they need to do to update hook_menu(), in all of its variations, from D7 to Drupal 8.

xjm’s picture

Title: Document in WSCCI change notice (possibly with link to handbook) all the menu changes (tasks, actions, contextual links, menu links) from 7 to 8 » Document all the menu changes (tasks, actions, contextual links, menu links) from 7 to 8 in the WSCCI change record
michaelfavia’s picture

Assigned: Unassigned » michaelfavia
xjm’s picture

Thanks @michaelfavia (and @qwertyisms) -- are you folks still working on this issue? And could you post what notes you have regarding it? Thanks!

Gábor Hojtsy’s picture

Started documenting the current state of menu at https://www.drupal.org/node/2122241/revisions/view/7117961/7366563, there are way too many facets of this issue, and this is just a minor start, just wanted to note.

Gábor Hojtsy’s picture

Also updated the local tasks docs page for the examples to be up to date, added image illustrations and fixed links: https://www.drupal.org/node/2122253/revisions/view/7349495/7366687

Gábor Hojtsy’s picture

Updated local actions docs, added image illustration and section on dynamic local actions with derivatives: https://www.drupal.org/node/2133247/revisions/view/7016473/7366853

Gábor Hojtsy’s picture

Finally, updated the contextual links page to be a much more complete and full example of block contextual links instead of jumping around from blocks to nodes, added illustration and dynamic contextual links docs: https://www.drupal.org/node/2133283/revisions/view/7339895/7366943

I will stop this for now, since I think these pages now provide a solid base to point to as they document the state of the art NOW. These updated pages DO NOT resolve this issue since the issue was opened to have *upgrade* docs. But now there is a set of reference docs on the current state to point to and aid writing the upgrade docs. This is still assigned to @michaelfavia, so will let @michaelfavia and others work on the upgrade docs. Let me know if you need help/input. As can be seen from the various example links I've added, views and config translation are the two very flexible modules that stretch the APIs most and I have very deep experience with config translation at least.

jhodgdon’s picture

Great work!!!!

Gábor Hojtsy’s picture

All right, since nobody beat me to it, now wrote this detailed guide with plenty of outside references to routes, access checking, tabs, etc. at https://www.drupal.org/node/2118147/revisions/view/2891943/7373091 Also created a nice image illustration with D7/D8 comparison :) Hope you like it.

Let's figure out what else do we need here :)

Gábor Hojtsy’s picture

Also added a summary section on the admin tabs (2 levels of tabs and how/why they work), illustrated the tab on nodes, and added two examples for actions and contextual links (which are not in book module) based on menu module :) https://www.drupal.org/node/2118147/revisions/view/7373091/7373355 So all types now have a direct porting example on this page.

Gábor Hojtsy’s picture

jhodgdon’s picture

I'm hoping that when you're done with all of this, you'll set the issue status to "needs review" so we can review the final documentation? :)

xjm’s picture

@Gábor Hojtsy and I discussed these docs this morning. I think the last step is to just remove all the stale code examples and text from the routing change record, reduce it to essentials, and link the new tutorial and topics from it.

Gábor Hojtsy’s picture

In preparation to be able to remove most of the content of the change notice, I updated the menu conversion tutorial as follows:

- added a very high level view of the controller class (still linking out to the routing and the WSCCI conversion guides for more detail)
- explained the _content vs. _controller business on the examples routes used (we already had a case of both)
- added a sample port of dynamic items based on node/add/* (although that was not ported to D8 in practice either); I think this is very educational because you only need one route but still need several menu items

https://www.drupal.org/node/2118147/revisions/view/7374201/7376503

I'm getting there were practically all the content on https://www.drupal.org/node/1800686 is represented in the tutorial and much better. Will do one more pass of review, update the change notice by gutting it out mostly and then move this to needs review.

Gábor Hojtsy’s picture

Status: Active » Needs review

All righto, retitled the change notice from Routing functionality of hook_menu() has been replaced by new routing system (and others) to All functionality of hook_menu() is replaced by new systems for routing, menu links, local tasks, actions and contextual links so it has all the juicy keywords one would search for. Gutted the examples, added the overall illustration image and linked out to examples page.

I think this is now done.

Gábor Hojtsy’s picture

Also updated dynamic routes doc since it now only mentioned the route_callbacks solution while if dynamic routes need to be defined based on other dynamic routes, then the alterRoutes() method needs to be used: https://www.drupal.org/node/2122201/revisions/view/7218443/7376855 and https://www.drupal.org/node/2187643/revisions/view/7337813/7376935 (also fixed route altering example on the later page, which was pretty outdated).

Gábor Hojtsy’s picture

BTW @webchick was puzzled by the number of different files and opened #2291137: Rename various *links.yml files to improve DX for unifying the static definitions. I summarised the dynamic definition solutions available now and opened #2291773: Creating dynamic hook_menu() successor items use different APIs to improve how dynamic definitions are provided for each.

jhodgdon’s picture

Related issue:
#2290129: Menu/routing topic needs an overhaul
is about the overview/landing page for menu/router stuff on api.drupal.org. I made heavy use of the nice new documentation from this issue (good job by the way!! I think this documentation is really in pretty good shape!).

A review on that other issue would be appreciated!

catch’s picture

Issue tags: -beta blocker

This looks fantastic. I'm going to remove the beta blocker tag since there is more than enough there to stop this issue blocking that, leaving critical/CNR for extra reviews though for now.

Gábor Hojtsy’s picture

What else is to be done here? I think we updated all the things now?

Gábor Hojtsy’s picture

Status: Needs review » Fixed

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.