Includes - Revision history

Luke: /* Dynamic Includes */

2023-06-15T12:44:30Z

Dynamic Includes

← Older revision		Revision as of 12:44, 15 June 2023
Line 237:		Line 237:
	Dynamic includes are a mechanism where you can include something of a database specified type. This is useful in, for example, featured content scenario's where the thing being featured could be a product, a business or really any other kind of content. In other words: the database is specifying what the content type is, and also the ID of the content too.		Dynamic includes are a mechanism where you can include something of a database specified type. This is useful in, for example, featured content scenario's where the thing being featured could be a product, a business or really any other kind of content. In other words: the database is specifying what the content type is, and also the ID of the content too.

	To use dynamic includes, declare the field name containing the type as well as the field name containing the ID. Note that the content type field ~~MUST~~ be a string, and the ID field must be a ulong.		To use dynamic includes, declare the field name containing the type as well as the field name containing the ID. Note that the content type field must be a string, and the ID field must be a ulong.

	<syntaxhighlight lang="csharp">		<syntaxhighlight lang="csharp">

Luke: /* Dynamic Includes */

2023-06-15T12:44:03Z

Dynamic Includes

← Older revision		Revision as of 12:44, 15 June 2023
Line 259:		Line 259:
	</syntaxhighlight>		</syntaxhighlight>

	Dynamic includes should however be considered a feature of last resort. As anything can be included this way, the UI is less structured as it doesn't necessarily know for certain what it will have to display.		Dynamic includes should however be considered a feature of last resort. If you know that something will be one of two types, then it is suggested to include lists of both of those types instead. As anything can be included this way, the UI is less structured as it doesn't necessarily know for certain what it will have to display.

	Globally available includes can be nested on dynamic includes too. For example, "item,item.tags" will obtain the dynamic item plus any tags on it. As functional includes such as primaryUrl are global, they are are available as well. If you use a wildcard, it will use all available implicit global includes.		Globally available includes can be nested on dynamic includes too. For example, "item,item.tags" will obtain the dynamic item plus any tags on it. As functional includes such as primaryUrl are global, they are are available as well. If you use a wildcard, it will use all available implicit global includes.

Luke: /* Functional Includes */

2023-06-15T12:42:08Z

Functional Includes

← Older revision		Revision as of 12:42, 15 June 2023
Line 228:		Line 228:

	It can be useful to run some code on a particular object whilst its JSON is generating. Whilst you can do this with the List and Load event handlers, it is generally recommended to use a functional include instead as it has less overhead. Their downside is they are global: they operate on any type. If you would like the primary URL of a piece of content, it is available as a functional include called "primaryUrl". In other words, including primaryUrl on a piece of content will provide a field called primaryUrl which would contain the page URL that content of that type is the primary content on.		It can be useful to run some code on a particular object whilst its JSON is generating. Whilst you can do this with the List and Load event handlers, it is generally recommended to use a functional include instead as it has less overhead. Their downside is they are global: they operate on any type. If you would like the primary URL of a piece of content, it is available as a functional include called "primaryUrl". In other words, including primaryUrl on a piece of content will provide a field called primaryUrl which would contain the page URL that content of that type is the primary content on.

			As with all includes, functional includes can also be nested. You can, for example include "tags,tags.primaryUrl" - to get a list of tags on this object, plus a primaryUrl for each tag - assuming some sort of /tags/{tag.slug} page exists.

	See also: PrimaryUrlValueGenerator for an example in your code.		See also: PrimaryUrlValueGenerator for an example in your code.

Luke at 12:40, 15 June 2023

2023-06-15T12:40:53Z

