A projection returns selected data from an existing entity without a new table. For example, ArticleCard can combine an article title, its section and a limited tag list. Creating, updating and deleting records through such an entity are not supported.
Create and inspect a projection
admingen-cli --path ./docs-demo projection add ArticleCard \
--source Article --module content --get=true --list=true \
--field id --field title
admingen-cli --path ./docs-demo --output json projection show ArticleCard
--source must reference a persistent entity with one primary key. Repeat --field for each field; field:alias changes only the response name. The source field is not renamed.
Add a section and tag collection
If Article.section and Article.tags relationships already exist, include them in the response:
admingen-cli --path ./docs-demo projection relation add ArticleCard section \
--as category --field id --field title
admingen-cli --path ./docs-demo projection relation add ArticleCard tags \
--field id --field title --default-limit 5 --max-limit 20 \
--order-by title --order-direction asc
Configure consistent limits and ordering for hasMany/manyToMany. A limit caps the nested list, so the response does not necessarily contain all related records. An inverse view uses the relationship's existing owner without creating a new one.
Change selected data
admingen-cli --path ./docs-demo projection field update ArticleCard title --as heading
admingen-cli --path ./docs-demo projection relation field add ArticleCard section slug
admingen-cli --path ./docs-demo projection relation update ArticleCard tags --default-limit 10
--field on add sets the initial selection. Then use nested field add/update/delete. --as= removes an alias. --clear-collection is allowed only for a relationship kind that can exist without collection settings.
projection update changes the source, module and read operations. After changing the source, check the entire selection. projection delete removes its model definition. General permissions can be changed through entity update, but source/select contents are configured through projection commands.
What the generator validates
Duplicate output names, missing source fields and inconsistent limits cause an error. Nested writes, arbitrary response extensions and projections sourced from projections are unsupported.
After changing the selection, check API clients and run Generate. In the admin system, a projection remains a read-only list and record view.
Commands
| Command | Invocation |
|---|---|
projection |
admingen-cli projection [command] |
projection add |
admingen-cli projection add <projection-name> [flags] |
projection delete |
admingen-cli projection delete <projection-name> [flags] |
projection field |
admingen-cli projection field [command] |
projection relation |
admingen-cli projection relation [command] |
projection show |
admingen-cli projection show <projection-name> [flags] |
projection update |
admingen-cli projection update <projection-name> [flags] |
projection field add |
admingen-cli projection field add <projection-name> <field-name> [flags] |
projection field delete |
admingen-cli projection field delete <projection-name> <field-name> [flags] |
projection field update |
admingen-cli projection field update <projection-name> <field-name> [flags] |
projection relation add |
admingen-cli projection relation add <projection-name> <relation-name> [flags] |
projection relation delete |
admingen-cli projection relation delete <projection-name> <relation-name> [flags] |
projection relation field |
admingen-cli projection relation field [command] |
projection relation update |
admingen-cli projection relation update <projection-name> <relation-name> [flags] |
projection relation field add |
admingen-cli projection relation field add <projection-name> <relation-name> <field-name> [flags] |
projection relation field delete |
admingen-cli projection relation field delete <projection-name> <relation-name> <field-name> [flags] |
projection relation field update |
admingen-cli projection relation field update <projection-name> <relation-name> <field-name> [flags] |
Global parameters are covered in CLI basics. Replace names in angle brackets with your own. Update preserves properties whose flags are omitted.
Selection and collection parameters
| Parameter | Used by | Default | Meaning |
|---|---|---|---|
--field VALUE |
projection add, projection relation add |
empty list | Initial selected field: field or field:alias. Repeat the flag; subsequent changes use separate field commands. |
--get |
projection add, projection update |
projection add: true; projection update: false |
Enable reading a projection by identifier. |
--list |
projection add, projection update |
false | For an entity, the UI list; for a projection, reading a list of root records. |
--module VALUE |
projection add, projection update |
empty string | For init, the Go module path; for an entity/projection, an existing navigation module. In update, moves the item. |
--source VALUE |
projection add, projection update |
empty string | Stored entity from which the projection reads. |
--as VALUE |
projection field add, projection field update, projection relation add, projection relation update, projection relation field add, projection relation field update |
empty string | Output name of a selected field/relationship; --as= clears the alias. |
--new-field VALUE |
projection field update, projection relation field update |
empty string | New source field for a selected projection item. |
--default-limit VALUE |
projection relation add, projection relation update |
0 | Default number of nested collection items. |
--max-limit VALUE |
projection relation add, projection relation update |
0 | Maximum number of nested collection items. |
--order-by VALUE |
projection relation add, projection relation update |
empty string | Default ordering field for a nested collection. |
--order-direction VALUE |
projection relation add, projection relation update |
"asc" | Default ordering direction: asc or desc. |
--clear-collection |
projection relation update |
false | Remove collection settings only when the resulting relation permits it. |
--new-relation VALUE |
projection relation update |
empty string | New source relationship for a selected projection item. |
Search, filtering and sorting
Each selected scalar's capabilities are configured independently of its persistent source. The flags are the same for projection field add/update and projection relation field add/update:
| Flag | Value on add | Result |
|---|---|---|
--searchable |
false | Search the selected string/text. |
--filterable |
false | Allowed typed filters. |
--sortable |
false | User-defined sorting by the field. |
admingen-cli --path ./docs-demo projection field update ArticleCard title --searchable --sortable --filterable
admingen-cli --path ./docs-demo projection relation field update ArticleCard section title --filterable --sortable
admingen-cli --path ./docs-demo projection relation field update ArticleCard tags title --searchable --sortable
Use original field and relationship names in commands, not output aliases. Pass =false to disable a setting.
A belongsTo field participates in root-record filtering and sorting. A hasMany/manyToMany field controls items inside the collection. For example, tag sorting changes tag order for each article, not the order of the articles themselves.
API requests, in contrast, use the output alias: tagsSearches, tagsFilters, tagsSort, tagsOrder, tagsLimit, tagsOffset. Limits and totals are calculated independently for each parent. If every item is filtered out, the parent remains with empty items. See the API format.
Mandatory read conditions
Configure list/get permissions through entity access and response contents through projection. There is no separate CLI flag for the server readRule tree: configure the root and collections in the Access UI or manifest.
The source persistent entity's rule is not automatically inherited. Independent PageBlock, Page and items conditions are illustrated in access rules.