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

Mile23’s picture

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.

Mile23’s picture

marvil07’s picture

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

marvil07’s picture

Issue summary:View changes

Add page_example issue.

marvil07’s picture

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.

marvil07’s picture

Issue summary:View changes

Add links to issues about main examples port

marvil07’s picture

Issue summary:View changes

add views and rest apis issues for new examples

jhodgdon’s picture

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.

marvil07’s picture

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

marvil07’s picture

Issue summary:View changes

Add render_example issue to the list

Mile23’s picture

Issue summary:View changes

Added references to PHPUnit stuff

Kristen Pol’s picture

Issue summary:View changes

Add email example

Kristen Pol’s picture

Issue summary:View changes

Add action

Kristen Pol’s picture

Issue summary:View changes

add xmlrpc

Kristen Pol’s picture

Issue summary:View changes

formatting

Kristen Pol’s picture

Issue summary:View changes

add ajax

Kristen Pol’s picture

Issue summary:View changes

batch

Kristen Pol’s picture

Issue summary:View changes

add cache

Kristen Pol’s picture

Issue summary:View changes

add contextual links

Kristen Pol’s picture

Issue summary:View changes

add file

Kristen Pol’s picture

Issue summary:View changes

add filter

Kristen Pol’s picture

Issue summary:View changes

add form

Kristen Pol’s picture

Issue summary:View changes

add image

Kristen Pol’s picture

Issue summary:View changes

added js

Kristen Pol’s picture

Issue summary:View changes

add node access

Kristen Pol’s picture

Issue summary:View changes

add node

Kristen Pol’s picture

Issue summary:View changes

add pager

Kristen Pol’s picture

Issue summary:View changes

add simpletest

Kristen Pol’s picture

Issue summary:View changes

add tabledrag

Kristen Pol’s picture

Issue summary:View changes

add tablesort

Kristen Pol’s picture

Issue summary:View changes

add token

Kristen Pol’s picture

Issue summary:View changes

add trigger

Kristen Pol’s picture

Issue summary:View changes

add vertical_tabs

Kristen Pol’s picture

Issue summary:View changes

Add notes for "other modules"

Kristen Pol’s picture

Issue summary:View changes

add field_permission

Kristen Pol’s picture

Issue summary:View changes

add queue

Kristen Pol’s picture

Issue summary:View changes

add rdf

Kristen Pol’s picture

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

marvil07’s picture

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

Mile23’s picture

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.

kerasai’s picture

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

jhodgdon’s picture

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

Mile23’s picture

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.

jhodgdon’s picture

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.

Garrett Albright’s picture

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.

jhodgdon’s picture

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.

Mile23’s picture

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.

jhodgdon’s picture

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?

Mile23’s picture

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.

marvil07’s picture

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

jhodgdon’s picture

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

marvil07’s picture

@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

marvil07’s picture

Issue summary:View changes

remove extra phpunit

Mile23’s picture

Issue summary:View changes
Mile23’s picture

Issue summary:View changes
Mile23’s picture

Issue summary:View changes
Mile23’s picture

Issue summary:View changes
Mile23’s picture

Issue summary:View changes
Mile23’s picture

Issue summary:View changes
marvil07’s picture

Issue summary:View changes

Adding #2182621: Migrate example to the list.

Mile23’s picture

Priority:Normal» Major
Mile23’s picture

Issue summary:View changes
Mile23’s picture

Issue summary:View changes

Adding new entity examples.

Mile23’s picture

Mile23’s picture

Issue summary:View changes
Mile23’s picture

Issue summary:View changes
frob’s picture