Guidelines on customisation options when using hook_views_default_views?

Question

Are there any good instructions for the customisation options available when creating a default Views files using hook_views_default_views()?

The API for the function can be found here: http://api.drupal.org/api/views/views.api.php/function/hook_views_default_views/7

However I have yet to find any explicit information on the values that can be used and the options that are available when using the display_options array.

As an aside, here is an example where the lack of instruction become a problem for a novice Drupal developer: it's hard to know what to put for:

$handler->display->display_options['access']['type'] = 'none';

Do you add just add the name of a permission, or a role, if you want to restrict access? Is this even what the option means?

Answer 1

There is one neat and simple way. Create view normally, using GUI. Then export it. I created view default-demo for demonstration purposes:

http://example.org/admin/structure/views/view/default_demo/export

gives:

$view = new view();
$view->name = 'default_demo';
$view->description = '';
$view->tag = 'default';
$view->base_table = 'node';
$view->human_name = 'default demo';
$view->core = 7;
$view->api_version = '3.0';
$view->disabled = FALSE; /* Edit this to true to make a default view disabled initially     */

/* Display: Master */
$handler = $view->new_display('default', 'Master', 'default');
$handler->display->display_options['title'] = 'default demo';
$handler->display->display_options['use_more_always'] = FALSE;
$handler->display->display_options['access']['type'] = 'perm';
$handler->display->display_options['cache']['type'] = 'none';
$handler->display->display_options['query']['type'] = 'views_query';
$handler->display->display_options['exposed_form']['type'] = 'basic';
$handler->display->display_options['pager']['type'] = 'full';
$handler->display->display_options['pager']['options']['items_per_page'] = '10';
$handler->display->display_options['style_plugin'] = 'default';
$handler->display->display_options['row_plugin'] = 'node';
/* Field: Content: Title */
$handler->display->display_options['fields']['title']['id'] = 'title';
$handler->display->display_options['fields']['title']['table'] = 'node';
$handler->display->display_options['fields']['title']['field'] = 'title';
$handler->display->display_options['fields']['title']['label'] = '';
$handler->display->display_options['fields']['title']['alter']['word_boundary'] = FALSE;
$handler->display->display_options['fields']['title']['alter']['ellipsis'] = FALSE;
/* Sort criterion: Content: Post date */
$handler->display->display_options['sorts']['created']['id'] = 'created';
$handler->display->display_options['sorts']['created']['table'] = 'node';
$handler->display->display_options['sorts']['created']['field'] = 'created';
$handler->display->display_options['sorts']['created']['order'] = 'DESC';
/* Filter criterion: Content: Published */
$handler->display->display_options['filters']['status']['id'] = 'status';
$handler->display->display_options['filters']['status']['table'] = 'node';
$handler->display->display_options['filters']['status']['field'] = 'status';
$handler->display->display_options['filters']['status']['value'] = 1;
$handler->display->display_options['filters']['status']['group'] = 1;
$handler->display->display_options['filters']['status']['expose']['operator'] = FALSE;
/* Filter criterion: Content: Type */
$handler->display->display_options['filters']['type']['id'] = 'type';
$handler->display->display_options['filters']['type']['table'] = 'node';
$handler->display->display_options['filters']['type']['field'] = 'type';
$handler->display->display_options['filters']['type']['value'] = array(
  'article' => 'article',
);

/* Display: Page */
$handler = $view->new_display('page', 'Page', 'page');
$handler->display->display_options['path'] = 'default-demo';
$translatables['default_demo'] = array(
  t('Master'),
  t('default demo'),
  t('more'),
  t('Apply'),
  t('Reset'),
  t('Sort by'),
  t('Asc'),
  t('Desc'),
  t('Items per page'),
  t('- All -'),
  t('Offset'),
  t('« first'),
  t('‹ previous'),
  t('next ›'),
  t('last »'),
  t('Page'),
);

As you can see that's exactly what you would want to put into hook_views_default_views function. Simple as this :D

If you can't find export link, it's at top right, drop down edit view name/description to see it.

Everything available from code is supposed to be available from GUI too, with the notable exceptions of $view->core and $view->api_version that are always set by gui to the current release and must match what you set in hook_views_api() in your module.

For specific line you asked for:

$handler->display->display_options['access']['type'] = 'none';

You need to go to Page Settings > Access, set things as you want them, export view. Done. It seems that Views developers chooses to use their time to give us tools, not documentation, when their time is limited, but the tools they give us are comprehensive.

Answer 2

The modular way in which views is written is very clever and interesting, yet a little daunting the first few times :). I am afraid the only option here is going through the code (with some patience and grep :). Also some interesting info is written in the advanced help for views, people tend to forget about it.
Basically : any display can define any options, some of them are common. The options are defined in special hooks in the displays (check the plugins folder under views).
Access is slightly more complicated, because it is a plugin in a plugin :). So basically in the type option you select one of the available plugins (and you can write your own) and the plugin sets the values for the other options. The default access plugins are 'none' 'role' and 'perm'.
Another way to find these 3 values out is to check the source of the form, ofcourse.

Answer 3

Regarding the original poster's question about details of the Views API in terms of adding access permissions to Views:

$handler->display->display_options['access']['type'] = 'none';

The default perm given to a new view is:

$handler->display->display_options['access']['type'] = 'perm';

What I found confusing when trying to figure out how Views works is that the view definition will not explicitly identify which perm is actually required if the default perm is left in place: "View published content" (whose machine name is 'access content').

However, if the perm required for access is anything but "View published content" then there will need to be another line in the views definition like this:

$handler->display->display_options['access']['type'] = 'perm';
$handler->display->display_options['access']['perm'] = 'administer comments';

The perm name used in the Views definition is the perm's machine name (which does allow spaces unlike other machine names in Drupal).

To find the machine name of a perm: install and enable the Devel module. Then go to: Configuration => Development => Devel settings (/admin/config/development/devel) and tick on the checkbox Display machine names of permissions and modules. Then you go to the permissions page and hover over the perm you want.

Or you can just use the Views UI to select the perm, then export the View and then you can see its machine name in the exported code.