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:

  1. Familiarize yourself with what's needed from an Examples module: #2209627: [meta] Module Checklist for Examples
  2. 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
  3. Verify that the tests fail without code-based errors.
  4. Port example code to D8
  5. Review with coder
  6. Make sure the documentation is clear, well-written, and follows our documentation standards on http://drupal.org/node/1354
  7. Convert tests from SimpleTest to PHPUnit where possible.
  8. 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.

User interface changes

None.

API changes

None.

Comments

This 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.

Added #1882676: Port page_example to D8 to the issue summary.

Issue summary:View changes

Add page_example issue.

Title:[meta] Port to D8[meta] Port examples to D8

I've added missing links to issues about main examples porting to D8.

Also minor issue renaming.

Issue summary:View changes

Add links to issues about main examples port

Issue summary:View changes

add views and rest apis issues for new examples

Great 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:

+//// Helper functions ////

- Form constructor/validate/submit handlers have special docs syntax:
http://drupal.org/node/1354#forms

etc.

I've just reopened the dbtng port issue ;-), thanks for the quick review!

Issue summary:View changes

Add render_example issue to the list

Issue summary:View changes

Added references to PHPUnit stuff

Issue summary:View changes

Add email example

Issue summary:View changes

Add action

Issue summary:View changes

add xmlrpc

Issue summary:View changes

formatting

Issue summary:View changes

add ajax

Issue summary:View changes

batch

Issue summary:View changes

add cache

Issue summary:View changes

add contextual links

Issue summary:View changes

add file

Issue summary:View changes

add filter

Issue summary:View changes

add form

Issue summary:View changes

add image

Issue summary:View changes

added js

Issue summary:View changes

add node access

Issue summary:View changes

add node

Issue summary:View changes

add pager

Issue summary:View changes

add simpletest

Issue summary:View changes

add tabledrag

Issue summary:View changes

add tablesort

Issue summary:View changes

add token

Issue summary:View changes

add trigger

Issue summary:View changes

add vertical_tabs

Issue summary:View changes

Add notes for "other modules"

Issue summary:View changes

add field_permission

Issue summary:View changes

add queue

Issue summary:View changes

add rdf

I 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 :)

@Kristen Pol: Thanks for taking the time to create all the pending issues!

Yah, 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.

I'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. :)

karasai: 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:

/**
* @defgroup block_example Example: Block
* @ingroup examples
* @{
* Demonstrates code creation of blocks.

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 @{ @}.

Examples 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.

RE #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.

Do 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.

RE #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.

Not 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.

But 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?

Well, 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.

#1880976-14: [meta] Port examples to D8++
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?

I 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".

@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

Issue summary:View changes

remove extra phpunit

Issue summary:View changes

Issue summary:View changes

Issue summary:View changes

Issue summary:View changes

Issue summary:View changes

Issue summary:View changes

Issue summary:View changes

Adding #2182621: Migrate example to the list.

Priority:Normal» Major

Issue summary:View changes

Issue summary:View changes

Adding new entity examples.

Issue summary:View changes