Via the forums: https://forum.omeka.org/t/missing-tutorial-pages-on-omeka-docs/5588

Missing pages for

the Understanding Omeka_Record_AbstractRecord and the Understanding Omeka_Controller_AbstractActionController tutorial pages are completely blank

The docs should be informative and easy to read.

Alphabetical is totally inappropriate there. There's no logical grouping at all currently (except topics within a document).

Both for updating plugins and for guidance on building new plugins, we should provide guidance about how to build admin views pages

• What CSS classes are in play, and how to use them (e.g. for navigation tabs, flash messages, alerts, etc.)
  ** Document what classes/ids went away and what was added, just as for functions/methods in code
  ** Document what we help with for good mobile design
• Hooks/filters into new admin interface elements (?)
• Any javascripty goodness that's available across all admin pages?
• Design/layout principles we would like to push for consistency across plugins?
  ** Principles for plugin config screens vs admin tabs?

Need to get in line with: omeka/Omeka#367

it's clearly doing some weird stuff to the Exceptions

[1:08]
doesn't seem to be a problem, a PHP 7 artifact it looks like

[1:08]
there's a couple index.rsts that always get overwritten that you should probably revert

[1:08]
the label "Controllers" to "controllers"

[1:09]
"Class Library by Path" to "libraries/Omeka"

[1:11]
/Reference/libraries/Omeka/Application/Resource/Autoloader.rst looks like it should have been deleted but wasn't

[1:13]
this change looks wrong, probably revert it as well https://github.com/omeka/Documentation/compare/stable-2.5#diff-fd9b19693fd1b2919b40c0fda3b48a7fR14

[1:13]
"View Helpers" to views/helpers another one of those index heading changes that should just be reverted

[1:14]
otherwise looks fine

[1:14]
a little hard to tell for sure

It's in both Reference/libraries/Omeka and Reference/libraries/Omeka/View.

Lots of documentation, both prosish and in-code mentions an $options array to be passed, but explicit statements of possible options are not necessarily there.

Many of these situations are probably duplicated, where the same set of possible options are passed to many different functions (like ones for form or element building, or adding metadata to a record).

Those cases should be broken out into individual .rst files and included where useful with the .. include:: directive.

We specify a setting html_style in conf.py to force the "real" default theme.

The customized default theme they use just generally looks nicer (I think, anyway), and includes a search box for their full-text search. The "real" default we're using uses the crummier built-in search.

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

The documentation generator only sometimes creates an index.rst file. when missing, create one

We've had stub pages for examples of global functions forever, but few are filled in. Any examples creating behavior beyond the defaults in core themes will be very helpful. They're in https://github.com/omeka/Documentation/tree/master/source/Reference/libraries/globals/examples

Please submit pull requests, and comment on this issue to ask any questions.

Is it possible to append form content to the Navigation form? At first I thought it possible, using the navigation_form hook, but it doesn't appear any of the useful methods in Omeka_Form_Navigation are available. It also seems that it might not get rendered correctly, but I'm guessing I'm just doing it wrong.

Need to specify how loop() parameter is pluralized.

For example, if the controller default model name is 'CsvImport_Import', then the loop parameter is not 'csvimport_imports'. Instead it is 'csv_import_imports'.

Here is the correct usage:
loop('csv_import_imports')

There are lots of options in conf.py to set some CSS styles. work with those to make it close to the existing style on omeka.org

It would be great if there is an introduction section where you talk about directory structure, coding style, frameworks and libraries used and other "general" topics. E.g it would be great to know from the beginning which standards from the PHP FIG you are following. This makes it a lot easier to get into the code.

We need to explicitly state that flashSuccess and flashError have been replaced by _helper->flashMessenger

http://omeka.org/codex/Updating_Plugins_For_2.0#Hooks_and_Filters

There is no license attached to this repo.

Hi there,

We need to get tour info but do not see what API to call from the document. Does the API actually exist or not?

Thanks,

Hello:
I have seen that in '\admin\themes\default\collections\edit.php' there is a code line where a

The documentation sidebar needs a direct link to opening a documentation issue on github. Alternatively, we may want to create our own anonymous documentation issue form, which uses the Github API to post a new issue. The advantage of this approach is that we could include a link to the offending page in the posted issue, and we would not require the average documentation user to navigate and login to github. http://developer.github.com/v3/issues/#create-an-issue

Part of broader double-checking of all the filters #8

I read the documentation, and then started writing a plugin by looking at the source code from an existing plugin, and inspecting the source code of Omeka, because reading the documentation left me exactly at the same point where I was before reading it.

