Presentation almost there…

2024-11-16 08:21:22 -05:00 · 2024-11-16 08:21:22 -05:00 · 846b68aed9
commit 846b68aed9
parent df412c0c1b
1 changed files with 265 additions and 4 deletions
--- a/2024-nedcamp-when-not-a-module-make-and-maintain.md
+++ b/2024-nedcamp-when-not-a-module-make-and-maintain.md
@ -1,11 +1,17 @@
+---
+mermaid:
+  themeVariables:
+    lineColor: '#fff'
+---
+
+#### When There's Not a Module for That— How to Make (and Maintain) a New Module
+
 New England Drupal Camp @ Rhode Island College  
 Providence, RI  
 November 16, 2024  
 #NEDCamp2024  
 9am, Gaige Hall 201

-#### When There's Not a Module for That: How to Make (and Maintain) a New Module
-
 benjamin "mlncn" melançon  
 ben@agaric.coop

@ -22,12 +28,257 @@ Note: my name's ben, i have been a worker and owner at the worker-owned Agaric c
 ---

 ## When There's *Not*
-## a Module for That:
+## a Module for That
 ### How to Make (and Maintain)
 ### a New Drupal Module

 ---

+###### Presented by
+
+**Benjamin Melançon**  
+**[mlncn](https://agaric.coop/mlncn)**
+
+&nbsp;  
+with behind-the-scenes help from
+
+Mauricio Dinarte  
+**[dinarcon](https://agaric.coop/dinarcon)**
+
+
+
+---
+
+
+TOGETHER, we are **⅓** of
+
+<img alt="Agaric" src="content/images/agaric-logo-stacked.png" class="plain" />
+
+a web technology collective
+
+**ask@agaric.coop**
+
+---
+
+Send complaints to ben@agaric.coop
+
+and heckling posts to social.coop/@mlncn
+
+---
+
+![Frankenstein and monster, part of a still from 1931 guillermo del toro adaptation](images/frankenstein-and-monster-part-of-still-from-1931-guillermo-del-toro-adaptation.png)
+
+Note: So what do you do when there's not a module for that?  You make your own.  It's easy.
+
+---
+
+![Regular node add form with Save button](content/images/create-frankenstein-unmodified.png)
+
+
+Note: Say you're creating a site where people can relive great literature that may have been inspired by a famine.  You've already created an excellent content type under Structure » Content.  But somehow the usual "Save" doesn't communicate what you want when creating Frankenstein content.
+
+---
+
+
+`frankenstein.info.yml`
+
+```yaml
+name: Frankenstein
+description: "Rename save button for Frankenstein's content."
+type: module
+core_version_requirement: ^8 || ^9 || ^10 || ^11 || ^12
+```
+
+Note: This file tells Drupal about your module, and it is technically all you need to enable your module.
+
+---
+
+
+`frankenstein.module`
+
+```php
+<?php
+/**
+ * Implements hook_form_FORM_NAME_alter() for "Frankenstein" node (add) form.
+ */
+function frankenstein_form_node_frankenstein_form_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state) {
+  $form['actions']['submit']['#value'] = t('Re-animate!');
+}
+```
+
+Note: There we go, there's a module!  I think we're done here.  Anyone have any ideas for the next 40 minutes?  `.info.yml` files are not PHP.  They cleverly indicate this by not starting with `<?php`.  `.module` files are PHP...
+
+---
+
+### Where to put these files
+
+![Folder hierarchy of custom module in Drupal](content/images/frankenstein-location-in-ranger.png)
+
+Note: Our files are in place in our local site, now we go to our create 'Frankenstein' content form and…
+
+
+---
+
+
+![Regular node add form with Save button](content/images/create-frankenstein-unmodified.png)
+
+
+---
+
+
+# Enable your module
+
+At **Extend** (`/admin/modules`) or with:
+
+`drush -y en frankenstein`
+
+
+Note: That slide may be the most important you're going to be shown. Enable your module.
+
+---
+
+
+![Regular node add form with Save button as reanimate](content/images/create-frankenstein-reanimate.png)
+
+Note: Tadaaa!  Now you know how to make a module!
+
+---
+
+![Adam Scott staring at the camera](content/images/adam-scott-conan-stare.gif)
+
+Note: So you're all sitting* there thinking ... sure, that's easy if you know the exact words and symbols to *put* in that file.  And you're absolutely right.  And we're going to tell you how you can figure out all of that.
+
+---
+
+![A motor made of legos labeled Online Commerce Engine, a guitar made of legos labeled Music Media Gallery, and a pile of lego pieces labeled Module You Need](content/images/lego-modules-and-not-a-module.png)
+
+
+Note: It has often been said, Drupal is a box of legos that you can build just about anything you want with.  But sometimes those legos have been put together for you.  And sometimes not.
+
+---
+
+A few basic approaches give a lot of power.
+
+<img alt="Screwdriver with extensive collection of driver tips." src="content/images/screwdriver-tip-set.jpg" width="70%" />
+
+Note: A few specific examples will give you a lot of tools.   But first, two secrets.  One's good news, second is bad news.
+
+---
+
+#### Good News
+
+### Now you know where to paste
+
+![How do I exit the Vim editor? viewed 2.1 million times](content/images/stack-overflow-helping-devs-quit-vim.png)
+
+Note: And knowing where to paste unleashes the power of Stack Overflow / Stack Exchange sites.  (yes, the same family of sites that has helped a couple million developers figure out how to quit vim.)  Knowing where to put this code unleashes the power of Stack Overflow.  You now know enough to be dangerous.  And i hope i have definitively slayed (slewn?) the mythology that module-making is a mystic domain of Drupal druids.
+
+---
+
+#### Bad News
+### That simple form alter has hidden gotchas
+
+&nbsp;
+
+* As written, it only applies to the create (node/add) form— not the edit form.
+* There's a dozen variations of the humble form alter hook, and all are valid.
+
+Note: With our dirty secrets acknowledged, on with the show.  We'll show the edit form hook later on!
+
+---
+
+## The Show
+ 
+- Prelude: **How To Make a Module**
+- Act One: **How Not To Make a Module**
+- Act Two: **How Not To Have to Make a Whole Module**
+- Act Three: **How To Figure Out How To Make a Module**
+- Encore: **How To Contribute Your Module**
+
+---
+
+Act One
+
+### How Not To Make a Module
+
+![Muppet Show curtain](images/muppet-show-curtain.png)
+
+---
+
+### Hierarchy of Code Usage
+
+Stop at the first layer configurable to your needs.
+
+1. Drupal core code
+2. Broadly supported contributed module code
+3. Less-supported or patched contributed module code
+4. Code you have written and contributed
+5. Custom code you have written and hidden from the world
+
+Note: Why not to make a module.
+
+---
+
+#### When not to make a module?
+
+[![Turtle with golf ball on spring contraption on back.](images/rube-goldberg-tortoise.jpg)](https://www.koreus.com/video/machine-rube-goldberg-lente.html)
+
+Note: You can do anything with a module!  Why wouldn't you make one every day?
+
+---
+
+
+#### …when there's an easier way
+
+![Ginger Howard completing her swing after hitting a golf ball](images/ginger-howard-golf-swing.jpg)
+
+Note: find a contrib module that does it.  Should it be in a template?  If it's very specific to the display on your site, you should probably do it in the theme layer.  But if it's at all data and you might ever want to switch themes, or want to allow site builders or site managers to disable or change settings, get that in a module.
+
+---
+
+Alternatives to a module:
+
+- Template override
+- String override
+- ECA (Event Condition Action, or now Rules is also stable, but i like ECA)
+
+Note: There are a couple of modules for string overrides, or they can go in settings.php.  ECA is not necessarily faster than making a module, especially once you know how to make a module, but it exposes the logic to non-developers better.
+
+---
+
+> When building a Drupal site, “there’s a module for that” can be the sweetest words you can hear.
+
+Note: So let's start there.
+
+---
+
+### Is there already a module for that?
+
+
+[drupal.org/project/project_module](https://www.drupal.org/project/project_module)
+
+![Modules link](content/images/download-extend-modules-menu.png)
+
+---
+
+![Modules search](images/modules-search.png)
+
+Note: I definitely recommend changing core compatibility to something reasonable, Drupal 10, to start.  And Status to "All projects", not just Full, non-sandbox projects, if you're ready to write a module.  A sandbox may be a great start.  And then allow any version.  Then put in your key words and search.  Remove the version— perhaps your best bet is porting an existing module.  Use lots of different keywords.
+
+---
+
+* Do the same searches on an Internet-wide search with “Drupal” and “module” included as keywords.
+* Ask in IRC: #drupal-support, #drupal, and #drupal-contribute (in that order and over some time, even a few days)
+* Er, i meant the Slack equivalents #support, #general, #contribute, see https://www.drupal.org/slack
+
+---
+
+Take note of everything you use to search for a module.
+
+Note: This is how people in the same situation will find your module.  Currently we are pouring our notes into Logseq, and they'll be public soon.
+
+---
+
 ### Be a part of something bigger
 (but not as big as all of Drupal)

@ -59,7 +310,7 @@ in `src/Plugin` of whatever modules you are operating in the vicinity of.
 BEF Links Filter is a `better_exposed_filters` plugin in about 250 lines of code altogether.


-Doing your own or copying 
+Note: Doing your own by extending an existing plugin or copying and modifying an existing plugin is probably the highest impact to effort ratio.

 ---

@ -90,6 +341,16 @@ Note: Grep.  Even when i am fully using an IDE for everything else, i grep in th

 ---

+### Building a Contrib-Worthy Modern Drupal (10, 11, 12…) Module
+
+---
+
+File issues for your own modules.
+
+Note: It helps you think through what you are planning to do, it makes features and bugs more discoverable by other people, if you do not get to it right away there is a chance someone else will, and you (and anyone else who helps) get Drupal.org issue credit for that (you get no credit for contributing the actual module).
+
+---
+
 To be continued…

 Note: Let me know what you build!