Tutorial: Custom DataSources for EAV / 2sxc #1

In 2sxc 9.13 we made it easier to create custom data sources - something that's been requested often lately. This is part 1 of 4.

1. Part 1: The most basic DataSource delivering 1 item
2. Part 2: Creating lists which come from elsewhere
3. Part 3: Unit Testing DataSources
4. Part 4: Creating a distributable DNN package with your DataSource
5. Part 5: Giving the admin a configuration UI

Some Background: What is this, and what for?

DataSource objects provide a list of data-items. This can be anything, like:

• people items (for showing nice lists of people)
• blog-items (for showing list/details of blogs)
• page items (for generating a special menu)

Since these DataSource objects are very generic you can wire them together. So you can connect the Out of any source to the In of another source, and make them do cool things. This can then look like this: 

This example has an App data-source providing Company items, which go through a Paging data-source, which provide a two lists to the final output - a list containing the items of the current page, and a list containing paging information. 

To learn more about DataSources, read the blog-posts about them. 

Creating Your Own First DataSource

Let's just start with some code - this is what the most basic DataSource looks like:

using System;
using System.Collections.Generic;
using ToSic.Eav.DataSources;
using ToSic.Eav.DataSources.VisualQuery;
using ToSic.Eav.Interfaces;

namespace ToSic.Tutorial.DataSource
{
    // additional info so the visual query can provide the correct buttons and infos
    [VisualQuery(
        NiceName = "DateTime-Basic",
        GlobalName = "7aee541c-7188-429f-a4bb-2663a576b19e",   // namespace or guid
        HelpLink = "https://github.com/2sic/2sxc/wiki/DotNet-DataSources-Custom"
    )]
    public class DateTimeDataSourceBasic: ExternalDataDataSource
    {
        public const string DateFieldName = "Date";

        /// <summary>
        /// Constructor to tell the system what out-streams we have
        /// </summary>
        public DateTimeDataSourceBasic()
        {
            Provide(GetList); // default out, if 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 not execute unless it's really used
        /// </summary>
        /// <returns></returns>
        private IEnumerable<IEntity> GetList()
        {
            var values = new Dictionary<string, object>
            {
                {DateFieldName, DateTime.Now}
            };
            var entity = AsEntity(values);
            return new List<IEntity> {entity};
        }
    }
}

This code shows:

1. The VisualQuery attribute, so that this data-source will be shown in VisualQuery
2. The constructor, which tells the source what Out-streams it has, in this case it's just the Default
3. A method GetList which gets the items, if ever requested

Using in in Visual Query

To now use it, you must manually copy the DLL into the web/bin folder, and load the visual query designer. You can now drag it in:

...and if you query it, you'll see something like this:

Now that was just the very basics. More to come...

Last Remarks

Note that these examples use the newest (easiest) API from 2sxc 9.13. Previous versions were more difficult, so I really recommend to use that. 

Love from Switzerland,
Daniel

PS: During the next days I'll show a more sophisticated example, delivering a list of items