Early Bird Registration for DrupalCon Portland 2024 is open! Register by 23:59 PST on 31 March 2024, to get $100 off your ticket.
Problem/Motivation
This is a meta-issue to group all issues about porting all submodules and the new ones for D8, which is the first step before #1532612: Move Examples Project into Drupal core.
Proposed resolution
For every submodule:
- Familiarize yourself with what's needed from an Examples module: #2209627: [meta] Module Checklist for Examples
- Port the module's SimpleTest tests to D8. Some notes on how here: https://drupal.org/node/2166895 Also: #2102675: Port simpletest_example module to Drupal 8
- Verify that the tests fail without code-based errors.
- Port example code to D8
- Check coding standards like this:
$ cd modules/examples $ ../../vendor/bin/phpcs -ps .
- Make sure the documentation is clear and well-written
- Convert tests from SimpleTest to PHPUnit where possible.
- Add PHPUnit tests where possible.
Remaining tasks
I'm grouping the issues based on feedback from #1532612: Move Examples Project into Drupal core, all are needed, it's only to make it easier for people to find what to do first.
- QA-based examples:
- simpletest_example: #2102675: Port simpletest_example module to Drupal 8
- Main examples(list based on webchick analysis):
- block_example: #1630760: Update block example module for D8
- dbtng_example: #1868178: (better docs for) Port dbtng_example to D8
- entity_example: #1883722: Port entity_example to D8
- menu_example: #1883724: Port menu_example to D8 #2277667: Port D7 Tests To D8 for menu_example
- nodeapi_example: #1883726: Port nodeapi_example to D8
- page_example: #1882676: Port page_example to D8
- theming_example: #1883728: Port theming_example to D8
- New examples(@todo: complete this list):
- #2032697: Create PHPUnit example module
- #1668362: D8 Plugin Example
- #1615520: Add translatable config_simple_example
- #1630762: Configuration example for D7, so that the upgrade path to D8 may be demonstrated.
- #1883784: New examples for REST API in D8
- #1883760: New examples for views on D8
- #2147349: Create tour_example
- #2165259: Create node_type_example
- #2182621: Add Migrate example
- #2220565: Create a Content Entity Example
- #2084301: Add a Config Entity example
- Rest:
- action_example: #2102625: Port action_example module to Drupal 8
- ajax_example: #2102639: Port ajax_example module to Drupal 8
- batch_example: #2102643: Port batch_example module to Drupal 8
- cache_example: #2102645: Port cache_example module to Drupal 8
- contextual_links_example: #2102647: Add contextual_links_example module for Drupal 8
- cron_example: #1867662: Port cron_example to D8 #2197267: Remove variable_set()/variable_get() from cron_example
- email_example: #2102621: Port email_example module to Drupal 8
- field_example: #1796606: D8 Port: field_example
- field_permission_example: #2102699: Port field_permission_example module to Drupal 8
- file_example: #2102651: Port file_example module to Drupal 8
- filter_example: #2102657: Port filter_example module to Drupal 8
- form_example: #2102659: Add new Form API example module for Drupal 8
- image_example: #2102661: Port image_example module to Drupal 9.4+
- js_example: #2102665: Port js_example module to Drupal 8
- node_access_example: #2102667: Port node_access_example module to Drupal 8
- node_example: #2102669: Port node_example module to Drupal 8
- pager_example: #2102673: Port pager_example module to Drupal 8
- queue_example: #2102703: Port queue_example module to Drupal 8
- rdf_example: #2102705: Port rdf_example module to Drupal 8
- render_example: #1889842: Port render_example to D8
- tabledrag_example: #2102677: Port tabledrag_example module to Drupal 8
- tablesort_example: #2102679: Port tablesort_example module to Drupal 8
- token_example: #2102685: Port token_example module to Drupal 9
- trigger_example: #2102689: Port trigger_example module to Drupal 8
- vertical_tabs_example: #2102695: Port vertical_tabs_example module to Drupal 8
- xmlrpc_example: #2102635: Port xmlrpc_example module to Drupal 8
- ajax remaining examples:#2928719: [meta] Add remaining AJAX examples from conversion
Comments
Comment #1
Mile23This looks great. Thanks, marvil07.
Adding #1630762: Configuration example for D7, so that the upgrade path to D8 may be demonstrated., even though it's a D7 issue. It's trying to provide a testable upgrade path for configuration.
Comment #1.0
Mile23Added #1630762: Configuration example for D7, so that the upgrade path to D8 may be demonstrated.
Comment #2
marvil07 CreditAttribution: marvil07 commentedAdded #1882676: Port page_example to D8 to the issue summary.
Comment #2.0
marvil07 CreditAttribution: marvil07 commentedAdd page_example issue.
Comment #3
marvil07 CreditAttribution: marvil07 commentedI've added missing links to issues about main examples porting to D8.
Also minor issue renaming.
Comment #3.0
marvil07 CreditAttribution: marvil07 commentedAdd links to issues about main examples port
Comment #3.1
marvil07 CreditAttribution: marvil07 commentedadd views and rest apis issues for new examples
Comment #4
jhodgdonGreat progress!
I took a quick look at the DBTNG example that was committed. I'll just note here that this will need to be updated before it can be committed to Drupal Core -- it doesn't conform to our documentation standards very well. Things like:
- Verb tense on function descriptions.
- Files, functions, etc. need a one-line description (put additional information in a separate paragraph)
- Not all code sections in the doc blocks are in @code/@endcode tags. These will not format well on api.drupal.org.
- We don't normally have lines like this in core:
- Form constructor/validate/submit handlers have special docs syntax:
http://drupal.org/node/1354#forms
etc.
Comment #5
marvil07 CreditAttribution: marvil07 commentedI've just reopened the dbtng port issue ;-), thanks for the quick review!
Comment #5.0
marvil07 CreditAttribution: marvil07 commentedAdd render_example issue to the list
Comment #5.1
Mile23Added references to PHPUnit stuff
Comment #5.2
Kristen PolAdd email example
Comment #5.3
Kristen PolAdd action
Comment #5.4
Kristen Poladd xmlrpc
Comment #5.5
Kristen Polformatting
Comment #5.6
Kristen Poladd ajax
Comment #5.7
Kristen Polbatch
Comment #5.8
Kristen Poladd cache
Comment #5.9
Kristen Poladd contextual links
Comment #5.10
Kristen Poladd file
Comment #5.11
Kristen Poladd filter
Comment #5.12
Kristen Poladd form
Comment #5.13
Kristen Poladd image
Comment #5.14
Kristen Poladded js
Comment #5.15
Kristen Poladd node access
Comment #5.16
Kristen Poladd node
Comment #5.17
Kristen Poladd pager
Comment #5.18
Kristen Poladd simpletest
Comment #5.19
Kristen Poladd tabledrag
Comment #5.20
Kristen Poladd tablesort
Comment #5.21
Kristen Poladd token
Comment #5.22
Kristen Poladd trigger
Comment #5.23
Kristen Poladd vertical_tabs
Comment #5.24
Kristen PolAdd notes for "other modules"
Comment #5.25
Kristen Poladd field_permission
Comment #5.26
Kristen Poladd queue
Comment #5.27
Kristen Poladd rdf
Comment #6
Kristen PolI just added ~25 issues for the example modules that didn't have an issue yet. If you want to work on one, just assign it to yourself and code away :)
Comment #7
marvil07 CreditAttribution: marvil07 commented@Kristen Pol: Thanks for taking the time to create all the pending issues!
Comment #8
Mile23Yah, thanks, Kristen. :-)
Of course, there might be situations where there can't be a direct 1:1 port. But we'll deal as it happens.
Comment #9
kerasai CreditAttribution: kerasai commentedI'm going to attack at least one of these this weekend during the DrupalCamp Fox Valley sprint. Let me know if there is a preference as to which. I'm versatile. :)
Comment #10
jhodgdonkarasai: Take a look at the list in the summary. The ones listed as "main examples" would be a good starting point. After that, you can take your pick!
As a note... Although the Block example issue above is marked "closed/fixed", I don't think the Block example is actually going to work as it is. I took a quick look at the code, and it is still using hook_menu() instead of a routing.yml file.
So I think it would be great if a sprint would concentrate on making sure those "main examples" actually work correctly with the current Drupal 8 code.
Also, since I think the objective is to put those "main examples" into Drupal 8 core (hopefully), it would be good if a check could be made to see if they conform to our coding standards (using Coder) and documentation standards (comparing to https://drupal.org/node/1354). For instance, I noticed this at the top of the block example module file:
I am pretty sure that a line with @defgroup followed by a line with @ingroup is not going to work as expected. Presumably the intention was to make sure that the Block example, when displayed on api.drupal.org or a similar site, would show up inside the Examples topic. But this is not the right way to do it -- the @ingroup needs to be inside the @{ @}.
Comment #11
Mile23Examples has an umbrella group called 'examples,' and each module has its own group, such as 'block_example,' which is in the 'examples' group.
You can see how it works here: https://api.drupal.org/api/examples
Dunno if this will be a problem with the D8 fold-in, but the way its structured now is to @defgroup a group, and declare that group to be @ingroup examples. We can modify that going forward as needed, but it's nice to have separate groups for each module so the user can navigate through them on api.drupal.org, and also distinguish them from core itself.
Comment #12
jhodgdonRE #11... I understand that. I was just questioning the syntax used to accomplish that. I guess it works though.
I also think in Core we will not want to have that many new topics, because each one will show up on the Topics list.
Comment #13
Garrett Albright CreditAttribution: Garrett Albright commentedDo we still want modules which aren't page_example declaring menu items and page callbacks which basically spit out the same information as hook_help()? I'm particularly looking at filter_example. It's kind of odd for a module which just provides a filter to be also declaring a menu item for a page like this, and I'm sure that could apply to field_example and many others as well.
Comment #14
jhodgdonRE #13 - I personally think it is silly to provide page callbacks for example modules that do not need them, and if the same text is in hook_help(), then it has to be maintained in two places. I think the example modules would be better off as modules that you could use as a starting point -- you should be able to take them and change the name to have a viable module, without having to rip out a bunch of code. I vote for putting the help information in hook_help(), and making sure that all the module titles (in the info.yml files) start with "Example:" so that they will be grouped together on the Help landing page.
Comment #15
Mile23Not to be contradictory or anything, but: Yes, we want modules which aren't page_example to declare landing pages so the examples are readable after you install them.
In an ideal world, the help text would be refactored so you could manage it in one place for both hook_help() and a page callback.
An example module isn't for re-use as much as it is for illustrating a concept, though of course the code could be reused. Your production code is probably going to rip out the giant docblocks and replace both the page callback and hook_help() anyway, so err on the side of being didactic.
Examples modules are books that you read, but also happen to be executable.
Comment #16
jhodgdonBut you can definitely read the documentation by just installing the Help module and going to the module's help page. I don't get why you'd want it twice. It seems like Help is a good central location for getting information?
Comment #17
Mile23Well, suppose you enable an example module expecting it to show you something, and it doesn't seem to do anything. Did you enable it correctly? Did it break something? At least you have a menu item showing up with 'Examples' in it so you can click on that and see if something changed there.
Also, the page and the help info aren't always the same thing, as with form_example. So the help-and-page pattern is there, and if help_hook and the description page have the same content, it can just come from the same function.
Comment #18
marvil07 CreditAttribution: marvil07 commented#1880976-14: [meta] Port examples (including submodules) to D9.4+++
That's a good idea. We could just work-around using creating the routes from main example module, so examples can actually serve as ready-tto-copy-paste ones. I am not sure if on d8 routing file is possible, but hopefully(in d7 in hook_menu it was).
@Mile23: I guess if that is possible we can still provide a visual UI hint to the person trying the example module while also letting the example be copy/paste-able, what do you think?
Comment #19
jhodgdonI guess the question I have in #17 is "expecting it to show you something". Why should you expect an example module that demonstrates Blocks or Defining an Entity or Field to show you a page? I have always thought it was bizarre that the Examples project modules did this, and I'd be very happy to get rid of this behavior.
Here's a thought:
- Make the help module a dependency of all the Example modules, to make sure it gets enabled.
- Put prominently in the README and on the project page that Example modules have help and that you should read it to find out what they do and how to use them.
- Is it possible to put up a message when the module is enabled saying "Visit the Help page for this module for information on how to use it, and read the extensive comments in the code for information on how it was done"? or something like that? I'm pretty sure in 7 I've enabled modules that have had a message like "You'll need to do x, y, and z before this module will work".
Comment #20
marvil07 CreditAttribution: marvil07 commented@jhodgdon: thanks for your suggestions!
@jhodgdon, @Mile23: I have opened a new issue to figure it out/solve the last discussion topic: #2123195: [policy] Change approach on end user ui. Let's continue the conversation there please. This is a big meta ticket I would like to have focused if possible :-p
Comment #20.0
marvil07 CreditAttribution: marvil07 commentedremove extra phpunit
Comment #21
Mile23Comment #22
Mile23Comment #23
Mile23Comment #24
Mile23Comment #25
Mile23Comment #26
Mile23Comment #27
marvil07 CreditAttribution: marvil07 commentedAdding #2182621: Add Migrate example to the list.
Comment #28
Mile23Comment #29
Mile23Comment #30
Mile23Adding new entity examples.
Comment #31
Mile23Comment #32
Mile23Comment #33
Mile23Comment #34
frobComment #35
kentr CreditAttribution: kentr as a volunteer commentedAdded #2643048: Example search plugin
Comment #36
Mile23Comment #37
Mile23Comment #38
Lal_We still have some more examples to be ported.
Comment #39
valthebaldMarking this as closed, since we already have 9.x-compatible release :)
Comment #41
TR CreditAttribution: TR commentedWhy was this closed? It's not close to being finished - there are at least 10 unported submodules linked above, and now there's no way to track what still needs to be done to complete the port from D7?
Comment #42
valthebald@TR: You're right. Reopening to complete porting of submodules.
Comment #43
valthebaldComment #44
jungleD8 is EOL, the 4.0.x branch is the active dev branch for Drupal ^9.4 || ^10