Why Ditto Ignores `parents` When `documents` Is Set

A classic Ditto trap appears when a project mixes category logic and a manual document list. The legacy example called Ditto from PHP like this:

$res = $modx->runSnippet('Ditto', array(
    'parents'   => $like,
    'tpl'       => 'productTpl',
    'paginate'  => '1',
    'depth'     => '3',
    'display'   => $display,
    'documents' => $ids_str
));

The expectation was simple: use parents for the current category and documents for a custom subset. In practice Ditto ignored parents once documents was present.

Why That Happens

In Ditto, documents is not a secondary hint. It is an explicit resource list. Once you provide it, Ditto has already been told exactly which resources to render, so parent-based discovery no longer drives the selection.

What to Do Instead

• use parents when you want Ditto to discover resources from the tree
• use documents when you already know the exact resource IDs
• if you need both ideas at once, prepare the final ID list before calling Ditto

A Better Pattern for Multicategory Catalogs

For multicategory setups, the cleanest approach is usually to resolve the matching IDs first and then pass only the final filtered list to documents. That keeps the query deterministic and avoids the false impression that Ditto is applying both filters internally.

This old thread is still useful because the behavior is not a bug so much as a parameter-priority rule. Once you understand that, the output becomes predictable again.