← Older revision		Revision as of 12:40, 15 June 2023
Line 224:		Line 224:
	);		);
	</syntaxhighlight>		</syntaxhighlight>

			= Functional Includes =

			It can be useful to run some code on a particular object whilst its JSON is generating. Whilst you can do this with the List and Load event handlers, it is generally recommended to use a functional include instead as it has less overhead. Their downside is they are global: they operate on any type. If you would like the primary URL of a piece of content, it is available as a functional include called "primaryUrl". In other words, including primaryUrl on a piece of content will provide a field called primaryUrl which would contain the page URL that content of that type is the primary content on.

			See also: PrimaryUrlValueGenerator for an example in your code.

			= Dynamic Includes =

			Dynamic includes are a mechanism where you can include something of a database specified type. This is useful in, for example, featured content scenario's where the thing being featured could be a product, a business or really any other kind of content. In other words: the database is specifying what the content type is, and also the ID of the content too.

			To use dynamic includes, declare the field name containing the type as well as the field name containing the ID. Note that the content type field MUST be a string, and the ID field must be a ulong.

			<syntaxhighlight lang="csharp">

			// Including "item" when obtaining this featured content would also obtain the referenced type
			// provided permission checks pass too of course.
			[HasVirtualField("Item", "ContentType", "ContentId")]
			public partial class FeaturedContent : VersionedContent<uint>
			{
			/// <summary>
			/// The content type name, e.g. "Product".
			/// </summary>
			public string ContentType;

			/// <summary>
			/// The content ID. e.g. A product ID.
			/// </summary>
			public ulong ContentId;
			}

			</syntaxhighlight>

			Dynamic includes should however be considered a feature of last resort. As anything can be included this way, the UI is less structured as it doesn't necessarily know for certain what it will have to display.

			Globally available includes can be nested on dynamic includes too. For example, "item,item.tags" will obtain the dynamic item plus any tags on it. As functional includes such as primaryUrl are global, they are are available as well. If you use a wildcard, it will use all available implicit global includes.

Luke: /* Single objects */

2023-04-26T01:19:56Z

Single objects

← Older revision		Revision as of 01:19, 26 April 2023
Line 112:		Line 112:

	"Create an includable field called CreatorUser, which will be a User type, and the ID of the user to include comes from the UserId field".		"Create an includable field called CreatorUser, which will be a User type, and the ID of the user to include comes from the UserId field".

			=== On the admin panel ===

			A virtual field declared in this way will cause a convenient dropdown selector to appear for the ID field on the admin panel (UI/ContentSelect). Sometimes though your included type may have thousands or millions of rows, so a dropdown is not appropriate and instead a search first mechanism is required. You can turn on search mode like so:

			<syntaxhighlight lang="csharp" line="1">

			[Data("titleField", "Name")] /* The field name to use as the title in the results list (or in the dropdown) */
			[Data("search", "true")] /* Use search mode instead of a dropdown of all */
			public uint OtherTypeNameId;

			</syntaxhighlight>

	==Lists==		==Lists==

Luke: /* Lists */

2023-04-26T00:39:48Z

Lists

← Older revision		Revision as of 00:39, 26 April 2023
Line 123:		Line 123:
	{		{
	public uint OtherTypeNameId;		public uint OtherTypeNameId;

			public string Name;
	}		}
	</syntaxhighlight>		</syntaxhighlight>
Line 128:		Line 130:

	You can use multiple ListAs declarations. Users is a good example of a use case for this - there is a list of permitted users on other types, but also you might want a list of members etc.		You can use multiple ListAs declarations. Users is a good example of a use case for this - there is a list of permitted users on other types, but also you might want a list of members etc.

			=== On the admin panel ===

			By default a ListAs field will appear as a content selector on the admin panel. This content selector uses a searchbar to find the content you're after and it will default to using the [[Content_Type_Meta_Fields\|meta title field]] of the thing being marked with ListAs. Meta title fields take a guess at an appropriate field to use if they are not explicitly marked and it will ultimately default to searching by a field called "Name" otherwise.

			For example, if you have the MyCustomType above, it has a field called Name so the search bar that appears will use that. If it did not have a field called Name, it will also attempt to use fields like "Title" and similar if they exist, based on the rules of the [[Content_Type_Meta_Fields\|meta title field]]. If you want some other field to be searched by, mark it as the meta title field instead:

			<syntaxhighlight lang="csharp" line="1">
			[Meta("title")]
			public string Registration;
			</syntaxhighlight>

			With that, the admin UI will then search by this field called Registration.

	===Explicit Lists===		===Explicit Lists===

