Need to document best practices for plugin development

[patrickmj]

Existing "Best Practices" is a mix of real best practices and "things you must do to make it work" I'd like to distinguish those, and put together a list of real best practices for 2.0.

Hopefully, very early in the process of upgrading plugins we can nail these down, and get things written up for us to follow.

Draft of the page is underway at Documentation/build/html/Tutorials/bestPracticesPlugins.html

On the list --- updated according to comments and discussion below

• Method Naming Conventions
• Maintaining Expected behavior -- e.g., if you override browseAction, keep the expected hooks in place
• User View Partials
• Put form-building logic in controller, not in extending Omeka_Form or Omeka_Form_Admin
• Use Omeka_Form or Omeka_Admin_Form or view helpers
• Use Omeka_Plugin_AbstractPlugin
• When and how to override Omeka_Record_AbstractRecord::recordUrl()
• Maintain admin look and feel (Omeka_Form_Admin helps here, but should include new CSS classes and whatnot when form is too complex for Omeka_Form_Admin to easily handle)
• Use HTML5
• Use nav(), and include a name for your nav so other plugins can filter it
• Make your content searchable
• Follow Omeka's guidelines for functions e.g., globals don't echo (need to document these)
• Internationalization (need to figure out/document adding new i18n files)
• Omeka Jobs -- default and long-running. When and why to choose

[patrickmj]

Should we say that using HTML5 structures is best practice?

[jimsafley]

• New search API
• New, renamed, and removed hooks and filters
• Pass array of arguments to hooks and filters
• New ACL plugin hook API
• New navigation filter API
• New, renamed, and removed global helper functions
• Global helper functions never echo
• Internationalization
• $this->_helper->db action helper
• $this->_helper->flashMessenger() action helper
• After/before hooks consolidated in Omeka_Record_AbstractRecord::after/beforeSave()
• New record form handling in Omeka_Controller_AbstractActionController::editAction()
• $acl->isAllowed() for ACL permission check
• Use Zend form view helpers, like $this->formText()
• Removed Omeka_Context in favor of Zend_Registry
• Omeka jobs, default and long running

[patrickmj]

Some of these are in the category of 'needed to just make it work', and so will go in an updating plugins and basic plugin development sections. Others are 'best practice' in the sense that a plugin will still work if done another way, but people should be aware of the better way to do something. For example, the new API, hooks, etc. stuff is 'make it work', while using Zend form view helpers is the better/preferred way to build forms. Some are kind of a mix, like how to do validations now that some hooks have been removed (this came up in IRC a while ago).

Internationalization is a big important one. Seems like we want to say using __() is a best practice, but we also need to make an easier path to updating translations without waiting for a new release. We're seeing this in forums and dev list already.