• Basics
  • Abyss
  • Web APIs
  • C# & Razor
  • .net API
  • JS & TS API

    Show / Hide Table of Contents

    Create Custom DataSources

    you are here (click to zoom) - discover the stack

    If you want to create your own DataSource and use it in C# or the VisualQuery designer, this is for you.

    • Docs about the API
    • DataSource Configuration
    • how LookUps work

    Simple Example

    Here's an example of a complete data-source, which just delivers 1 item with the current date:

    using System;
    using System.Collections.Generic;
    using System.Collections.Immutable;
    using ToSic.Eav.Data;
    using ToSic.Eav.DataSources;
    using ToSic.Eav.DataSources.Queries;
    
    namespace ToSic.Tutorial.DataSource.Basic
    {
        // Additional info so the VisualQuery can provide the correct buttons and infos
        [VisualQuery(
            NiceName = "Demo DateTime Basic",
            GlobalName = "7aee541c-7188-429f-a4bb-2663a576b19e"   // random & unique Guid
        )]
        public class DateTimeDataSourceBasic: ExternalData
        {
            public const string DateFieldName = "Date";
    
            /// <summary>
            /// Constructor to tell the system what out-streams we have
            /// </summary>
            public DateTimeDataSourceBasic()
            {
                Provide(GetList); // "Default" out; when accessed, will deliver GetList
            }
    
            /// <summary>
            /// Get-List method, which will load/build the items once requested 
            /// Note that the setup is lazy-loading so this code will only execute when used
            /// </summary>
            private ImmutableArray<IEntity> GetList()
            {
                var date = DateTime.Now;
                var values = new Dictionary<string, object>
                {
                    {DateFieldName, date},
                    {"Weekday", date.DayOfWeek},
                    {"DayOfWeek", (int) date.DayOfWeek}
                };
    
                // Construct the IEntity and return as ImmutableArray
                var entity = DataBuilder.Entity(values, titleField: DateFieldName);
                return new [] {entity}.ToImmutableArray();
            }
        }
    }
    

    This code demonstrates:

    1. The VisualQuery attribute, so that this data-source will be shown in VisualQuery
    2. The constructor DateTimeDataSourceBasic(), which tells the source what Out-streams it has using Provide, in this case it's just the Default
    3. A method GetList() which gets the items if ever requested
    4. The DataBuilder.Entity(...) helper to construct IEntity objects from value-dictionaries

    Use in VisualQuery Designer

    This is what the DataSource would appear like in VisualQuery

    ...and this is what the test-run would look like

    Demo App and further links

    • DataSource API: VisualQuery Attribute
    • DataSource API: Provide(...)
    • DataSource API: DataBuilder.Entity(...)
    • Basic DataSources for EAV and 2sxc
    • Blog about this feature
    • Blog post about custom DataSources

    History

    1. Introduced in 2sxc ca. 4 but with a difficult API
    2. API strongly enhanced and simplifield in 2sxc 09.13
    3. Another API rework ca. 2sxc 10.25 (but we're not exactly sure)
    • Improve this Doc
    Back to top Generated by DocFX