I needed to create a table representing a Many-to-Many relationship between two models. That means that the primary key is made of two fields, one referencing the id of a table represeting one model, and the other referencing the id of the table representing another model. In a standard mapping of an Entity-Relation model to a database structure, the table representing the many-to-many relation shouldn't have a useless, redundant, auto-increment 'id' field, it just has the primary key built with the ids referencing the two model tables.

There's NOTHING about this in the documentation, so I tried.

This is the statement creating the table in the installation hook:

CREATE TABLE IF NOT EXISTS `{$this->_db->AdditionalParentCollection}` (
          `parent_collection_id` int(10) unsigned NOT NULL,
          `collection_id` int(10) unsigned NOT NULL,
          PRIMARY KEY (`parent_collection_id`, `collection_id`)
        ) ENGINE=InnoDB  DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;";
        $this->_db->query($sql);

This is a many-to-many relationship between Collection and Collection. What it means and what it's for are not relevant here.

I created a model AdditionalParentCollection and a table Table_AdditionalParentCollection.

I find NOTHING in the documenation about how I'm supposed to tell Omeka that this table represents a relation and not a model, and/or that the primary key is not id, let alone that it's made of two fields. So I thought I'd try by just never using find() (only findBy()) and never mentioning the id and see what would happen.

In my hookAfterSaveCollection I have this:

				$additionalParent = new AdditionalParentCollection;
				$additionalParent->collection_id = $collection->id;
				$additionalParent->parent_collection_id = $additionalParentId;
				$additionalParent->save();

This looks like it shouldn't cause any problem by itself. I'm creating a new instance of the model, populating the only two fields that it has, and trying to save it.

This causes this error:

exception 'Zend_Db_Statement_Mysqli_Exception' with message 'Mysqli prepare error: Unknown column 'id' in 'field list'' in /srv/www/****/application/libraries/Zend/Db/Statement/Mysqli.php:77
Stack trace:
#0 /srv/www/****/application/libraries/Zend/Db/Statement.php(115): Zend_Db_Statement_Mysqli->_prepare('INSERT INTO `ad...')
#1 /srv/www/****/application/libraries/Zend/Db/Adapter/Mysqli.php(388): Zend_Db_Statement->__construct(Object(Zend_Db_Adapter_Mysqli), 'INSERT INTO `ad...')
#2 /srv/www/****/application/libraries/Zend/Db/Adapter/Abstract.php(479): Zend_Db_Adapter_Mysqli->prepare('INSERT INTO `ad...')
#3 [internal function]: Zend_Db_Adapter_Abstract->query('INSERT INTO `ad...', Array)
#4 /srv/www/****/application/libraries/Omeka/Db.php(79): call_user_func_array(Array, Array)
#5 /srv/www/****/application/libraries/Omeka/Db.php(255): Omeka_Db->__call('query', Array)
#6 /srv/www/****/application/libraries/Omeka/Db.php(255): Omeka_Db->query('INSERT INTO `ad...', Array)
#7 /srv/www/****/application/libraries/Omeka/Record/AbstractRecord.php(541): Omeka_Db->insert('AdditionalParen...', Array)
#8 /srv/www/****/plugins/AdditionalParents/AdditionalParentsPlugin.php(172): Omeka_Record_AbstractRecord->save()
#9 [internal function]: AdditionalParentsPlugin->hookAfterSaveCollection(Array)
#10 /srv/www/****/application/libraries/Omeka/Plugin/Broker.php(154): call_user_func(Array, Array)
#11 /srv/www/****/application/libraries/Omeka/Record/AbstractRecord.php(301): Omeka_Plugin_Broker->callHook('after_save_coll...', Array)
#12 /srv/www/****/application/libraries/Omeka/Record/AbstractRecord.php(548): Omeka_Record_AbstractRecord->runCallbacks('afterSave', Array)
#13 /srv/www/****/application/libraries/Omeka/Controller/AbstractActionController.php(229): Omeka_Record_AbstractRecord->save(false)
#14 /srv/www/****/application/controllers/CollectionsController.php(52): Omeka_Controller_AbstractActionController->editAction()
#15 /srv/www/****/application/libraries/Zend/Controller/Action.php(516): CollectionsController->editAction()
#16 /srv/www/****/application/libraries/Zend/Controller/Dispatcher/Standard.php(308): Zend_Controller_Action->dispatch('editAction')
#17 /srv/www/****/application/libraries/Zend/Controller/Front.php(954): Zend_Controller_Dispatcher_Standard->dispatch(Object(Zend_Controller_Request_Http), Object(Zend_Controller_Response_Http))
#18 /srv/www/****/application/libraries/Zend/Application/Bootstrap/Bootstrap.php(105): Zend_Controller_Front->dispatch()
#19 /srv/www/****/application/libraries/Zend/Application.php(384): Zend_Application_Bootstrap_Bootstrap->run()
#20 /srv/www/****/application/libraries/Omeka/Application.php(73): Zend_Application->run()
#21 /srv/www/****/admin/index.php(28): Omeka_Application->run()
#22 {main}

