A class, generated for each controller-backed type in your data model as <ModelName>ApiClient and exported from api-clients.g.ts containing one method for each API endpoint.
Each method on the API client takes in the regular parameters of the method as you would expect, as well as an optional AxiosRequestConfig parameter at the end that can be used to provide additional configuration for the single request, if needed.
API Callers (typed with the name ApiState in coalesce-vue, sometimes also referred to as "loaders" or "invokers") are stateful functions for invoking an API endpoint, created with the $makeCaller function on an API Client. A summary of features:
Each API Caller is itself a function, so it can be invoked to trigger an API request to the server.
API Callers contain properties about the last request made, including things like wasSuccessful, isLoading, result, and more.
Using setConcurrency(mode), you can configure how each individual caller handles what happens when multiple requests are made simultaneously
Some examples:
// Preamble for all the examples below:
+import { PersonApiClient } from '@/api-clients.g';
+const client = new PersonApiClient;
+A caller that takes no additional parameters:
const caller = client.$makeCaller(
+ "item",
+ c => c.namesStartingWith("A")
+);
+
+await caller();
+console.log(caller.result)
+A caller that takes custom parameters:
const caller = client.$makeCaller(
+ methods => methods.namesStartingWith,
+ (c, str: string) => c.namesStartingWith(str)
+);
+
+await caller("Rob");
+console.log(caller.result)
+const caller = client.$makeCaller("item",
+ // The parameter-based version is always required, even if it won't be used.
+ (c, str: string) => c.namesStartingWith(str),
+ // A function which creates a blank instance of the args object.
+ // All props should be initialized (i.e. not undefined) to work with Vue's reactivity.
+ () => ({str: null as string | null, }),
+ // The function that accepts the args object and uses it:
+ (c, args) => c.namesStartingWith(args.str)
+);
+
+caller.args.str = "Su";
+await caller.invokeWithArgs();
+console.log(caller.result)
+A caller that performs multiple async operations:
const deleteFirstNameStartingWith = client.$makeCaller(
+ "item",
+ async (c, str: string) => {
+ const namesResult = await c.namesStartingWith(str)
+ return await c.deletePersonByName(namesResult.data.object[0])
+ }
+);
+
+await caller("Rob");
+console.log(caller.result)
+The first parameter, resultType, can either be one of "item" or "list", indicating whether the method returns a ItemResult or ListResult (examples #1 and #3 above). It can also be a function which accepts the set of method metadata for the API Client and which returns the specific method metadata (example #2 above), or it can be a direct reference to a specific method metadata object.
The following state properties can be found on API Caller instances. These properties are useful for binding to in a user interface to display errors, results, or indicators of progress.
API callers have a setConcurrency method that allows you to customize how they behave when additional invocations are performed when there is already a request pending. There are four options available, with "disallow" being the default:
"disallow"The default behavior - simply throws an error for any secondary invocations.
Note
Having "disallow" as the default prevents the unexpected behavior that can happen in a number of ways with the other modes:
"debounce"When a secondary invocation is performed, enqueue it after the current pending invocation completes.
If additional invocations are performed while there is already an invocation enqueued and waiting, the already-enqueued invocation is abandoned and replaced by the most recent invocation attempt. The promise of the abandoned invocation will be resolved with undefined (it is NOT rejected).
"cancel"When a secondary invocation is performed, cancel the current pending invocation.
',9),ye={href:"https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.http.httpcontext.requestaborted?view=aspnetcore-3.1",target:"_blank",rel:"noopener noreferrer"},me=s("code",null,"undefined",-1),fe=i('"allow"When a secondary invocation is performed, always continue normally, sending the request to the server.
The state of the properties on the caller at any time will reflect the most recent response received from the server, which is never guaranteed to correlate with the most recent request made to the server - that is, requests are not guaranteed to complete in the order they were made. In particular, the isLoading property will be false after the first response comes back, even if the second response has not yet been received.
WARNING
For the reasons outlined above, it is generally not recommended to use "allow" unless you fully understand the drawbacks. This mode mirrors the legacy behavior of the Knockout stack for Coalesce.
Response caching on API Callers is a feature that will save API responses to persistent storage (sessionStorage or localStorage). The next time a matching request is made, the result property of the API Caller will be populated with that saved response, allowing for a faster time to interactivity and reduced repaints and shifting of elements as initial data loads after a page navigation. It does not prevent any HTTP requests from being made, and does not affect the Promise returned from invoke or invokeWithArgs.
Common use cases include:
When a cached response is loaded, result is populated with that response's data, wasSuccessful and hasResult are set to true, and onFulfilled callbacks are invoked.
export type ResponseCachingConfiguration = {
+ /** Function that will determine the cache key used for a particular request.
+ * Return a falsy value to prevent caching. The default key is the request URL.
+ */
+ key?: (
+ req: AxiosRequestConfig,
+ defaultKey: string
+ ) => string | null | undefined;
+
+ /** The maximum age of a cached response. If null, the entry will not expire. Default 1 hour.
+ *
+ * The smallest of the current configured max age and the max age that was set at the time of the cached response is used. */
+ maxAgeSeconds?: number | null;
+
+ /** The Storage (default \`sessionStorage\`) that will hold cached responses. */
+ storage?: Storage;
+};
+API Callers have a few other methods available as well:
`,3),ge=s("p",null,[e("Manually cancel the current request. The promise of the cancelled invocation will be resolved with "),s("code",null,"undefined"),e(" (it is NOT rejected). If using concurrency mode "),s("code",null,'"allow"'),e(", only the most recent invocation is cancelled.")],-1),be=s("p",null,[e("Add a callback to the caller to be invoked when a success response is received from the server. If a promise is returned, this promise will be awaited and will delay the setting of the "),s("code",null,"isLoading"),e(" prop to "),s("code",null,"false"),e(" until it completes.")],-1),_e=s("p",null,[e("Add a callback to the caller to be invoked when a failure response is received from the server. If a promise is returned, this promise will be awaited and will delay the setting of the "),s("code",null,"isLoading"),e(" prop to "),s("code",null,"false"),e(" until it completes.")],-1),we=s("p",null,[e("The invoke function is a reference from the caller to itself. In other words, "),s("code",null,"caller.invoke === caller"),e(". This exists to mirror the syntax of the Knockout generated method classes.")],-1),Ae=s("p",null,[e("If called a parameter, that parameter will be used as the args object. Otherwise, "),s("code",null,"caller.args"),e(" will be used.")],-1),Ee=s("p",null,"Only exists if the caller was created with the option of being invoked with an args object as described in the sections above.",-1),ke={href:"https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL",target:"_blank",rel:"noopener noreferrer"},qe=s("code",null,"result",-1),Fe=s("p",null,[e("Accepts a "),s("code",null,"Vue"),e(" instance in order to manage the lifecycle of the URL, since object URLs must be manually released to avoid memory leaks. When the provided Vue component is destroyed, the object URL will be destroyed. If called inside the component template, the Vue instance can be acquired automatically.")],-1),Ie=s("p",null,"Only exists if the caller was created with the option of being invoked with an args object as described in the sections above.",-1);function xe(Te,Pe){const l=c("RouterLink"),r=c("ExternalLinkIcon"),t=c("router-link"),o=c("Prop");return u(),h("div",null,[y,p(" MARKER:summary "),s("p",null,[e("The API client layer, generated as "),m,e(", exports a class for each API controller that was generated for your data model. These classes are stateless and provide one method for each API endpoint. This includes both the standard set of endpoints created for "),n(l,{to:"/modeling/model-types/entities.html"},{default:a(()=>[e("Entity Models")]),_:1}),e(" and "),n(l,{to:"/modeling/model-types/dtos.html"},{default:a(()=>[e("Custom DTOs")]),_:1}),e(", as well as any custom "),n(l,{to:"/modeling/model-components/methods.html"},{default:a(()=>[e("Methods")]),_:1}),e(" on the aforementioned types, as well as any methods on your "),n(l,{to:"/modeling/model-types/services.html"},{default:a(()=>[e("Services")]),_:1}),e(".")]),p(" MARKER:summary-end "),s("p",null,[e("The API clients provided by Coalesce are based on "),s("a",f,[e("axios"),n(r)]),e(". All API clients used a shared axios instance, exported from "),v,e(" as "),C,e(". This instance can be used to configure all HTTP requests made by Coalesce, including things like attaching "),s("a",g,[e("interceptors"),n(r)]),e(" to modify the requests being made, or configuring "),s("a",b,[e("defaults"),n(r)]),e(".")]),s("p",null,[e("As with all the layers, the "),s("a",_,[e("source code of coalesce-vue"),n(r)]),e(" is also a great supplement to this documentation.")]),s("nav",w,[s("ul",null,[s("li",null,[n(t,{to:"#concepts"},{default:a(()=>[e("Concepts")]),_:1}),s("ul",null,[s("li",null,[n(t,{to:"#api-client"},{default:a(()=>[e("API Client")]),_:1})]),s("li",null,[n(t,{to:"#api-callers-api-states"},{default:a(()=>[e("API Callers/API States")]),_:1})])])]),s("li",null,[n(t,{to:"#api-callers"},{default:a(()=>[e("API Callers")]),_:1}),s("ul",null,[s("li",null,[n(t,{to:"#creating-and-invoking-an-api-caller"},{default:a(()=>[e("Creating and Invoking an API Caller")]),_:1})]),s("li",null,[n(t,{to:"#properties"},{default:a(()=>[e("Properties")]),_:1})]),s("li",null,[n(t,{to:"#concurrency-mode"},{default:a(()=>[e("Concurrency Mode")]),_:1})]),s("li",null,[n(t,{to:"#response-caching"},{default:a(()=>[e("Response Caching")]),_:1})]),s("li",null,[n(t,{to:"#other-methods"},{default:a(()=>[e("Other Methods")]),_:1})])])])])]),A,s("p",null,[e("For the methods that correspond to the standard set of CRUD endpoints that Coalesce provides ("),E,e(", "),k,e(", "),q,e(", "),F,e(", "),I,e("), an additional parameter "),x,e(" is available that accepts the set of "),n(l,{to:"/modeling/model-components/data-sources.html#standard-parameters"},{default:a(()=>[e("Standard Parameters")]),_:1}),e(" appropriate for the endpoint.")]),s("p",null,[e("Each method returns a "),T,e(" where "),P,e(" is either "),R,e(", "),S,e(", or "),L,e(", depending on the return type of the API endpoint. "),j,e(" is the "),s("a",B,[e("response object from axios"),n(r)]),e(", containing the "),W,e(" in its "),M,e(" property, as well as other properties like "),O,e(". The returned type "),V,e(" is automatically converted into valid "),n(l,{to:"/stacks/vue/layers/models.html"},{default:a(()=>[e("Model implementations")]),_:1}),e(" for you.")]),N,U,s("p",null,[e("Because they are such an integral part of the overall picture of "),H,e(", they have "),n(l,{to:"/stacks/vue/layers/api-clients.html"},{default:a(()=>[e("their own section below")]),_:1}),e(" where they are explained in much greater detail.")]),$,s("p",null,[e("API Callers can be created so that they have an "),z,e(" object that can be bound to, using "),K,e(" to make a request using those arguments as the API endpoint's parameters. The API Callers created for the "),n(l,{to:"/stacks/vue/layers/viewmodels.html"},{default:a(()=>[e("ViewModel Layer")]),_:1}),e(" are all created this way.")]),G,Q,s("div",X,[J,s("p",null,[e("During typical development, it is unlikely that you'll need to make a custom API Caller - the ones created for you on the generated "),n(l,{to:"/stacks/vue/layers/viewmodels.html"},{default:a(()=>[e("ViewModel Layer")]),_:1}),e(" will usually suffice. However, creating your own can allow for some more advanced functionality.")])]),Y,s("p",null,[e("A caller that has an args object that can be bound to. This is how the generated API Callers in the "),n(l,{to:"/stacks/vue/layers/viewmodels.html"},{default:a(()=>[e("ViewModel Layer")]),_:1}),e(" are created:")]),Z,n(o,{def:"isLoading: boolean",lang:"ts"}),ee,n(o,{def:"wasSuccessful: boolean | null",lang:"ts"}),se,n(o,{def:"message: string | null",lang:"ts"}),ne,n(o,{def:"hasResult: boolean",lang:"ts"}),ae,n(o,{def:"args: {}",lang:"ts"}),oe,le,n(o,{def:"get url(): string",lang:"ts"}),te,re,ie,n(o,{def:"result: T | null",lang:"ts",id:"member-result-item"}),ce,n(o,{def:"validationIssues: ValidationIssue[] | null",lang:"ts"}),s("p",null,[e("Any validation issues returned by the previous request. This is never populated automatically by Coalesce, and is therefore is only used if you have written custom code to populate it in your "),n(l,{to:"/modeling/model-components/behaviors.html"},{default:a(()=>[e("Behaviors")]),_:1}),e(" or "),n(l,{to:"/modeling/model-components/methods.html"},{default:a(()=>[e("Methods")]),_:1}),e(".")]),pe,n(o,{def:"result: ArrayCoalesce also supports a number of the built-in System.ComponentModel.DataAnnotations attributes and will use these to shape the generated code.
The displayed name and description of a property, as well as the order in which it appears in generated views, can be set via the [Display] attribute. By default, properties will be displayed in the order in which they are defined in their class.
The displayed name of a property can also be set via the [DisplayName] attribute.
To create your own behaviors, you simply need to define a class that implements IntelliTect.Coalesce.IBehaviors<T>. To expose your behaviors to Coalesce, either place it as a nested class of the type T that your behaviors are for, or annotate it with the [Coalesce] attribute. Of course, the easiest way to create behaviors that doesn't require you to re-engineer a great deal of logic would be to inherit from IntelliTect.Coalesce.StandardBehaviors<T, TContext>, and then override only the parts that you need.
public class Case
+{
+ public int CaseId { get; set; }
+ public int OwnerId { get; set; }
+ public bool IsDeleted { get; set; }
+ ...
+}
+
+[Coalesce]
+public class CaseBehaviors : StandardBehaviors<Case, AppDbContext>
+{
+ public CaseBehaviors(CrudContext<AppDbContext> context) : base(context) { }
+
+ public override ItemResult BeforeSave(SaveKind kind, Case oldItem, Case item)
+ {
+ // Allow admins to bypass all validation.
+ if (User.IsInRole("Admin")) return true;
+
+ if (kind == SaveKind.Update && oldItem.OwnerId != item.OwnerId)
+ return "The owner of a case may not be changed";
+
+ // This is a new item, OR its an existing item and the owner isn't being modified.
+ if (item.CreatedById != User.GetUserId())
+ return "You are not the owner of this item.";
+
+ return true;
+ }
+
+ public override ItemResult BeforeDelete(Case item)
+ => User.IsInRole("Manager") ? true : "Unauthorized";
+
+ public override Task ExecuteDeleteAsync(Case item)
+ {
+ // Soft delete the item.
+ item.IsDeleted = true;
+ return Db.SaveChangesAsync();
+ }
+}
+All behaviors are instantiated using dependency injection and your application's IServiceProvider. As a result, you can add whatever constructor parameters you desire to your behaviors as long as a value for them can be resolved from your application's services. The single parameter to the StandardBehaviors is resolved in this way - the CrudContext<TContext> contains the common set of objects most commonly used, including the DbContext and the ClaimsPrincipal representing the current user.
The standard behaviors, IntelliTect.Coalesce.StandardBehaviors<T> and its EntityFramework-supporting sibling IntelliTect.Coalesce.StandardBehaviors<T, TContext>, contain a significant number of properties and methods that can be utilized and/or overridden at your leisure.
A data source that, if set, will override the data source that is used to retrieve the target of an delete operation from the database after it has been deleted. If an object is able to be retrieved from this data source, it will be sent back to the client. This allows soft-deleted items to be returned to the client when the user is able to see them. Null by default; override by setting a value in the constructor.
The standard behaviors implementation contains many different methods which can be overridden in your derived class to control functionality.
These methods often call one another, so overriding one method may cause some other method to no longer be called. The hierarchy of method calls, ignoring any logic or conditions contained within, is as follows:
SaveAsync
+ DetermineSaveKindAsync
+ GetDbSet
+ ValidateDto
+ MapIncomingDto
+ BeforeSaveAsync
+ BeforeSave
+ ExecuteSaveAsync
+ AfterSave
+
+DeleteAsync
+ BeforeDeleteAsync
+ BeforeDelete
+ ExecuteDeleteAsync
+ GetDbSet
+ AfterDelete
+All of the methods outlined above can be overridden. A description of each of the methods is as follows:
`,7),x=e("p",null,[s("Save the given item. This is the main entry point for saving, and takes a DTO as a parameter. This method is responsible for performing mapping to your EF models and ultimately saving to your database. If it is required that you access properties from the incoming DTO in this method, a set of extension methods "),e("code",null,"GetValue"),s(" and "),e("code",null,"GetObject"),s(" are available on the DTO for accessing properties that are mapped 1:1 with your EF models.")],-1),k=e("p",null,"Given the incoming DTO on which Save has been called, examine its properties to determine if the operation is meant to be a create or an update operation. Return this distinction along with the key that was used to make the distinction.",-1),F=e("p",null,"This method is called outside of the standard data source by the base API controller to perform role-based security on saves at the controller level.",-1),j=e("p",null,[s("Returns a "),e("code",null,"DbSetMap the properties of the incoming DTO to the model that will be saved to the database. For a SaveKind.Create, this will call the MapToNew method on the DTO and a new instance must be returned (item will be null). For a SaveKind.Update, this will call the MapTo method on the DTO, and the incoming item must be returned. If more precise control is needed, extension methods on IClassDto<T> or casting to a known type can be used to get specific values. If all else fails, the DTO can be reflected upon.
You can, of course, create a custom base behaviors class that all your custom implementations inherit from. But, what if you want to override the standard behaviors across your entire application, so that StandardBehaviors<,> will never be instantiated? You can do that too!
Simply create a class that implements IEntityFrameworkBehaviors<,> (the StandardBehaviors<,> already does - feel free to inherit from it), then register it at application startup like so:
public class MyBehaviors<T, TContext> : StandardBehaviors<T, TContext>
+ where T : class
+ where TContext : DbContext
+{
+ public MyBehaviors(CrudContext<TContext> context) : base(context)
+ {
+ }
+
+ ...
+}
+public void ConfigureServices(IServiceCollection services)
+{
+ services.AddCoalesce(b =>
+ {
+ b.AddContext<AppDbContext>();
+ b.UseDefaultBehaviors(typeof(MyBehaviors<,>));
+ });
+Your custom behaviors class must have the same generic type parameters - <T, TContext>. Otherwise, the Microsoft.Extensions.DependencyInjection service provider won't know how to inject it.
<select data-bind="
+ select2Ajax: personId,
+ url: '/api/Person/list',
+ idField: 'personId',
+ textField: 'Name',
+ object: person,
+ allowClear: true
+"></select>
+Creates a select2 dropdown using the specified url and fields that can be used to select an object from the endpoint specified. Additional complimentary bindings include:
`,4),g=e("p",null,"The Coalesce List API url to call to populate the contents of the dropdown.",-1),v=e("p",null,[s("The name of the field on each item in the results of the AJAX call which contains the ID of the option. The value of this field will be set on the observable specified for the main "),e("code",null,"select2Ajax"),s(" binding.")],-1),C=e("p",null,"The name of the field on each item in the results of the AJAX call which contains the text to be displayed for each option.",-1),_=e("p",null,[s("An observable that holds the full object corresponding to the foreign key property being bound to. If the selected value changes, this will be set to null to avoid representation of incorrect data (unless "),e("code",null,"setObject"),s(" is used - see below).")],-1),x=a("If true, the observable specified by the object binding will be set to the selected data when an option is chosen in the dropdown. Binding itemViewModel is required if this binding is set.
Additionally, requests to the API to populate the dropdown will request the entire object, as opposed to only the two fields specified for idField and textField like is normally done when this binding is missing or set to false. To override this behavior and continue requesting only specific fields even when setObject is true, add fields=field1,field2,... to the query string of the url binding.
If true, the dropdown will open when tabbed to. Browser support may be incomplete in some versions of IE.
<select multiple="multiple" data-bind="
+ select2AjaxMultiple: people,
+ url: '/api/Person/list',
+ idField: 'personId',
+ textField: 'Name',
+ itemViewModel: ViewModels.PersonCase
+"></select>
+Creates a select2 multi-select input for choosing objects that participate as the foreign object in a many-to-many relationship with the current object. The primary select2AjaxMultiple binding takes the collection of items that make up the foreign side of the relationship. This is NOT the collection of the join objects (a.k.a. middle table objects) in the relationship.
Additional complimentary bindings include:
`,5),M=e("p",null,[s("The Coalesce List API url to call to populate the contents of the dropdown. In order to only receive specific fields from the server, add "),e("code",null,"fields=field1,field2,..."),s(" to the query string of the url, ensuring that at least the "),e("code",null,"idField"),s(" and "),e("code",null,"textField"),s(" are included in that collection.")],-1),O=e("p",null,"The name of the field on each item in the results of the AJAX call which contains the ID of the option. The value of this field will be set as the key of the foreign object in the many-to-many relationship.",-1),B=e("p",null,"The name of the field on each item in the results of the AJAX call which contains the text to be displayed for each option.",-1),P=e("p",null,[s("A reference to the class that represents the types in the supplied collection. For example, a many-to-many between "),e("code",null,"Person"),s(" and "),e("code",null,"Case"),s(" objects where "),e("code",null,"Case"),s(" is the object being bound to and "),e("code",null,"Person"),s(" is the type represented by a child collection, the correct value is "),e("code",null,"ViewModels.Person"),s(". This is used when constructing new objects representing the relationship when a new item is selected.")],-1),V=e("p",null,"The number of items to request in each call to the server.",-1),S=e("p",null,[s("A string containing the substring "),e("code",null,"{0}"),s(", which will be replaced with the text value of an option in the dropdown list when the option is displayed.")],-1),N=e("p",null,[s("A string containing the substring "),e("code",null,"{0}"),s(", which will be replaced with the text value of the selected option of the dropdown list.")],-1),K=e("p",null,"If true, a cache-busting querystring parameter will be included in AJAX requests.",-1),Y=e("p",null,[s("Directly maps to select2 option "),e("code",null,"selectOnClose"),s(".")],-1),z=e("p",null,[s("Whether or not to allow the current select to be set to null. Directly maps to select2 option "),e("code",null,"allowClear"),s(".")],-1),L=e("p",null,[s("Placeholder when nothing is selected. Directly maps to select2 option "),e("code",null,"placeholder"),s(".")],-1),W=a(`If true, the dropdown will open when tabbed to. Browser support may be incomplete in some versions of IE.
<select data-bind="
+ select2AjaxText: schoolName,
+ url: '/api/Person/SchoolNames'
+"></select>
+Creates a select2 dropdown against the specified url where the url returns a collection of string values that are potential selection candidates. The dropdown also allows the user to input any value they choose - the API simply serves suggested values.
`,4),X=a("The url to call to populate the contents of the dropdown. This should be an endpoint that returns one of the following:
string[]{ list: string[] }{ object: string[] }{ list: { [prop: string]: string } } where the value given to resultField is a valid property of the returned objects.{ object: { [prop: string]: string } } where the value given to resultField is a valid property of the returned objects.The url will also be passed a search parameter and a page parameter appended to the query string. The chosen endpoint is responsible for implementing this functionality. Page size is expected to be some fixed value. Implementer should anticipate that the requested page may be out of range.
The cases listed above that accept arrays of objects (as opposed to arrays of strings) require that the resultField binding is also used. These are designed for obtaining string values from objects obtained from the standard list endpoint.
If true, the dropdown will open when tabbed to. Browser support may be incomplete in some versions of IE.
<select data-bind="select2: selectedNumber">
+ <option value="1">Option 1</option>
+ <option value="2">Option 2</option>
+</select>
+If true, the dropdown will open when tabbed to. Browser support may be incomplete in some versions of IE.
<div class="input-group date">
+ <input data-bind="datePicker: birthDate" type="text" class="form-control" id-prefix="datePicker" />
+ <span class="input-group-addon">
+ <span class="fa fa-calendar"></span>
+ </span>
+</div>
+If true, the datePicker will update the underlying observable on each input change. Otherwise, the observable will only be changed when the datePicker loses focus (on blur).
<div data-bind="with: product">
+ <input type="text" data-bind="textValue: description, saveImmediately: true" />
+</div>
+<div data-bind="with: product">
+ <input type="text" data-bind="textValue: description, delaySave: true" />
+</div>
+<div data-bind="tooltip: tooltipText">Some Element</div>
+<div data-bind="tooltip: {title: note, placement: 'bottom', animation: false}">Some Element</div>
+<div data-bind="fadeVisible: isVisible">Some Element</div>
+Similar to the Knockout visible binding, but uses jQuery fadeIn/fadeOut calls to perform the transition.
<div data-bind="slideVisible: isVisible">Some Element</div>
+Similar to the Knockout visible, but uses jQuery slideIn/slideOut calls to perform the transition.
<div data-bind="moment: momentObservable"></div>
+<div data-bind="moment: momentObservable, format: 'MM/DD/YYYY hh:mm a'"></div>
+Controls the text of the element by calling the format method on a moment object.
<div data-bind="momentFromNow: momentObservable"></div>
+<div data-bind="momentFromNow: momentObservable, shorten: true"></div>
+Controls the text of the element by calling the fromNow method on a moment object. If shorten is true, certain phrases will be slightly shortened.
<div class="item">
+ <!-- ko let: { showControls: $data.isEditing() || $parent.editingChildren() } -->
+ <button data-bind="click: $root.editItem, visible: showControls">Edit</button>
+ <span data-bind="text: name"></span>
+ <button data-bind="click: $root.deleteItem, visible: showControls">Delete</button>
+ <!-- /ko -->
+</div>
+The let binding is a somewhat common construct used in Knockout applications, but isn't part of Knockout itself. It effectively allows the creation of variables in the binding context, allowing complex statements which may be used multiple times to be aliased for both clarity of code and better performance.
These are static properties on IntelliTect.Coalesce.Knockout.Helpers.Knockout you can assign to somewhere in the app lifecycle startup to change the default markup generated server-side when using @Knockout.* methods to render Knockout bindings in your .cshtml files.
The date/time picker properties can be coupled with DateTimeOffset model properties to display time values localized for the current user's locale. If you want to make the localization static, simply include a script block in your _Layout.cshtml or in a specific view that sets the default for Moment.js:
<script>
+moment.tz.setDefault("America/Chicago");
+</script>
+Note
This needs to happen after Moment is loaded, but before the bootstrap-datetimepicker script is loaded.
<!-- Renders regularly as text: -->
+<c-admin-display :model="person" for="firstName" />
+
+<!-- Renders as a link to an item: -->
+<c-admin-display :model="person" for="company" />
+
+<!-- Renders as a link to a list: -->
+<c-admin-display :model="person" for="casesAssigned" />
+// router.ts or main.ts
+
+// WITHOUT Vuetify A la carte:
+import { CAdminEditorPage } from 'coalesce-vue-vuetify';
+// WITH Vuetify A-la-carte:
+import { CAdminEditorPage } from 'coalesce-vue-vuetify/lib';
+
+const router = new Router({
+ // ...
+ routes: [
+ // ... other routes
+ {
+ path: '/admin/:type/edit/:id?',
+ name: 'coalesce-admin-item',
+ component: CAdminEditorPage,
+ props: true,
+ },
+ ]
+})
+<c-admin-editor :model="person" />
+<c-admin-method :model="person" for="setTitle" auto-reload-model />
+<c-admin-methods :model="person" class="x" auto-reload-model />
+<c-admin-methods :model="person" auto-reload-model />
+<c-admin-methods :model="personList" auto-reload-model />
+// router.ts or main.ts
+
+// WITHOUT Vuetify A la carte:
+import { CAdminTablePage } from 'coalesce-vue-vuetify';
+// WITH Vuetify A-la-carte:
+import { CAdminTablePage } from 'coalesce-vue-vuetify/lib';
+
+const router = new Router({
+ // ...
+ routes: [
+ // ... other routes
+ {
+ path: '/admin/:type',
+ name: 'coalesce-admin-list',
+ component: CAdminTablePage,
+ props: true,
+ },
+ ]
+})
+<c-admin-table-toolbar :list="personList" />
+<c-admin-table-toolbar :list="personList" color="pink" :editable.sync="isEditable" />
+<c-admin-table :list="personList" />
+<c-datetime-picker :model="person" for="birthDate" />
+
+<c-datetime-picker v-model="standaloneDate" />
+
+<c-datetime-picker
+ v-model="standaloneTime"
+ date-kind="time"
+ date-format="h:mm a"
+/>
+The format of the date that will be rendered in the component's text field, and the format that will be attempted first when parsing user input in the text field.
Defaults to:
M/d/yyyy h:mm a if dateKind == 'datetime',M/d/yyyy if dateKind == 'date', orh:mm a if dateKind == 'time'.Typical usage, providing an object and a property on that object:
<c-display :model="person" for="gender" />
+<c-display :model="person" for="birthDate" format="M/d/yyyy" />
+<c-display
+ :value="person.setFirstName.result"
+ :for="person.$metadata.methods.setFirstName.return"
+ element="div"
+/>
+Displaying a standalone date value without a model or other source of metadata:
<c-display :value="dateProp" format="M/d/yyyy" />
+Can be provided the value to be displayed in conjunction with the for prop, as an alternative to the model prop.
This is an uncommon scenario - it is generally easier to use the for/model props together.
default - Used to display fallback content if the value being displayed is either null or "" (empty string).
For properties and other values annotated with [DataTypeAttribute], the following special handling occurs based on the data type:
DataType.MultilineText: Renders with white-space: pre-wrap.DataType.Password: Renders with a show/hide toggle (hidden by default), showing a fixed number of dot characters when hidden.DataType.Url: Renders as a clickable link.DataType.EmailAddress: Renders as a clickable mailto link.DataType.PhoneNumber: Renders as a clickable tel link.DataType.ImageUrl: Renders as an img element."Color": Renders a colored dot next to the value, interpreting the field value as a 7-character HTML hex color code..Typical usage, providing an object and a property on that object:
<c-input :model="person" for="firstName" />
+<c-input :model="comment" for="content" textarea solo />
+<c-input
+ :model="person.setFirstName"
+ for="newName" />
+Or, using a more verbose syntax:
<c-input
+ :model="person.setFirstName.args"
+ for="Person.methods.setFirstName.newName" />
+<c-input :model="personList.$dataSource" for="startsWith" />
+Usage with v-model (this scenario is atypical - the model/for pair of props are used in almost all scenarios):
<c-input v-model="person.firstName" for="Person.firstName" />
+<c-list-filters :list="list" />
+<c-list-page-size :list="list" />
+<c-list-page :list="list" />
+<c-list-pagination :list="list" />
+<c-list-range-display :list="list" />
+Wrap contents of a details/edit page:
<h1>Person Details</h1>
+<c-loader-status
+ :loaders="{
+ 'no-initial-content no-error-content': [person.$load],
+ '': [person.$save, person.$delete],
+ }"
+ #default
+>
+ First Name: {{ person.firstName }}
+ Last Name: {{ person.lastName }}
+ Employer: {{ person.company.name }}
+</c-loader-status>
+Use c-loader-status to render a progress bar and any error messages, but don't use it to control content:
<c-loader-status :loaders="{'': [list.$load]}" />
+Wrap a save/submit button:
<c-loader-status
+ :loaders="{ 'no-loading-content': [person.$save] }"
+>
+ <button> Save </button>
+</c-loader-status>
+Hides the table before the first load has completed, or if loading the list encountered an error. Don't show the progress bar after we've already loaded the list for the first time (useful for loads that occur without user interaction, e.g. setInterval):
<c-loader-status
+ :loaders="{
+ 'no-secondary-progress no-initial-content no-error-content': [list.$load]
+ }"
+ #default
+>
+ <table>
+ <tr v-for="item in list.$items"> ... </tr>
+ </table>
+</c-loader-status>
+The available flags are as follows. All flags default to true, and may be prefixed with no- to set the flag to false instead of true. Multiple flags may be specified at once by delimiting them with spaces.
Flag | Description |
|---|---|
loading-content | Controls whether the default slot is rendered while any API caller is loading (i.e. when caller.isLoading === true). |
error-content | Controls whether the default slot is rendered while any API Caller is in an error state (i.e. when caller.wasSuccessful === false). |
initial-content | Controls whether the default slot is rendered while any API Caller has yet to receive a response for the first time (i.e. when caller.wasSuccessful === null). |
initial-progress | Controls whether the progress indicator is shown when an API Caller is loading for the very first time (i.e. when caller.wasSuccessful === null). |
secondary-progress | Controls whether the progress indicator is shown when an API Caller is loading any time after its first invocation (i.e. when caller.wasSuccessful !== null). |
<c-select-many-to-many :model="case" for="caseProducts" />
+<c-select-many-to-many
+ :model="case"
+ for="caseProducts"
+ dense
+ outlined
+/>
+<c-select-many-to-many
+ v-model="case.caseProducts"
+ for="Case.caseProducts"
+/>
+adding - Fired when a new item has been selected, but before the call to /save has completed.added - Fired when the call to /save has completed after adding a new item.deleting - Fired when an item has been removed, but before the call to /delete has completed.deleted - Fired when the call to /delete has completed after removing an item.<c-select-string-value
+ :model="person"
+ for="jobTitle"
+ method="getSuggestedJobTitles"
+/>
+<c-select-string-value
+ v-model="title"
+ label="Job Title"
+ for="Person"
+ method="getSuggestedJobTitles"
+/>
+class Person
+{
+ public int PersonId { get; set; }
+
+ public string JobTitle { get; set; }
+
+ [Coalesce]
+ public static async Task<ICollection<string>> GetSuggestedJobTitles(AppDbContext db, string search)
+ {
+ return await db.People
+ .Select(p => p.JobTitle)
+ .Distinct()
+ .Where(t => t.StartsWith(search))
+ .OrderBy(t => t)
+ .Take(100)
+ .ToListAsync()
+ }
+}
+<c-select-values
+ :model="post.setTags.args"
+ for="Post.methods.setTags.params.tagNames"
+/>
+Binding to a navigation property or foreign key of a model:
<c-select :model="person" for="company" />
+ <!-- OR: -->
+ <c-select :model="person" for="companyId" />
+Binding an arbitrary primary key value or an arbitrary object:
<!-- Binding a key: -->
+ <c-select for="Person" :key-value.sync="selectedPersonId" />
+
+ <!-- Binding an object: -->
+ <c-select for="Person" :object-value.sync="selectedPerson" />
+ <c-select for="Person" v-model="selectedPerson" />
+Examples of other props:
<c-select
+ for="Person"
+ v-model="selectedPerson"
+ :clearable="false"
+ preselect-first
+ :params="{ pageSize: 42, filter: { isActive: true } }"
+ :create="createMethods"
+ dense
+ outlined
+ color="pink"
+/>
+<!-- \`createMethods\` is defined in the docs of \`create\` below -->
+For example:
createMethods = {
+ getLabel(search: string, items: Person[]) {
+ const searchLower = search.toLowerCase();
+ if (items.some(a => a.name?.toLowerCase().indexOf(searchLower) == 0)) {
+ return false;
+ }
+ return search;
+ },
+ async getItem(search: string, label: string) {
+ const client = new PersonApiClient();
+ return (await client.addPersonByName(label)).data.object!;
+ }
+}
+<c-table :list="list" />
+A more complex example using more of the available options:
<c-table
+ :list="list"
+ :props="['firstName', 'lastName']"
+ :extra-headers="['Actions']"
+>
+ <template #item.append="{item}">
+ <td>
+ <v-btn
+ title="Edit"
+ text icon
+ :to="{name: 'edit-person', params: { id: item.$primaryKey }}"
+ >
+ <i class="fa fa-edit"></i>
+ </v-btn>
+ </td>
+ </template>
+</c-table>
+public class Person
+{
+ public int PersonId { get; set; }
+
+ [ClientValidation(IsRequired = true, AllowSave = true)]
+ public string FirstName { get; set; }
+
+ [ClientValidation(IsRequired = true, AllowSave = false, MinLength = 1, MaxLength = 100)]
+ public string LastName { get; set; }
+}
+If set to true, any client validation errors on the property will not prevent saving on the client. This includes all client-side validation, including null-checking for required foreign keys and other validations that are implicit. This also includes other explicit validation from System.ComponentModel.DataAnnotations annotations.
Instead, validation errors will be treated only as warnings, and will be available through the warnings: KnockoutValidationErrors property on the TypeScript ViewModel.
Note
Use AllowSave = true to allow partially complete data to still be saved, protecting your user from data loss upon navigation while still hinting to them that they are not done filling out data.
In Coalesce, all configuration of the code generation is done in a JSON file. This file is typically named coalesce.json and is typically placed in the solution root.
When the code generation is run by invoking dotnet coalesce, Coalesce will try to find a configuration file via the following means:
dotnet coalesce C:/Projects/MyProject/config.jsoncoalesce.jsoncoalesce.json is found. If such a file is never found, an error will be thrown.A full example of a coalesce.json file, along with an explanation of each property, is as follows:
{
+ "webProject": {
+ // Required: Path to the csproj of the web project. Path is relative to location of this coalesce.json file.
+ "projectFile": "src/Coalesce.Web/Coalesce.Web.csproj",
+
+ // Optional: Framework to use when evaluating & building dependencies.
+ // Not needed if your project only specifies a single framework - only required for multi-targeting projects.
+ "framework": "netcoreapp2.0",
+
+ // Optional: Build configuration to use when evaluating & building dependencies.
+ // Defaults to "Debug".
+ "configuration": "Debug",
+
+ // Optional: Override the namespace prefix for generated C# code.
+ // Defaults to MSBuild's \`$(RootNamespace)\` for the project.
+ "rootNamespace": "MyCompany.Coalesce.Web",
+ },
+
+ "dataProject": {
+ // Required: Path to the csproj of the data project. Path is relative to location of this coalesce.json file.
+ "projectFile": "src/Coalesce.Domain/Coalesce.Domain.csproj",
+
+ // Optional: Framework to use when evaluating & building dependencies.
+ // Not needed if your project only specifies a single framework - only required for multi-targeting projects.
+ "framework": "netstandard2.0",
+
+ // Optional: Build configuration to use when evaluating & building dependencies.
+ // Defaults to "Release".
+ "configuration": "Debug",
+ },
+
+ // The name of the root generator to use. Defaults to "Knockout".
+ // Available values are "Vue" and "Knockout".
+ "rootGenerator": "Vue",
+
+ // If set, specifies a list of whitelisted root type names that will restrict
+ // which types Coalesce will use for code generation.
+ // Root types are those that must be annotated with [Coalesce].
+ // Useful if want to segment a single data project into multiple web projects,
+ // or into different areas/directories within a single web project.
+ "rootTypesWhitelist": [
+ "MyDbContext", "MyCustomDto"
+ ],
+
+ "generatorConfig": {
+ // A set of objects keyed by generator name.
+ // Generator names may optionally be qualified by their full namespace.
+ // All generators are listed when running 'dotnet coalesce' with '--verbosity debug'.
+ // For example, "Views" or "IntelliTect.Coalesce.CodeGeneration.Knockout.Generators.Views".
+ "GeneratorName": {
+ // Optional: true if the generator should be disabled.
+ "disabled": true,
+ // Optional: Configures a path relative to the default output path for the generator
+ // where that generator's output should be placed instead.
+ "targetDirectory": "../DifferentFolder"
+ },
+ // Indentation for generated C# is configurable by type (API controllers, DTO classes and regular View controllers)
+ // It defaults to 4 spaces
+ "ApiController": {
+ "indentationSize": 2
+ },
+ "ClassDto": {
+ "indentationSize": 2
+ },
+ "ViewController" : {
+ "indentationSize": 2
+ }
+ }
+}
+There are a couple of extra options which are only available as CLI parameters to dotnet coalesce. These options do not affect the behavior of the code generation - only the behavior of the CLI itself.
--debug
When this flag is specified when running dotnet coalesce, Coalesce will wait up to 60 seconds for a debugger to be attached to its process before starting code generation.
-v|--verbosity <level>
Set the verbosity of the output. Options are trace, debug, information, warning, error, critical, and none.
public class Person
+{
+ public int PersonId { get; set; }
+ public string LastName { get; set; }
+
+ public string PictureHash { get; set; }
+
+ [Coalesce]
+ [ControllerAction(Method = HttpMethod.Get)]
+ public static long PersonCount(AppDbContext db, string lastNameStartsWith = "")
+ {
+ return db.People.Count(f => f.LastName.StartsWith(lastNameStartsWith));
+ }
+
+ [Coalesce]
+ [ControllerAction(HttpMethod.Get, VaryByProperty = nameof(PictureHash))]
+ public IFile GetPicture(AppDbContext db)
+ {
+ return new IntelliTect.Coalesce.Models.File(db.PersonPictures
+ .Where(x => x.PersonId == this.PersonId)
+ .Select(x => x.Content)
+ )
+ {
+ ContentType = "image/jpg",
+ };
+ }
+}
+The HTTP method to use on the generated API Controller.
Enum values are:
HttpMethod.Post Use the POST method.HttpMethod.Get Use the GET method.HttpMethod.Put Use the PUT method.HttpMethod.Delete Use the DELETE method.HttpMethod.Patch Use the PATCH method.[Controller(ApiRouted = false, ApiControllerSuffix = "Gen", ApiActionsProtected = true)]
+public class Person
+{
+ public int PersonId { get; set; }
+
+ ...
+}
+Determines whether or not a [Route] annotation will be placed on the generated API controller. Set to false to prevent emission of the [Route] attribute.
Use cases include:
If true, actions on the generated API controller will have an access modifier of protected instead of public.
In order to consume the generated API controller, you must inherit from the generated controller and override each desired generated action method via hiding (i.e. use public new ..., not public override ...).
Note
If you inherit from the generated API controllers and override their methods without setting ApiActionsProtected = true, all non-overridden actions from the generated controller will still be exposed as normal.
By default an API and View controller are both created. This allows for suppressing the creation of either or both of these.
[CreateController(view: false, api: true)]
+public class Person
+{
+ public int PersonId { get; set; }
+
+ ...
+}
+By default, each of your models that Coalesce exposes will expose the standard data source (IntelliTect.Coalesce.StandardDataSource<T, TContext>). This data source provides all the standard functionality one would expect - paging, sorting, searching, filtering, and so on. Each of these component pieces is implemented in one or more virtual methods, making the StandardDataSource a great place to start from when implementing your own data source. To suppress this behavior of always exposing the raw StandardDataSource, create your own custom data source and annotate it with [DefaultDataSource].
To implement your own custom data source, you simply need to define a class that implements IntelliTect.Coalesce.IDataSource<T>. To expose your data source to Coalesce, either place it as a nested class of the type T that you data source serves, or annotate it with the [Coalesce] attribute. Of course, the easiest way to create a data source that doesn't require you to re-engineer a great deal of logic would be to inherit from IntelliTect.Coalesce.StandardDataSource<T, TContext>, and then override only the parts that you need.
public class Person
+{
+ [DefaultDataSource]
+ public class IncludeFamily : StandardDataSource<Person, AppDbContext>
+ {
+ public IncludeFamily(CrudContext<AppDbContext> context) : base(context) { }
+
+ public override IQueryable<Person> GetQuery(IDataSourceParameters parameters)
+ => Db.People
+ .Where(f => User.IsInRole("Admin") || f.CreatedById == User.GetUserId())
+ .Include(f => f.Parents).ThenInclude(s => s.Parents)
+ .Include(f => f.Cousins).ThenInclude(s => s.Parents);
+ }
+}
+
+[Coalesce]
+public class NamesStartingWithA : StandardDataSource<Person, AppDbContext>
+{
+ public NamesStartingWithA(CrudContext<AppDbContext> context) : base(context) { }
+
+ public override IQueryable<Person> GetQuery(IDataSourceParameters parameters)
+ => Db.People.Include(f => f.Siblings).Where(f => f.FirstName.StartsWith("A"));
+}
+WARNING
If you create a custom data source that has custom logic for securing your data, be aware that the default implementation of StandardDataSource (or your custom default implementation - see below) is still exposed unless you annotate one of your custom data sources with [DefaultDataSource]. Doing so will replace the default data source with the annotated class for your type T.
All data sources are instantiated using dependency injection and your application's IServiceProvider. As a result, you can add whatever constructor parameters you desire to your data sources as long as a value for them can be resolved from your application's services. The single parameter to the StandardDataSource is resolved in this way - the CrudContext<TContext> contains the common set of objects most commonly used, including the DbContext and the ClaimsPrincipal representing the current user.
All methods on IDataSource<T> take a parameter that contains all the client-specified parameters for things paging, searching, sorting, and filtering information. Almost all virtual methods on StandardDataSource are also passed the relevant set of parameters.
On any data source that you create, you may add additional properties annotated with [Coalesce] that will then be exposed as parameters to the client. These property parameters are currently restricted to primitives (numeric types, strings) and dates (DateTime, DateTimeOffset). Property parameter primitives may be expanded to allow for more types in the future.
[Coalesce]
+public class NamesStartingWith : StandardDataSource<Person, AppDbContext>
+{
+ public NamesStartingWith(CrudContext<AppDbContext> context) : base(context) { }
+
+ [Coalesce]
+ public string StartsWith { get; set; }
+
+ public override IQueryable<Person> GetQuery(IDataSourceParameters parameters)
+ => Db.People.Include(f => f.Siblings)
+ .Where(f => string.IsNullOrWhitespace(StartsWith) ? true : f.FirstName.StartsWith(StartsWith));
+}
+The maximum page size that will be served. By default, client-specified page sizes will be clamped to this value. Override by setting a value in the constructor.
The standard data source contains 19 different methods which can be overridden in your derived class to control its behavior.
These methods often call one another, so overriding one method may cause some other method to no longer be called. The hierarchy of method calls, ignoring any logic or conditions contained within, is as follows:
GetMappedItemAsync
+ GetItemAsync
+ GetQueryAsync
+ GetQuery
+ GetIncludeTree
+ TransformResults
+
+GetMappedListAsync
+ GetListAsync
+ GetQueryAsync
+ GetQuery
+ ApplyListFiltering
+ ApplyListPropertyFilters
+ ApplyListPropertyFilter
+ ApplyListSearchTerm
+ GetListTotalCountAsync
+ ApplyListSorting
+ ApplyListClientSpecifiedSorting
+ ApplyListDefaultSorting
+ ApplyListPaging
+ GetIncludeTree
+ TrimListFields
+ TransformResults
+
+GetCountAsync
+ GetQueryAsync
+ GetQuery
+ ApplyListFiltering
+ ApplyListPropertyFilters
+ ApplyListPropertyFilter
+ ApplyListSearchTerm
+ GetListTotalCountAsync
+All of the methods outlined above can be overridden. A description of each of the non-interface inner methods is as follows:
`,7),Z=r("The method is the one that you will most commonly be override in order to implement custom query logic. The default implementation of GetQueryAsync simply calls GetQuery - be aware of this in cases of complex overrides/inheritance. From this method, you could:
.Include() and .ThenInclude()..IncludedSeparately() and .ThenIncluded().Performs trimming of the fields of the result set based on the parameters given to the data source. Can be overridden to forcibly disable this, override the behavior to always trim specific fields, or any other functionality desired.
You can, of course, create a custom base data source that all your custom implementations inherit from. But, what if you want to override the standard data source across your entire application, so that StandardDataSource<,> will never be instantiated? You can do that too!
Simply create a class that implements IEntityFrameworkDataSource<,> (the StandardDataSource<,> already does - feel free to inherit from it), then register it at application startup like so:
public class MyDataSource<T, TContext> : StandardDataSource<T, TContext>
+ where T : class
+ where TContext : DbContext
+{
+ public MyDataSource(CrudContext<TContext> context) : base(context)
+ {
+ }
+
+ ...
+}
+public void ConfigureServices(IServiceCollection services)
+{
+ services.AddCoalesce(b =>
+ {
+ b.AddContext<AppDbContext>();
+ b.UseDefaultDataSource(typeof(MyDataSource<,>));
+ });
+}
+Your custom data source must have the same generic type parameters - <T, TContext>. Otherwise, the Microsoft.Extensions.DependencyInjection service provider won't know how to inject it.
Specifies whether a DateTime type will have a date and a time, or only a date.
public class Person
+{
+ public int PersonId { get; set; }
+
+ [DateType(DateTypeAttribute.DateTypes.DateOnly)]
+ public DateTimeOffset? BirthDate { get; set; }
+}
+public class Person
+{
+ public int PersonId { get; set; }
+
+ public int DepartmentId { get; set; }
+
+ [DefaultOrderBy(FieldOrder = 0, FieldName = nameof(Department.Order))]
+ public Department Department { get; set; }
+
+ [DefaultOrderBy(FieldOrder = 1)]
+ public string LastName { get; set; }
+}
+public class Person
+{
+ public int PersonId { get; set; }
+
+ public int DepartmentId { get; set; }
+
+ [DefaultOrderBy(FieldOrder = 0, FieldName = nameof(Department.Order))]
+ public Department Department { get; set; }
+
+ [DefaultOrderBy(FieldOrder = 1)]
+ public string LastName { get; set; }
+}
+Server code:
public class Person
+{
+ // Don't include CreatedBy when editing - will be included for all other views
+ [DtoExcludes("Editor")]
+ public AppUser CreatedBy { get; set; }
+
+ // Only include the Person's Department when \`includes == "details"\` on the TypeScript ViewModel.
+ [DtoIncludes("details")]
+ public Department Department { get; set; }
+
+ // LastName will be included in all views
+ public string LastName { get; set; }
+}
+
+public class Department
+{
+ [DtoIncludes("details")]
+ public ICollection<Person> People { get; set; }
+}
+Client code:
`,4),F=s("div",{class:"language-typescript line-numbers-mode","data-ext":"ts"},[s("pre",{class:"shiki",style:{"background-color":"#1E1E1E"}},[s("code",null,[s("span",{class:"line"},[s("span",{style:{color:"#C586C0"}},"import"),s("span",{style:{color:"#D4D4D4"}}," { "),s("span",{style:{color:"#9CDCFE"}},"PersonListViewModel"),s("span",{style:{color:"#D4D4D4"}}," } "),s("span",{style:{color:"#C586C0"}},"from"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#CE9178"}},"'@/viewmodels.g'")]),e(` +`),s("span",{class:"line"}),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#569CD6"}},"const"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#4FC1FF"}},"personList"),s("span",{style:{color:"#D4D4D4"}}," = "),s("span",{style:{color:"#569CD6"}},"new"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#DCDCAA"}},"PersonListViewModel"),s("span",{style:{color:"#D4D4D4"}},"();")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#9CDCFE"}},"personList"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#9CDCFE"}},"$includes"),s("span",{style:{color:"#D4D4D4"}}," = "),s("span",{style:{color:"#CE9178"}},'"Editor"'),s("span",{style:{color:"#D4D4D4"}},";")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#C586C0"}},"await"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#9CDCFE"}},"personList"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#DCDCAA"}},"$load"),s("span",{style:{color:"#D4D4D4"}},"();")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#6A9955"}},"// Objects in personList.$items will not contain CreatedBy nor Department objects.")]),e(` +`),s("span",{class:"line"}),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#569CD6"}},"const"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#4FC1FF"}},"personList2"),s("span",{style:{color:"#D4D4D4"}}," = "),s("span",{style:{color:"#569CD6"}},"new"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#DCDCAA"}},"PersonListViewModel"),s("span",{style:{color:"#D4D4D4"}},"();")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#9CDCFE"}},"personList2"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#9CDCFE"}},"$includes"),s("span",{style:{color:"#D4D4D4"}}," = "),s("span",{style:{color:"#CE9178"}},'"details"'),s("span",{style:{color:"#D4D4D4"}},";")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#C586C0"}},"await"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#9CDCFE"}},"personList"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#DCDCAA"}},"$load"),s("span",{style:{color:"#D4D4D4"}},"();")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#6A9955"}},"// Objects in personList2.items will be allowed to contain both CreatedBy and Department objects. ")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#6A9955"}},"// Department will be allowed to include its other Person objects.")]),e(` +`),s("span",{class:"line"})])]),s("div",{class:"line-numbers","aria-hidden":"true"},[s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"})])],-1),L=s("div",{class:"language-typescript line-numbers-mode","data-ext":"ts"},[s("pre",{class:"shiki",style:{"background-color":"#1E1E1E"}},[s("code",null,[s("span",{class:"line"},[s("span",{style:{color:"#569CD6"}},"var"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#9CDCFE"}},"personList"),s("span",{style:{color:"#D4D4D4"}}," = "),s("span",{style:{color:"#569CD6"}},"new"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#9CDCFE"}},"ListViewModels"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#DCDCAA"}},"PersonList"),s("span",{style:{color:"#D4D4D4"}},"();")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#9CDCFE"}},"personList"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#9CDCFE"}},"includes"),s("span",{style:{color:"#D4D4D4"}}," = "),s("span",{style:{color:"#CE9178"}},'"Editor"'),s("span",{style:{color:"#D4D4D4"}},";")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#9CDCFE"}},"personList"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#DCDCAA"}},"load"),s("span",{style:{color:"#D4D4D4"}},"(() "),s("span",{style:{color:"#569CD6"}},"=>"),s("span",{style:{color:"#D4D4D4"}}," {")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#6A9955"}},"// objects in personList.items will not contain CreatedBy nor Department objects.")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#D4D4D4"}},"});")]),e(` +`),s("span",{class:"line"}),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#569CD6"}},"var"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#9CDCFE"}},"personList2"),s("span",{style:{color:"#D4D4D4"}}," = "),s("span",{style:{color:"#569CD6"}},"new"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#9CDCFE"}},"ListViewModels"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#DCDCAA"}},"PersonList"),s("span",{style:{color:"#D4D4D4"}},"();")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#9CDCFE"}},"personList2"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#9CDCFE"}},"includes"),s("span",{style:{color:"#D4D4D4"}}," = "),s("span",{style:{color:"#CE9178"}},'"details"'),s("span",{style:{color:"#D4D4D4"}},";")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#9CDCFE"}},"personList2"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#DCDCAA"}},"load"),s("span",{style:{color:"#D4D4D4"}},"(() "),s("span",{style:{color:"#569CD6"}},"=>"),s("span",{style:{color:"#D4D4D4"}}," {")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#6A9955"}},"// objects in personList2.items will be allowed to contain both CreatedBy and Department objects. Department will be allowed to include its other Person objects.")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#D4D4D4"}},"});")]),e(` +`),s("span",{class:"line"})])]),s("div",{class:"line-numbers","aria-hidden":"true"},[s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"})])],-1),x=s("h2",{id:"properties",tabindex:"-1"},[s("a",{class:"header-anchor",href:"#properties","aria-hidden":"true"},"#"),e(" Properties")],-1),B=s("code",null,"includes",-1),P=t("For DtoIncludes, this will be the values of includes for which this property will be allowed to be serialized and sent to the client.
For DtoExcludes, this will be the values of includes for which this property will not be serialized and sent to the client.
Next, ensure that one property is annotated with [Key] so that Coalesce can know the primary key of your DTO in order to perform database lookups and keep track of your object uniquely in the client-side TypeScript.
Now, populate the required MapTo and MapFrom methods with code for mapping from and to your DTO, respectively (the methods are named with respect to the underlying entity, not the DTO). Most properties probably map one-to-one in both directions, but you probably created a DTO because you wanted some sort of custom mapping - say, mapping a collection on your entity with a comma-delimited string on the DTO. This is also the place to perform any user-based, role-based, property-level security. You can access the current user on the IMappingContext object.
[Coalesce]
+public class CaseDto : IClassDto<Case>
+{
+ [Key]
+ public int CaseId { get; set; }
+
+ public string Title { get; set; }
+
+ [Read]
+ public string AssignedToName { get; set; }
+
+ public void MapTo(Case obj, IMappingContext context)
+ {
+ obj.Title = Title;
+ }
+
+ public void MapFrom(Case obj, IMappingContext context = null, IncludeTree tree = null)
+ {
+ CaseId = obj.CaseKey;
+ Title = obj.Title;
+ if (obj.AssignedTo != null)
+ {
+ AssignedToName = obj.AssignedTo.Name;
+ }
+ }
+}
+using IntelliTect.Coalesce.Mapping;
+
+[Coalesce]
+public class CaseDto : IClassDto<Case>
+{
+ public int ProductId { get; set; }
+ public Product Product { get; set; }
+ ...
+
+ public void MapFrom(Case obj, IMappingContext context = null, IncludeTree tree = null)
+ {
+ ProductId = obj.ProductId;
+
+ if (tree == null || tree[nameof(this.Product)] != null)
+ Product = Mapper.MapToDto<Product, ProductDtoGen>(obj.Product, context, tree?[nameof(this.Product)]
+ ...
+ }
+}
+As a nested class of the DTO. The relationship between your data source or behaviors and your DTO will be picked up automatically.
[Coalesce]
+public class CaseDto : IClassDto<Case>
+{
+ [Key]
+ public int CaseId { get; set; }
+
+ public string Title { get; set; }
+
+ ...
+
+ public class MyCaseDtoSource : StandardDataSource<Case, AppDbContext>
+ {
+ ...
+ }
+}
+With a [DeclaredFor] attribute that references the DTO type:
[Coalesce]
+public class CaseDto : IClassDto<Case>
+{
+ [Key]
+ public int CaseId { get; set; }
+
+ public string Title { get; set; }
+
+ ...
+}
+
+[Coalesce, DeclaredFor(typeof(CaseDto))]
+public class MyCaseDtoSource : StandardDataSource<Case, AppDbContext>
+{
+ ...
+}
+[Coalesce, DeclaredFor(typeof(CaseDto))]
+public class CaseDtoSource : ProjectedDtoDataSource<Case, CaseDto, AppDbContext>
+{
+ public CaseDtoSource(CrudContext<AppDbContext> context) : base(context) { }
+
+ public override IQueryable<CaseDto> ApplyProjection(IQueryable<Case> query, IDataSourceParameters parameters)
+ {
+ return query.Select(c => new CaseDto
+ {
+ CaseId = c.CaseKey,
+ Title = c.Title,
+ AssignedToName = c.AssignedTo == null ? null : c.AssignedTo.Name
+ });
+ }
+}
+Once you've got a solid data model in place, its time to start customizing the way that Coalesce will read your data, as well as the way that it will handle your data when processing creates, updates, and deletes.
To define data sources and behaviors for Standalone Entities, it is recommended you inherit from StandardDataSource<T> and StandardBehaviors<T>, respectively. For example:
[Coalesce, StandaloneEntity]
+public class StandaloneExample
+{
+ public int Id { get; set; }
+
+ [Search(SearchMethod = SearchAttribute.SearchMethods.Contains), ListText]
+ public string Name { get; set; } = "";
+
+ [DefaultOrderBy]
+ public DateTimeOffset Date { get; set; }
+
+ private static int nextId = 0;
+ private static ConcurrentDictionary<int, StandaloneExample> backingStore = new ConcurrentDictionary<int, StandaloneExample>();
+
+ public class DefaultSource : StandardDataSource<StandaloneExample>
+ {
+ public DefaultSource(CrudContext context) : base(context) { }
+
+ public override Task<IQueryable<StandaloneExample>> GetQueryAsync(IDataSourceParameters parameters)
+ => Task.FromResult(backingStore.Values.AsQueryable());
+ }
+
+ public class Behaviors : StandardBehaviors<StandaloneExample>
+ {
+ public Behaviors(CrudContext context) : base(context) { }
+
+ public override Task ExecuteDeleteAsync(StandaloneExample item)
+ {
+ backingStore.TryRemove(item.Id, out _);
+ return Task.CompletedTask;
+ }
+
+ public override Task ExecuteSaveAsync(SaveKind kind, StandaloneExample? oldItem, StandaloneExample item)
+ {
+ if (kind == SaveKind.Create)
+ {
+ item.Id = Interlocked.Increment(ref nextId);
+ backingStore.TryAdd(item.Id, item);
+ }
+ else
+ {
+ backingStore.TryRemove(item.Id, out _);
+ backingStore.TryAdd(item.Id, item);
+ }
+ return Task.CompletedTask;
+ }
+ }
+}
+The above example is admittedly contrived, as it is unlikely that you would be using an in-memory collection as a data persistence mechanism. A more likely real-world scenario would be to inject an interface to some other data store. Data Source and Behavior classes are instantiated using your application's service provider, so any registered service can be injected.
`,3);function k(T,I){const t=p("ExternalLinkIcon"),o=p("router-link"),l=p("RouterLink");return D(),i("div",null,[y,a("p",null,[s("Models are the core business objects of your application - they serve as the fundamental representation of data in your application. The design of your models is very important. In "),a("a",u,[s("Entity Framework Core"),n(t)]),s(" (EF), data models are just Plain Old CLR Objects (POCOs).")]),a("nav",C,[a("ul",null,[a("li",null,[n(o,{to:"#building-a-data-model"},{default:e(()=>[s("Building a Data Model")]),_:1}),a("ul",null,[a("li",null,[n(o,{to:"#properties"},{default:e(()=>[s("Properties")]),_:1})]),a("li",null,[n(o,{to:"#attributes"},{default:e(()=>[s("Attributes")]),_:1})]),a("li",null,[n(o,{to:"#methods"},{default:e(()=>[s("Methods")]),_:1})])])]),a("li",null,[n(o,{to:"#customizing-crud-operations"},{default:e(()=>[s("Customizing CRUD Operations")]),_:1}),a("ul",null,[a("li",null,[n(o,{to:"#data-sources"},{default:e(()=>[s("Data Sources")]),_:1})]),a("li",null,[n(o,{to:"#behaviors"},{default:e(()=>[s("Behaviors")]),_:1})])])]),a("li",null,[n(o,{to:"#standalone-non-ef-entities"},{default:e(()=>[s("Standalone (non-EF) Entities")]),_:1})])])]),m,a("p",null,[s("To start building your data model that Coalesce will generate code for, follow the best practices for "),a("a",h,[s("EF Core"),n(t)]),s(". Guidance on this topic is available in abundance in the "),a("a",v,[s("Entity Framework Core documentation"),n(t)]),s(".")]),b,E,f,a("p",null,[s("Read "),n(l,{to:"/modeling/model-components/properties.html"},{default:e(()=>[s("Properties")]),_:1}),s(" for an outline of the different types of properties that you may place on your models and the code that Coalesce will generate for each of them.")]),g,_,a("p",null,[s("Read "),n(l,{to:"/modeling/model-components/attributes.html"},{default:e(()=>[s("Attributes")]),_:1}),s(" to learn more.")]),F,a("p",null,[s("You can place both static and interface methods on your model classes. Any public methods annotated with "),n(l,{to:"/modeling/model-components/attributes/coalesce.html"},{default:e(()=>[s("[Coalesce]")]),_:1}),s(" will have a generated API endpoint and corresponding generated TypeScript members for calling this API endpoint. Read "),n(l,{to:"/modeling/model-components/methods.html"},{default:e(()=>[s("Methods")]),_:1}),s(" to learn more.")]),B,a("p",null,[s("The method by which you can control what data the users of your application can access through Coalesce's generated APIs is by creating custom data sources. These are classes that allow complete control over the way that data is retrieved from your database and provided to clients. Read "),n(l,{to:"/modeling/model-components/data-sources.html"},{default:e(()=>[s("Data Sources")]),_:1}),s(" to learn more.")]),S,a("p",null,[s("Behaviors in Coalesce are to mutating data as data sources are to reading data. Defining a behaviors class for a model allows complete control over the way that Coalesce will create, update, and delete your application's data in response to requests made through its generated API. Read "),n(l,{to:"/modeling/model-components/behaviors.html"},{default:e(()=>[s("Behaviors")]),_:1}),s(" to learn more.")]),A,x,a("p",null,[s("For these types, you must define at least one custom "),n(l,{to:"/modeling/model-components/data-sources.html"},{default:e(()=>[s("Data Source")]),_:1}),s(", and optionally a "),n(l,{to:"/modeling/model-components/behaviors.html"},{default:e(()=>[s("Behaviors")]),_:1}),s(" class as well. If no behaviors are defined, the type is implicitly read-only, equivalent to turning off create/edit/delete via the "),n(l,{to:"/modeling/model-components/attributes/security-attribute.html"},{default:e(()=>[s("Security Attributes")]),_:1}),s(".")]),w])}const P=c(d,[["render",k],["__file","entities.html.vue"]]);export{P as default}; diff --git a/assets/execute.html.29138de0.js b/assets/execute.html.29138de0.js new file mode 100644 index 000000000..d1e724bb8 --- /dev/null +++ b/assets/execute.html.29138de0.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-1e992cc4","path":"/modeling/model-components/attributes/execute.html","title":"[Execute]","lang":"en-US","frontmatter":{},"excerpt":"","headers":[{"level":2,"title":"Example Usage","slug":"example-usage","link":"#example-usage","children":[]},{"level":2,"title":"Properties","slug":"properties","link":"#properties","children":[]}],"git":{"updatedTime":1680124405000},"filePathRelative":"modeling/model-components/attributes/execute.md"}');export{e as data}; diff --git a/assets/execute.html.3ada74ae.js b/assets/execute.html.3ada74ae.js new file mode 100644 index 000000000..f923bad3b --- /dev/null +++ b/assets/execute.html.3ada74ae.js @@ -0,0 +1,12 @@ +import{_ as i,y as c,z as p,X as e,B as a,Q as s,$ as l,a5 as r,P as t}from"./framework.fe9a73df.js";const d={},u=e("h1",{id:"execute",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#execute","aria-hidden":"true"},"#"),a(" [Execute]")],-1),D=e("p",null,"Controls permissions for executing of a static or instance method through the API.",-1),h=r(`public class Person
+{
+ public int PersonId { get; set; }
+
+ [Coalesce, Execute(Roles = "Payroll,HR")]
+ public void GiveRaise(int centsPerHour) {
+ ...
+ }
+
+ ...
+}
+The level of access to allow for the action for the method.
Enum values are:
SecurityPermissionLevels.AllowAll Allow all users to perform the action for the attribute, including users who are not authenticated at all.SecurityPermissionLevels.AllowAuthorized Allow only users who are members of the roles specified on the attribute to perform the action. If no roles are specified on the attribute, then all authenticated users are allowed (no anonymous access).SecurityPermissionLevels.DenyAll Deny the action to all users, regardless of authentication status or authorization level. If DenyAll is used, no API endpoint for the action will be generated.For example, in the following scenario, the following classes are considered as external types:
PluginMetadata, exposed through a getter-only property on ApplicationPlugin.PluginResult, exposed through a method return on ApplicationPlugin.PluginHandler is not because it not exposed by the model, neither directly nor through any of the other external types.
public class AppDbContext : DbContext {
+ public DbSet<Application> Applications { get; set; }
+ public DbSet<ApplicationPlugin> ApplicationPlugins { get; set; }
+}
+
+public class Application {
+ public int ApplicationId { get; set; }
+ public string Name { get; set; }
+ public ICollection<ApplicationPlugin> Plugins { get; set; }
+}
+
+public class ApplicationPlugin {
+ public int ApplicationPluginId { get; set; }
+ public int ApplicationId { get; set; }
+ public Application Application { get; set; }
+
+ public string TypeName { get; set; }
+
+ private PluginHandler GetInstance() =>
+ ((PluginHandler)Activator.CreateInstance(Type.GetType(TypeName)));
+
+ public PluginMetadata Metadata => GetInstance().GetMetadata();
+
+ public PluginResult Invoke(string action, string data) => GetInstance().Invoke(Application, action, data);
+}
+
+public abstract class PluginHandler {
+ public abstract PluginMetadata GetMetadata();
+ public abstract PluginResult Invoke(Application app, string action, string data);
+}
+
+public abstract class PluginMetadata {
+ public bool Name { get; set; }
+ public string Version { get; set; }
+ public ICollection<string> Actions { get; set; }
+}
+
+public abstract class PluginResult {
+ public bool Success { get; set; }
+ public string Message { get; set; }
+}
+Coalesce's code generation is ran via a dotnet CLI tool, dotnet coalesce. In order to invoke this tool, you must have the appropriate references to the package that provides it in your .csproj file:
<Project Sdk="Microsoft.NET.Sdk.Web">
+ <PropertyGroup>
+ <TargetFramework>net7.0</TargetFramework>
+
+ <!-- Necessary to use DotNetCliToolReference with modern framework versions -->
+ <DotnetCliToolTargetFramework>net7.0</DotnetCliToolTargetFramework>
+ </PropertyGroup>
+
+ ...
+
+ <ItemGroup>
+ <PackageReference Include="IntelliTect.Coalesce" Version="..." />
+ </ItemGroup>
+
+ <ItemGroup>
+ <DotNetCliToolReference Include="IntelliTect.Coalesce.Tools" Version="..." />
+ </ItemGroup>
+</Project>
+There are a couple of extra options which are only available as CLI parameters to dotnet coalesce. These options do not affect the behavior of the code generation - only the behavior of the CLI itself.
--debug - When this flag is specified when running dotnet coalesce, Coalesce will wait for a debugger to be attached to its process before starting code generation.
-v|--verbosity <level> - Set the verbosity of the output. Options are trace, debug, information, warning, error, critical, and none.
Coalesce will generate a full vertical stack of code for you:
Run dotnet ef migrations add Init (Init can be any name) in the data project to create an initial database migration.
Run Coalesce's code generation by either:
dotnet coalesce in the web project's root directorycoalesce npm script (Vue) or gulp task (Knockout) in the Task Runner ExplorerThe quickest and easiest way to create a new Coalesce Knockout application is to use the dotnet new template. In your favorite shell:
dotnet new install IntelliTect.Coalesce.KnockoutJS.Template
+dotnet new coalesceko
+Run dotnet ef migrations add Init (Init can be any name) in the data project to create an initial database migration.
Run Coalesce's code generation by either:
dotnet coalesce in the web project's root directorycoalesce npm script (Vue) or gulp task (Knockout) in the Task Runner Explorernamespace MyApplication.Data.Models
+{
+ public class Person
+ {
+ public int PersonId { get; set; }
+ public string Name { get; set; }
+ public DateTimeOffset? BirthDate { get; set; }
+ }
+}
+We can create a details page for a Person by creating:
A controller in src/MyApplication.Web/Controllers/PersonController.cs:
namespace MyApplication.Web.Controllers
+{
+ public partial class PersonController
+ {
+ public IActionResult Details() => View();
+ }
+}
+A view in src/MyApplication.Web/Views/Person/Details.cshtml:
<h1>Person Details</h1>
+
+<div data-bind="with: person">
+ <dl class="dl-horizontal">
+ <dt>Name </dt>
+ <dd data-bind="text: name"></dd>
+
+ <dt>Date of Birth </dt>
+ <dd data-bind="moment: birthDate, format: 'MM/DD/YYYY hh:mm a'"></dd>
+ </dl>
+</div>
+
+@section Scripts
+{
+<script src="~/js/person.details.js"></script>
+<script>
+ $(function () {
+ var vm = new MyApplication.PersonDetails();
+ ko.applyBindings(vm);
+ vm.load();
+ });
+</script>
+}
+And a script in src/MyApplication.Web/Scripts/person.details.ts:
/// <reference path="viewmodels.generated.d.ts" />
+
+module MyApplication {
+ export class PersonDetails {
+ public person = new ViewModels.Person();
+
+ load() {
+ var id = Coalesce.Utilities.GetUrlParameter("id");
+ if (id != null && id != '') {
+ this.person.load(id);
+ }
+ }
+ }
+}
+With these pieces in place, we now have a functioning page that will display details about a person. We can start up the application and navigate to /Person/Details?id=1 (assuming a person with ID 1 exists - if not, navigate to /Person/Table and create one).
The quickest and easiest way to create a new Coalesce Vue application is to use the dotnet new template. In your favorite shell:
mkdir MyCompany.MyProject
+cd MyCompany.MyProject
+dotnet new install IntelliTect.Coalesce.Vue.Template
+dotnet new coalescevue
+cd *.Web
+npm ci
+The structure of the Web project follows the conventions of both ASP.NET Core and Vite. The Vue-specific folders are as follows:
/src - Files that should be compiled into your application. CSS/SCSS, TypeScript, Vue SFCs, and so on./public - Static assets that should be served as files. Includes index.html, the root document of the application./wwwroot - Target for compiled output.During development, no special tooling is required to build your frontend code. Coalesce's UseViteDevelopmentServer in ASP.NET Core will take care of that automatically when the application starts. Just make sure NPM packages have been installed (npm ci).
At this point, you can open up the newly-created solution in Visual Studio and run your application. However, your application won't do much without a data model, so you will probably want to do the following before running:
',5),_=n("code",null,"DbSet<>",-1),w=n("code",null,"AppDbContext",-1),E=n("code",null,"ApplicationUser",-1),k=o("Run dotnet ef migrations add Init (Init can be any name) in the data project to create an initial database migration.
Run Coalesce's code generation by either:
dotnet coalesce in the web project's root directorycoalesce npm script (Vue) or gulp task (Knockout) in the Task Runner Explorernamespace MyApplication.Data.Models
+{
+ public class Person
+ {
+ public int PersonId { get; set; }
+ public string Name { get; set; }
+ public DateTimeOffset? BirthDate { get; set; }
+ }
+}
+<template>
+ <dl>
+ <dt>Name</dt>
+ <dd>
+ <c-display :model="person" for="name" />
+ </dd>
+
+ <dt>Date of Birth</dt>
+ <dd>
+ <c-display :model="person" for="birthDate" format="M/d/yyyy" />
+ </dd>
+ </dl>
+</template>
+
+<script setup lang="ts">
+import { PersonViewModel } from "@/viewmodels.g";
+
+const props = defineProps<{ id: number }>();
+const person = new PersonViewModel();
+
+person.$load(props.id);
+</script>
+We then need to add route to this new view. In MyApplication.Web/src/router.ts, add a new item to the routes array:
// In the \`routes\` array, add the following item:
+{
+ path: '/person/:id',
+ name: 'person-details',
+ component: () => import('@/views/person-details.vue'),
+ props: route => ({ id: +route.params.id }),
+},
+With these pieces in place, we now have a functioning page that will display details about a person. We can start up the application (or, if it was already running, refresh the page) and navigate to /person/1 (assuming a person with ID 1 exists - if not, navigate to /admin/Person and create one).
public class Person
+{
+ public int PersonId { get; set; }
+
+ [Hidden(HiddenAttribute.Areas.All)]
+ public int? IncomeLevelId { get; set; }
+}
+The areas in which the property should be hidden.
Enum values are:
HiddenAttribute.Areas.None Hide from no generated views. Primary and Foreign keys are hidden by default - setting this value explicitly can override this default behavior.HiddenAttribute.Areas.All Hide from all generated viewsHiddenAttribute.Areas.List Hide from generated list views only (Knockout Table/Cards, Vue c-admin-table)HiddenAttribute.Areas.Edit Hide from generated editor only (Knockout CreateEdit, Vue c-admin-editor)Coalesce is a framework based on ASP.NET Core that makes rapidly building awesome websites much easier. A project that would take a 3 months to complete now takes 1 month. We built this because we got tired of writing all the boiler plate code that is necessary to make amazing sites.
It does this by allowing developers to focus on the creative aspects of the solution. The more mundane parts are generated automatically. This means that you get to focus on data modeling, business logic and front-end development. Coalesce does the plumbing.
Here is a typical workflow
Coalesce was designed to create line-of-business applications. It provides a more customizable and maintainable alternative to off the shelf customizable products like SharePoint and Sales Force.
You should consider using Coalesce if your project:
Coalesce is specifically designed to meet the needs of web developers. However, there are lots of ways to do this. We have made a set of decisions which we believe makes for a great development experience
After you create your classes and the EF data context, Coalesce uses this information to generate code. When the Coalesce CLI (command line interface) is run, the following things happen:
Here are a few things we have found helpful when using Coalesce
In 2014 several developers from IntelliTect got together to talk about our craft. There were lots of different backgrounds, but recently we had all been writing web code in C#. We discussed things we enjoyed and things we dreaded. There was an underlying commitment to providing customers with great sites at a reasonable cost. However, those things often seemed at odds because of the complexity of web development.
For example, writing AJAX drop down lists with type ahead takes quite a bit of plumbing. Layer onto this the need for view models that allow for validation and saving as the user moves from field to field. We absolutely want want to deliver visually pleasing sites with complex UI paradigms. However, all this excellence adds up: complex view models, complex APIs, data binding, ugh.
Then there is that sinking feeling when you have to add another class to the project knowing that you are going to need to create all this yet again and you consider taking short cuts. Will there really be more than about 20 items in this table, maybe we don't need paging. Inevitably, the customer asks for admin screens. We consider giving them SQL Server Management Console and then consider using the built in ASP.NET list and editor pages. Better sense wins out and we end up spending two weeks building slick admin pages with paging, searching, sorting, etc.
That evening we starting talking about the things we loved to do:
We also lists things that we didn't enjoy
Over the next few months we talked about this issue, but couldn't find the right abstraction. We talked about other solutions that solve parts of the problem and considered putting together something from several pieces. Nothing felt unified and we ended up with leaky abstractions. We needed some way to divide the problem so that we could build the fun stuff and have something generate the boring stuff. This solution needed to be robust enough to satisfy our customer's needs and also be of use to developers without their needing to know the inner workings of the system.
What if we could build the models and business logic and have a tool build everything except the UI? There are great tools like Entity Framework for modeling and good tooling for minimizing duplicate code in user interfaces. And so Coalesce was born, a tool that would bring together the backend and front end development. '
Coalesce takes Entity Framework Core models and builds controllers, TypeScript view models, and admin pages automatically. These are built in a general way so that they can be applied to many different scenarios. There will always be pages that need to be written by hand and we intentionally don't support many edge cases in order to keep things simple. There is nothing wrong with building something by hand.
We have been using Coalesce for many of our web projects with great success. Typically, a project is taking about 1/3 the time it was taking before once developers ramp up. The ramp up on Coalesce has typically been a couple of days. We realized that in order for Coalesce to be useful it need to be intuitive to use and easy to understand. We have intentionally used simple paradigms to minimize the learning curve. There are complex bits, but hopefully, those are well hidden and documented as needed.
',37),n=[s];function l(r,d){return t(),i("div",null,n)}const c=e(o,[["render",l],["__file","history.html.vue"]]);export{c as default}; diff --git a/assets/history.html.f58a3d69.js b/assets/history.html.f58a3d69.js new file mode 100644 index 000000000..700695fa2 --- /dev/null +++ b/assets/history.html.f58a3d69.js @@ -0,0 +1 @@ +const e=JSON.parse(`{"key":"v-a7d34384","path":"/history.html","title":"Welcome to Coalesce's documentation!","lang":"en-US","frontmatter":{},"excerpt":"","headers":[{"level":2,"title":"Core Features","slug":"core-features","link":"#core-features","children":[]},{"level":2,"title":"Is Coalesce for Everyone and Every Project?","slug":"is-coalesce-for-everyone-and-every-project","link":"#is-coalesce-for-everyone-and-every-project","children":[]},{"level":2,"title":"Design Decisions and Limitations","slug":"design-decisions-and-limitations","link":"#design-decisions-and-limitations","children":[]},{"level":2,"title":"How Does it Work?","slug":"how-does-it-work","link":"#how-does-it-work","children":[]},{"level":2,"title":"General Guidance","slug":"general-guidance","link":"#general-guidance","children":[]},{"level":2,"title":"Why Coalesce","slug":"why-coalesce","link":"#why-coalesce","children":[]},{"level":2,"title":"The Problem","slug":"the-problem","link":"#the-problem","children":[]},{"level":2,"title":"The Path to the Solution","slug":"the-path-to-the-solution","link":"#the-path-to-the-solution","children":[]},{"level":2,"title":"Our Solution","slug":"our-solution","link":"#our-solution","children":[]},{"level":2,"title":"How has it Worked?","slug":"how-has-it-worked","link":"#how-has-it-worked","children":[]}],"git":{"updatedTime":1652390840000},"filePathRelative":"history.md"}`);export{e as data}; diff --git a/assets/include-tree.html.5aed11ea.js b/assets/include-tree.html.5aed11ea.js new file mode 100644 index 000000000..fc2d7c4de --- /dev/null +++ b/assets/include-tree.html.5aed11ea.js @@ -0,0 +1,120 @@ +import{_ as r,y as D,z as i,X as s,Q as a,$ as n,B as e,a5 as p,P as t}from"./framework.fe9a73df.js";const y={},d=s("h1",{id:"include-tree",tabindex:"-1"},[s("a",{class:"header-anchor",href:"#include-tree","aria-hidden":"true"},"#"),e(" Include Tree")],-1),u=s("p",null,[e("When Coalesce maps from the your POCO objects that are returned from EF Core queries, it will follow a structure called an "),s("code",null,"IncludeTree"),e(" to determine what relationships to follow and how deep to go in re-creating that structure in the mapped DTOs.")],-1),C={class:"table-of-contents"},m=p(`Without an IncludeTree present, Coalesce will map the entire object graph that is reachable from the root object. This can often spiral out of control if there aren't any rules defining how far to go while turning this graph into a tree.
For example, suppose you had the following model with a many-to-many relationship (key properties omitted for brevity):
public class Employee
+{
+ [ManyToMany("Projects")]
+ public ICollection<EmployeeProject> EmployeeProjects { get; set; }
+
+ public static IQueryable<Employee> WithProjectsAndMembers(AppDbContext db, ClaimsPrincipal user)
+ {
+ // Load all projects of an employee, as well as all members of those projects.
+ return db.Employees
+ .Include(e => e.EmployeeProjects)
+ .ThenInclude(ep => ep.Project.EmployeeProjects)
+ .ThenInclude(ep => ep.Employee);
+ }
+}
+
+public class Project
+{
+ [ManyToMany("Employees")]
+ public ICollection<EmployeeProject> EmployeeProjects { get; set; }
+}
+
+public class EmployeeProject
+{
+ public Employee Employee { get; set; }
+ public Project Project { get; set; }
+}
+Now, imagine that you have five employees and five projects, with every employee being a member of every project (i.e. there are 25 EmployeeProject rows).
Your client code makes a call to the Coalesce-generated API to load Employee #1 using the custom data source:
`,6),h=s("div",{class:"language-typescript line-numbers-mode","data-ext":"ts"},[s("pre",{class:"shiki",style:{"background-color":"#1E1E1E"}},[s("code",null,[s("span",{class:"line"},[s("span",{style:{color:"#C586C0"}},"import"),s("span",{style:{color:"#D4D4D4"}}," { "),s("span",{style:{color:"#9CDCFE"}},"Employee"),s("span",{style:{color:"#D4D4D4"}}," } "),s("span",{style:{color:"#C586C0"}},"from"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#CE9178"}},"'@/viewmodels.g'")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#C586C0"}},"import"),s("span",{style:{color:"#D4D4D4"}}," { "),s("span",{style:{color:"#9CDCFE"}},"EmployeeViewModel"),s("span",{style:{color:"#D4D4D4"}}," } "),s("span",{style:{color:"#C586C0"}},"from"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#CE9178"}},"'@/viewmodels.g'")]),e(` +`),s("span",{class:"line"}),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#569CD6"}},"var"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#9CDCFE"}},"employee"),s("span",{style:{color:"#D4D4D4"}}," = "),s("span",{style:{color:"#569CD6"}},"new"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#DCDCAA"}},"EmployeeViewModel"),s("span",{style:{color:"#D4D4D4"}},"();")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#9CDCFE"}},"employee"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#9CDCFE"}},"$dataSource"),s("span",{style:{color:"#D4D4D4"}}," = "),s("span",{style:{color:"#569CD6"}},"new"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#9CDCFE"}},"Employee"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#9CDCFE"}},"DataSources"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#DCDCAA"}},"WithProjectsAndMembers"),s("span",{style:{color:"#D4D4D4"}},"();")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#9CDCFE"}},"employee"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#DCDCAA"}},"$load"),s("span",{style:{color:"#D4D4D4"}},"("),s("span",{style:{color:"#B5CEA8"}},"1"),s("span",{style:{color:"#D4D4D4"}},");")]),e(` +`),s("span",{class:"line"})])]),s("div",{class:"line-numbers","aria-hidden":"true"},[s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"})])],-1),E=s("div",{class:"language-typescript line-numbers-mode","data-ext":"ts"},[s("pre",{class:"shiki",style:{"background-color":"#1E1E1E"}},[s("code",null,[s("span",{class:"line"},[s("span",{style:{color:"#569CD6"}},"var"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#9CDCFE"}},"employee"),s("span",{style:{color:"#D4D4D4"}}," = "),s("span",{style:{color:"#569CD6"}},"new"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#9CDCFE"}},"ViewModels"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#DCDCAA"}},"Employee"),s("span",{style:{color:"#D4D4D4"}},"();")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#9CDCFE"}},"employee"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#9CDCFE"}},"dataSource"),s("span",{style:{color:"#D4D4D4"}}," = "),s("span",{style:{color:"#569CD6"}},"new"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#9CDCFE"}},"employee"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#9CDCFE"}},"dataSources"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#DCDCAA"}},"WithProjectsAndMembers"),s("span",{style:{color:"#D4D4D4"}},"();")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#9CDCFE"}},"employee"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#DCDCAA"}},"load"),s("span",{style:{color:"#D4D4D4"}},"("),s("span",{style:{color:"#B5CEA8"}},"1"),s("span",{style:{color:"#D4D4D4"}},");")]),e(` +`),s("span",{class:"line"})])]),s("div",{class:"line-numbers","aria-hidden":"true"},[s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"})])],-1),v=s("p",null,[e("If you're already familiar with the fact that an "),s("code",null,"IncludeTree"),e(" is implicitly created in this scenario, then imagine for a moment that this is not the case (if you're not familiar with this fact, then keep reading!).")],-1),b=s("code",null,"DbContext",-1),F=p(`To map these objects to DTOs, we start with the root (employee #1) and expand outward from there until the entire object graph has been faithfully re-created with DTO objects, including all navigation properties.
The root DTO object (employee #1) then eventually is passed to the JSON serializer by ASP.NET Core to formulate the response to the request. As the object is serialized to JSON, the only objects that are not serialized are those that were already serialized as an ancestor of itself. What this ultimately means is that the structure of the serialized JSON with our example scenario ends up following a pattern like this (the vast majority of items have been omitted):
Employee#1
+ EmployeeProject#1
+ Project#1
+ EmployeeProject#6
+ Employee#2
+ EmployeeProject#7
+ Project#2
+ ... continues down through all remaining employees and projects.
+ ...
+ EmployeeProject#11
+ Employee#3
+ ...
+ EmployeeProject#2
+ Project#2
+ ...
+See how the structure includes the EmployeeProjects of Employee#2? We didn't write our custom data source calls to .Include in such a way that indicated that we wanted the root employee, their projects, the employees of those projects, and then the projects of those employees. But, because the JSON serializer blindly follows the object graph, that's what gets serialized. It turns out that the depth of the tree increases on the order of O(n^2), and the total size increases on the order of Ω(n!).
This is where IncludeTree comes in. When you use a custom data source like we did above, Coalesce automatically captures the structure of the calls to .Include and .ThenInclude, and uses this to perform trimming during creation of the DTO objects.
With an IncludeTree in place, our new serialized structure looks like this:
Employee#1
+ EmployeeProject#1
+ Project#1
+ EmployeeProject#6
+ Employee#2
+ EmployeeProject#11
+ Employee#3
+ ...
+ EmployeeProject#2
+ Project#2
+ ...
+No more extra data trailing off the end of the projects' employees!
However, there are sometimes cases where you perform complex loading in these methods that involves loading data into the current DbContext outside of the IQueryable that is returned from the method. The most common situation for this is needing to conditionally load related data - for example, load all children of an object where the child has a certain value of a Status property.
In these cases, Coalesce provides a pair of extension methods, .IncludedSeparately and .ThenIncluded, that can be used to merge in the structure of the data that was loaded separately from the main IQueryable.
For example:
public override IQueryable<Employee> GetQuery()
+{
+ // Load all projects that are complete, and their members, into the db context.
+ Db.Projects
+ .Include(p => p.EmployeeProjects).ThenInclude(ep => ep.Employee)
+ .Where(p => p.Status == ProjectStatus.Complete)
+ .Load();
+
+ // Return an employee query, and notify Coalesce that we loaded the projects in a different query.
+ return Db.Employees
+ .IncludedSeparately(e => e.EmployeeProjects)
+ .ThenIncluded(ep => ep.Project.EmployeeProjects)
+ .ThenIncluded(ep => ep.Employee);
+}
+public override IncludeTree GetIncludeTree(IQueryable<T> query, IDataSourceParameters parameters) => Db
+ .Employees
+ .IncludedSeparately(e => e.EmployeeProjects)
+ .ThenIncluded(ep => ep.Project.EmployeeProjects)
+ .ThenIncluded(ep => ep.Employee)
+ .GetIncludeTree();
+See the following two techniques for returning an IncludeTree from a custom method:
The easiest and most versatile way to return an IncludeTree from a custom method is to make that method return an ItemResult<T>, and then set the IncludeTree property of the ItemResult object. For example:
public class Employee
+{
+ public async Task<ItemResult<ICollection<Employee>>> GetChainOfCommand(AppDbContext db)
+ {
+ IQueryable<Employee> query = db.Employees
+ .Include(e => e.Supervisor);
+
+ var ret = new List<Employee>();
+ var current = this;
+ while (current.Supervisor != null)
+ {
+ ret.Push(current);
+ current = await query.FirstOrDefaultAsync(e => e.EmployeeId == current.SupervisorId);
+ }
+
+ return new(ret, includeTree: query.GetIncludeTree());
+ }
+}
+To tell Coalesce about the structure of the data returned from a model method, you can also add out IncludeTree includeTree to the signature of the method. Inside your method, set includeTree to an instance of an IncludeTree. However, this approach cannot be used on async methods, since out parameters are not allowed on async methods in C#. For example:
public class Employee
+{
+ public ICollection<Employee> GetChainOfCommand(AppDbContext db, out IncludeTree includeTree)
+ {
+ IQueryable<Employee> query = db.Employees
+ .Include(e => e.Supervisor);
+
+ var ret = new List<Employee>();
+ var current = this;
+ while (current.Supervisor != null)
+ {
+ ret.Push(current);
+ current = query.FirstOrDefault(e => e.EmployeeId == current.SupervisorId);
+ }
+
+ includeTree = query.GetIncludeTree();
+
+ return ret;
+ }
+}
+Server code:
public class Person
+{
+ // Don't include CreatedBy when editing - will be included for all other views
+ [DtoExcludes("Editor")]
+ public AppUser CreatedBy { get; set; }
+
+ // Only include the Person's Department when \`includes == "details"\` on the TypeScript ViewModel.
+ [DtoIncludes("details")]
+ public Department Department { get; set; }
+
+ // LastName will be included in all views
+ public string LastName { get; set; }
+}
+
+public class Department
+{
+ [DtoIncludes("details")]
+ public ICollection<Person> People { get; set; }
+}
+Client code:
`,4),R=s("div",{class:"language-typescript line-numbers-mode","data-ext":"ts"},[s("pre",{class:"shiki",style:{"background-color":"#1E1E1E"}},[s("code",null,[s("span",{class:"line"},[s("span",{style:{color:"#C586C0"}},"import"),s("span",{style:{color:"#D4D4D4"}}," { "),s("span",{style:{color:"#9CDCFE"}},"PersonListViewModel"),s("span",{style:{color:"#D4D4D4"}}," } "),s("span",{style:{color:"#C586C0"}},"from"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#CE9178"}},"'@/viewmodels.g'")]),e(` +`),s("span",{class:"line"}),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#569CD6"}},"const"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#4FC1FF"}},"personList"),s("span",{style:{color:"#D4D4D4"}}," = "),s("span",{style:{color:"#569CD6"}},"new"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#DCDCAA"}},"PersonListViewModel"),s("span",{style:{color:"#D4D4D4"}},"();")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#9CDCFE"}},"personList"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#9CDCFE"}},"$includes"),s("span",{style:{color:"#D4D4D4"}}," = "),s("span",{style:{color:"#CE9178"}},'"Editor"'),s("span",{style:{color:"#D4D4D4"}},";")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#C586C0"}},"await"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#9CDCFE"}},"personList"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#DCDCAA"}},"$load"),s("span",{style:{color:"#D4D4D4"}},"();")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#6A9955"}},"// Objects in personList.$items will not contain CreatedBy nor Department objects.")]),e(` +`),s("span",{class:"line"}),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#569CD6"}},"const"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#4FC1FF"}},"personList2"),s("span",{style:{color:"#D4D4D4"}}," = "),s("span",{style:{color:"#569CD6"}},"new"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#DCDCAA"}},"PersonListViewModel"),s("span",{style:{color:"#D4D4D4"}},"();")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#9CDCFE"}},"personList2"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#9CDCFE"}},"$includes"),s("span",{style:{color:"#D4D4D4"}}," = "),s("span",{style:{color:"#CE9178"}},'"details"'),s("span",{style:{color:"#D4D4D4"}},";")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#C586C0"}},"await"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#9CDCFE"}},"personList"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#DCDCAA"}},"$load"),s("span",{style:{color:"#D4D4D4"}},"();")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#6A9955"}},"// Objects in personList2.items will be allowed to contain both CreatedBy and Department objects. ")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#6A9955"}},"// Department will be allowed to include its other Person objects.")]),e(` +`),s("span",{class:"line"})])]),s("div",{class:"line-numbers","aria-hidden":"true"},[s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"})])],-1),K=s("div",{class:"language-typescript line-numbers-mode","data-ext":"ts"},[s("pre",{class:"shiki",style:{"background-color":"#1E1E1E"}},[s("code",null,[s("span",{class:"line"},[s("span",{style:{color:"#569CD6"}},"var"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#9CDCFE"}},"personList"),s("span",{style:{color:"#D4D4D4"}}," = "),s("span",{style:{color:"#569CD6"}},"new"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#9CDCFE"}},"ListViewModels"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#DCDCAA"}},"PersonList"),s("span",{style:{color:"#D4D4D4"}},"();")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#9CDCFE"}},"personList"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#9CDCFE"}},"includes"),s("span",{style:{color:"#D4D4D4"}}," = "),s("span",{style:{color:"#CE9178"}},'"Editor"'),s("span",{style:{color:"#D4D4D4"}},";")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#9CDCFE"}},"personList"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#DCDCAA"}},"load"),s("span",{style:{color:"#D4D4D4"}},"(() "),s("span",{style:{color:"#569CD6"}},"=>"),s("span",{style:{color:"#D4D4D4"}}," {")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#6A9955"}},"// objects in personList.items will not contain CreatedBy nor Department objects.")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#D4D4D4"}},"});")]),e(` +`),s("span",{class:"line"}),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#569CD6"}},"var"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#9CDCFE"}},"personList2"),s("span",{style:{color:"#D4D4D4"}}," = "),s("span",{style:{color:"#569CD6"}},"new"),s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#9CDCFE"}},"ListViewModels"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#DCDCAA"}},"PersonList"),s("span",{style:{color:"#D4D4D4"}},"();")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#9CDCFE"}},"personList2"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#9CDCFE"}},"includes"),s("span",{style:{color:"#D4D4D4"}}," = "),s("span",{style:{color:"#CE9178"}},'"details"'),s("span",{style:{color:"#D4D4D4"}},";")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#9CDCFE"}},"personList2"),s("span",{style:{color:"#D4D4D4"}},"."),s("span",{style:{color:"#DCDCAA"}},"load"),s("span",{style:{color:"#D4D4D4"}},"(() "),s("span",{style:{color:"#569CD6"}},"=>"),s("span",{style:{color:"#D4D4D4"}}," {")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#D4D4D4"}}," "),s("span",{style:{color:"#6A9955"}},"// objects in personList2.items will be allowed to contain both CreatedBy and Department objects. Department will be allowed to include its other Person objects.")]),e(` +`),s("span",{class:"line"},[s("span",{style:{color:"#D4D4D4"}},"});")]),e(` +`),s("span",{class:"line"})])]),s("div",{class:"line-numbers","aria-hidden":"true"},[s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"})])],-1),J=s("h3",{id:"properties",tabindex:"-1"},[s("a",{class:"header-anchor",href:"#properties","aria-hidden":"true"},"#"),e(" Properties")],-1),Q=s("code",null,"includes",-1),W=r("For DtoIncludes, this will be the values of includes for which this property will be allowed to be serialized and sent to the client.
For DtoExcludes, this will be the values of includes for which this property will not be serialized and sent to the client.
`,b.langId&&(L+=`",L}const ht={"&":"&","<":"<",">":">",'"':""","'":"'"};function ft(h){return h.replace(/[&<>"']/g,b=>ht[b])}function dt(h){var b;const j=new Set(["line"]);for(const n of h)for(const S of(b=n.classes)!==null&&b!==void 0?b:[])j.add(S);return Array.from(j)}class gt extends Te.exports.Registry{constructor(b){super(b),this._resolver=b,this.themesPath="themes/",this._resolvedThemes={},this._resolvedGrammars={}}getTheme(b){return typeof b=="string"?this._resolvedThemes[b]:b}async loadTheme(b){return typeof b=="string"?(this._resolvedThemes[b]||(this._resolvedThemes[b]=await Fe(`${this.themesPath}${b}.json`)),this._resolvedThemes[b]):(b=Ue(b),b.name&&(this._resolvedThemes[b.name]=b),b)}async loadThemes(b){return await Promise.all(b.map(j=>this.loadTheme(j)))}getLoadedThemes(){return Object.keys(this._resolvedThemes)}getGrammar(b){return this._resolvedGrammars[b]}async loadLanguage(b){const j=await this.loadGrammar(b.scopeName);this._resolvedGrammars[b.id]=j,b.aliases&&b.aliases.forEach(n=>{this._resolvedGrammars[n]=j})}async loadLanguages(b){for(const j of b)this._resolver.addLanguage(j);for(const j of b)await this.loadLanguage(j)}getLoadedLanguages(){return Object.keys(this._resolvedGrammars)}}function $e(h){return typeof h=="string"?xe.find(b=>{var j;return b.id===h||((j=b.aliases)===null||j===void 0?void 0:j.includes(h))}):h}function mt(h){var b;let j=xe,n=h.themes||[];return!((b=h.langs)===null||b===void 0)&&b.length&&(j=h.langs.map($e)),h.theme&&n.unshift(h.theme),n.length||(n=["nord"]),{_languages:j,_themes:n}}async function bt(h){var b,j;const{_languages:n,_themes:S}=mt(h),L=new ot(tt(),"vscode-oniguruma"),y=new gt(L);!((b=h.paths)===null||b===void 0)&&b.themes&&(y.themesPath=h.paths.themes),!((j=h.paths)===null||j===void 0)&&j.languages&&(L.languagesPath=h.paths.languages);const N=(await y.loadThemes(S))[0];let r;await y.loadLanguages(n);const d={"#000001":"var(--shiki-color-text)","#000002":"var(--shiki-color-background)","#000004":"var(--shiki-token-constant)","#000005":"var(--shiki-token-string)","#000006":"var(--shiki-token-comment)","#000007":"var(--shiki-token-keyword)","#000008":"var(--shiki-token-parameter)","#000009":"var(--shiki-token-function)","#000010":"var(--shiki-token-string-expression)","#000011":"var(--shiki-token-punctuation)","#000012":"var(--shiki-token-link)"};function k(t,s){t.bg=d[t.bg]||t.bg,t.fg=d[t.fg]||t.fg,s.forEach((_,v)=>{s[v]=d[_]||_})}function w(t){const s=t?y.getTheme(t):N;if(!s)throw Error(`No theme registration for ${t}`);(!r||r.name!==s.name)&&(y.setTheme(s),r=s);const _=y.getColorMap();return s.name==="css-variables"&&k(s,_),{_theme:s,_colorMap:_}}function i(t){const s=y.getGrammar(t);if(!s)throw Error(`No language registration for ${t}`);return{_grammar:s}}function T(t,s="text",_,v={includeExplanation:!0}){if(_t(s))return[...t.split(/\r\n|\r|\n/).map(H=>[{content:H}])];const{_grammar:P}=i(s),{_theme:A,_colorMap:I}=w(_);return it(A,I,t,P,v)}function g(t,s="text",_){let v;typeof s=="object"?v=s:v={lang:s,theme:_};const P=T(t,v.lang,v.theme,{includeExplanation:!1}),{_theme:A}=w(v.theme);return pt(P,{fg:A.fg,bg:A.bg,lineOptions:v==null?void 0:v.lineOptions})}async function l(t){await y.loadTheme(t)}async function u(t){const s=$e(t);L.addLanguage(s),await y.loadLanguage(s)}function p(){return y.getLoadedThemes()}function o(){return y.getLoadedLanguages()}function c(t){const{_theme:s}=w(t);return s.bg}function e(t){const{_theme:s}=w(t);return s.fg}return{codeToThemedTokens:T,codeToHtml:g,getTheme:t=>w(t)._theme,loadTheme:l,loadLanguage:u,getBackgroundColor:c,getForegroundColor:e,getLoadedThemes:p,getLoadedLanguages:o}}function _t(h){return!h||["plaintext","txt","text"].includes(h)}function kt(h){et(h)}export{xe as BUNDLED_LANGUAGES,yt as BUNDLED_THEMES,be as FontStyle,bt as getHighlighter,Fe as loadTheme,pt as renderToHtml,vt as setCDN,kt as setOnigasmWASM,et as setWasm,Ue as toShikiTheme}; diff --git a/assets/index.html.5d377a5b.js b/assets/index.html.5d377a5b.js new file mode 100644 index 000000000..5339e836a --- /dev/null +++ b/assets/index.html.5d377a5b.js @@ -0,0 +1 @@ +import{_ as s,y as r,z as d,X as e,B as t,Q as o,$ as i,a5 as c,P as l}from"./framework.fe9a73df.js";const u={},h=e("h1",{id:"coalesce",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#coalesce","aria-hidden":"true"},"#"),t(" Coalesce")],-1),p={href:"https://intellitect.com",target:"_blank",rel:"noopener noreferrer"},_=e("li",null,"ASP.NET Core",-1),m=e("li",null,"EF Core",-1),f=e("li",null,"TypeScript",-1),g={href:"https://vuejs.org/",target:"_blank",rel:"noopener noreferrer"},k=c('${b.langId}`),L+="",h.forEach((y,E)=>{var N;const r=E+1,d=(N=S.get(r))!==null&&N!==void 0?N:[],k=dt(d).join(" ");L+=``,y.forEach(w=>{const i=[`color: ${w.color||b.fg}`];w.fontStyle&be.Italic&&i.push("font-style: italic"),w.fontStyle&be.Bold&&i.push("font-weight: bold"),w.fontStyle&be.Underline&&i.push("text-decoration: underline"),L+=`${ft(w.content)}`}),L+=` +`}),L=L.replace(/\n*$/,""),L+="
You are responsible for the interesting parts of your application:
Coalesce builds the part of your application that are mundane and monotonous to build:
',5),w=e("li",null,"APIs to interact with your models via endpoints like List, Get, Save, and more.",-1),y=e("li",null,"A complete set of admin pages are provided, allowing you to read, create, edit, and delete data straight away without writing any additional code.",-1),b=e("h1",{id:"getting-started",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#getting-started","aria-hidden":"true"},"#"),t(" Getting Started")],-1);function v(x,C){const n=l("ExternalLinkIcon"),a=l("RouterLink");return r(),d("div",null,[h,e("p",null,[t("Designed to help you quickly build amazing web applications, Coalesce is a rapid-development code generation framework, created by "),e("a",p,[t("IntelliTect"),o(n)]),t(" and built on top of:")]),e("ul",null,[_,m,f,e("li",null,[e("a",g,[t("Vue"),o(n)])])]),k,e("ul",null,[e("li",null,[t("Client side "),o(a,{to:"/stacks/vue/layers/viewmodels.html"},{default:i(()=>[t("TypeScript ViewModels")]),_:1}),t(" that mirror your data model for both lists and individual objects. Utilize these to rapidly build out your application's various pages.")]),w,e("li",null,[t("Out-of-the-box "),o(a,{to:"/stacks/vue/coalesce-vue-vuetify/overview.html"},{default:i(()=>[t("Vue Components")]),_:1}),t(" for common controls like dates, selecting objects via drop downs, enums, etc. Dropdowns support searching and paging automatically.")]),y]),b,e("p",null,[t("To get started with Coalesce, check out "),o(a,{to:"/stacks/vue/getting-started.html"},{default:i(()=>[t("Getting Started with Vue")]),_:1}),t(".")]),e("p",null,[t("While Knockout.js is still supported by Coalesce, it is a deprecated option and not recommended for new projects. If you do still want to choose Knockout, click "),o(a,{to:"/stacks/ko/getting-started.html"},{default:i(()=>[t("here")]),_:1}),t(".")])])}const V=s(u,[["render",v],["__file","index.html.vue"]]);export{V as default}; diff --git a/assets/index.html.6f4afde9.js b/assets/index.html.6f4afde9.js new file mode 100644 index 000000000..a12d31cf8 --- /dev/null +++ b/assets/index.html.6f4afde9.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-8daa1a0e","path":"/","title":"Coalesce Documentation","lang":"en-US","frontmatter":{"lang":"en-US","title":"Coalesce Documentation","description":"Documentation home page for IntelliTect.Coalesce"},"excerpt":"","headers":[{"level":2,"title":"What do I do?","slug":"what-do-i-do","link":"#what-do-i-do","children":[]},{"level":2,"title":"What is done for me?","slug":"what-is-done-for-me","link":"#what-is-done-for-me","children":[]}],"git":{"updatedTime":1677792094000},"filePathRelative":"index.md"}');export{e as data}; diff --git a/assets/inject.html.6b988db4.js b/assets/inject.html.6b988db4.js new file mode 100644 index 000000000..311e9e92c --- /dev/null +++ b/assets/inject.html.6b988db4.js @@ -0,0 +1,13 @@ +import{_ as o,y as p,z as t,X as n,B as s,Q as l,$ as e,a5 as c,P as r}from"./framework.fe9a73df.js";const D={},i=n("h1",{id:"inject",tabindex:"-1"},[n("a",{class:"header-anchor",href:"#inject","aria-hidden":"true"},"#"),s(" [Inject]")],-1),y=n("p",null,"========",-1),d=n("code",null,"IServiceProvider",-1),u=c(`This gets translated to a Microsoft.AspNetCore.Mvc.FromServicesAttribute in the generated API controller's action.
public class Person
+{
+ public int PersonId { get; set; }
+ public string FirstName { get; set; }
+ public string LastName { get; set; }
+
+ public string GetFullName([Inject] ILogger<Person> logger)
+ {
+ logger.LogInformation("Person " + PersonId + "'s full name was requested");
+ return FirstName + " " + LastName";
+ }
+}
+If no color is saved in the database (the user hasn't picked a color), one is deterministically created.
public class ApplicationUser
+{
+ public int ApplicationUserId { get; set; }
+
+ [InternalUse]
+ public string ColorHex { get; set; }
+
+ [NotMapped]
+ public string Color
+ {
+ get => ColorHex ?? GenerateColor(ApplicationUserId).ToRGBHexString();
+ set => ColorHex = value;
+ }
+
+ public static HSLColor GenerateColor(int? seed = null)
+ {
+ var random = seed.HasValue ? new Random(seed.Value) : new Random();
+ return new HSLColor(random.NextDouble(), random.Next(40, 100) / 100d, random.Next(25, 65) / 100d);
+ }
+}
+When a textual representation of an object needs to be displayed in the UI, this attribute controls which property will be used. Examples include dropdowns and cells in admin UI tables.
If this attribute is not used, and a property named Name exists on the model, that property will be used. Otherwise, the primary key will be used.
public class Person
+{
+ public int PersonId { get; set; }
+
+ public string FirstName { get; set; }
+
+ public string LastName { get; set; }
+
+ [ListText]
+ [NotMapped]
+ public string Name => FirstName + " " + LastName
+}
+string.StartsWith.Example usage:
var list = new ListViewModels.PersonList();
+list.filter = { lastName: "Erickson" };
+list.load();
+Specifies that the targeted model instance method should load the instance it is called on from the specified data source when invoked from an API endpoint. By default, the default data source for the model's type will be used.
public class Person
+{
+ public int PersonId { get; set; }
+ public string FirstName { get; set; }
+
+ [Coalesce, LoadFromDataSource(typeof(WithoutCases))]
+ public void ChangeSpacesToDashesInName()
+ {
+ FirstName = FirstName.Replace(" ", "-");
+ }
+}
+public class Person
+{
+ public int PersonId { get; set; }
+ public string FirstName { get; set; }
+ public string LastName { get; set; }
+
+ [ManyToMany("Appointments")]
+ public ICollection<PersonAppointment> PersonAppointments { get; set; }
+}
+Type could be a language primitive like string or number, a non-primitive JavaScript type (date, file), or in the case of a custom Type, the type kind of that type (model, enum, object). For custom types, an additional property typeDef will refer to the Type metadata for that type.
Role represents what purpose the value serves in a relational model. Either value (the default - no relational role), primaryKey, foreignKey, referenceNavigation, or collectionNavigation.
A Property is a more refined Value that contains a number of additional fields based on the role of the property.
The type of the default export of the generated metadata. Serves as a single root from which all other metadata can be accessed. Contains fields types, enums, and services as organizing structures for the different kinds of custom types.
Here's an example for a method called Rename that takes a single parameter 'string name' and returns a string.
public string Rename(string name)
+{
+ FirstName = name;
+ return FullName; // Return the new full name of the person.
+}
+