Luke: /* Frontend Usage */

2023-03-16T17:22:38Z

Frontend Usage

← Older revision		Revision as of 17:22, 16 March 2023
Line 47:		Line 47:
	</syntaxhighlight>		</syntaxhighlight>

	In some rare cases you may need a [[~~form~~\|<Form>]] response to include something custom. By default edit and create include * with their response, but they don't know about any nested includes that you may need. Form has a requestOpts prop which gives you the ability to set raw values on the webRequest that it makes, allowing us to essentially do the same as above but with a form instead:		In some rare cases you may need a [[forms\|<Form>]] response to include something custom. By default edit and create include * with their response, but they don't know about any nested includes that you may need. Form has a requestOpts prop which gives you the ability to set raw values on the webRequest that it makes, allowing us to essentially do the same as above but with a form instead:

	<syntaxhighlight lang="js" line="1">		<syntaxhighlight lang="js" line="1">

Luke: /* Frontend Usage */

2023-03-16T17:22:19Z

Frontend Usage

← Older revision		Revision as of 17:22, 16 March 2023
Line 45:		Line 45:
	<syntaxhighlight lang="js" line="1">		<syntaxhighlight lang="js" line="1">
	webRequest('page/1', null, {includes: ['creatorUser']});		webRequest('page/1', null, {includes: ['creatorUser']});
			</syntaxhighlight>

			In some rare cases you may need a [[form\|<Form>]] response to include something custom. By default edit and create include * with their response, but they don't know about any nested includes that you may need. Form has a requestOpts prop which gives you the ability to set raw values on the webRequest that it makes, allowing us to essentially do the same as above but with a form instead:

			<syntaxhighlight lang="js" line="1">
			<Form action='page' requestOpts={{includes: ['*', 'creatorUser.tags']}}>
			..
	</syntaxhighlight>		</syntaxhighlight>

72.201.192.210: /* Lists */

2022-08-11T17:10:14Z

Lists

← Older revision		Revision as of 17:10, 11 August 2022
Line 112:		Line 112:
	<syntaxhighlight lang="csharp" line="1">		<syntaxhighlight lang="csharp" line="1">
	[ListAs("MyCustomTypes")]		[ListAs("MyCustomTypes")]
			[HasVirtualField("OtherTypeName", typeof(OtherTypeName), "OtherTypeNameId")]
	public partial class MyCustomType : VersionedContent<uint>		public partial class MyCustomType : VersionedContent<uint>
	{		{
Line 117:		Line 118:
	}		}
	</syntaxhighlight>		</syntaxhighlight>


	You can use multiple ListAs declarations. Users is a good example of a use case for this - there is a list of permitted users on other types, but also you might want a list of members etc.		You can use multiple ListAs declarations. Users is a good example of a use case for this - there is a list of permitted users on other types, but also you might want a list of members etc.

Luke at 15:59, 2 December 2021

2021-12-02T15:59:27Z

← Older revision		Revision as of 15:59, 2 December 2021
Line 61:		Line 61:
	</syntaxhighlight>		</syntaxhighlight>

	Nesting has no depth limit - you can use 3+ layers deep if you need to. Because you're spelling out each depth, there is no risk of recursion or cyclical behaviour either - you can include the creatorUser of a creatorUser, for example.		Nesting has no depth limit - you can use 3+ layers deep if you need to. Because you're spelling out each depth, there is no risk of recursion or cyclical behaviour either - you can include the creatorUser of a creatorUser, even if they are the same object. (And yes, Users do have a creatorUser as well - it can be used to identify if a user account was created by an admin for example).