which, as per another annoying bug I reported a few minutes ago, doesn't even show me the full query that causes the error.

I wouldn't necessarily expect this to work as is. I would expect to be able to find, in the documentation, an explanation of how I am supposed to do this.
And I believe I know how to look. I don't think I'm not finding it in the documentation because I don't know where to look or because it's obvious enough. I'm not finding it because it's not there.
Nor is there a link to a place where to look (e.g., if Omeka is built on top of some other well-known framework, a link to its documentation or a mention of its name)

Oh well, this really helps me understanding it.

This page incorrectly documents the hook.

For it to work, you have to implement a hook called admin_settings_form (without the 'general'). It then gets correctly called.

Also, the documentation is lacking about the right way to modify the form, but it's another problem.

Here's another concrete example of the utter insufficiency of the Omeka documentation.

I'll explain what I want to do so that you can understand what's missing in the documentation that would allow me to learn how to accomplish that.

I created a plugin, let's say it's called MyPlugin.

In this plugin I created a controlled called WhateverController which has a Show action (i.e. a showAction method).

Without doing anything else, that automatically gives me an url http://mydomain.com/my-plugin/whatever/show which runs the abovementioned action.

However:

1. The url http://mydomain.com/my-plugin/whatever/show/123 does not automagically populate an id parameter with the value 123, as it happens with the application's builtin controllers.
That is, if in WhateverController::showAction() I try to run:

    $id = $this->getRequest()->getParam('id');

that does not work. It returns null or an otherwise empty value.

So, I searched the documentation but found nothing about routes and how to customize them.
I also looked at the source code but it's too complex.

So, the first basic thing that the documentation fails to address is:

• How do you configure your plugin's routes so that they have the same basic default behavior of Omeka's builtin routes, where the pattern :controller/:action/:id gives you a request parameter called id.

Or called something else, which is another thing I wanted to do.

(I'm not sure whether this is something that can be entirely addressed at the plugin level or if I need to edit the application configuration to accomplish this; if it's the latter then there's a big flaw in the plugin architecture but for now I could live with that as long as somebody tells me how to do that. Either way it should be in the docs)

Much of this stuff works seems to be handled by the Zend Framework, which is also poorly documented, at least this version (not nearly as poorly as Omeka, of course), but it doesn't help that Omeka's documentation says absolutely nothing of which features of Zend exactly it is using and how.

2.
I would like some of the plugin controllers, whose names I know don't clash with any builtin controller, to be accessed without the plugin name as a prefix

That is, I would like to have this url:

http://mydomain.com/whatever/show

instead of http://mydomain.com/my-plugin/whatever/show, to be mapped to my plugin's WhateverController::showAction()

There must be a way to do that. It can't be that I'm condemned to have all the urls that are handled by my plugin's controllers start with the plugin name.

Again, this is probably handled by Zend and it may be documented in Zend's documentation, but Omeka's documentation gives me no clue where to look or even what to look for.

I know I can address both with Apache rewrite rules in .htaccess, but there must be a cleaner way.

"View Source" link is broken on every page, so people cannot view the documentation source (and potentially post an issue).

Understanding Omeka_Plugin_AbstractPlugin Tutorial should use _uninstallOptions instead of _installOptions.

The following:

"and Omeka_Plugin_AbstractPlugin::_installOptions in the uninstall callback."

Should be changed to:

"and Omeka_Plugin_AbstractPlugin::_uninstallOptions in the uninstall callback."

The recipes for Omeka 1.x worked pretty well, but we haven't gotten that momentum for Omeka 2.x, aka Omeka Classic.

If you've solved a small task and want to add it, please go for it. Recipes are located in https://github.com/omeka/Documentation/tree/master/source/Tutorials/recipes.

Pull requests to add are always welcome. If you have questions, please add them as comments on this issue.

See http://omeka.readthedocs.org/en/latest/Reference/libraries/Omeka/File/Derivative/StrategyInterface.html