Symphony.

The S2 Data Source Editor is that friendly enough pub that helps me through the day on a regular basis without me needing to know too much about what happens in the back.

But within the not oft spoken of dark corners such as {$param}s, and $ds-another-data-source chaining I suspect there is a lot I'm missing out on. I'd love to find out, saving a punch in the mouth ;)

I've tried to find more detail on how to use these settings and what effect they have but haven't turned up much. (I see some default examples in the standard S2 install but am not able to discern exactly how they all fit together.)

I'm coming new to Symphony with v2, so maybe I'm missing some of the basics but how does one utilize and leverage the settings below?

Any quick explanations or pointers to more in-depth information are greatly appreciated!

DS Editor > Filter Results > "Use {$param} syntax to filter by page parameters."

• From what I can tell one needs to set a variable here (to pass the value of a entry's custom field) that will be used later in the page 'URL Parameters'. (Does it always / only have this use?)
• I see some examples where the same parameter value is repeated in the 'Required URL Parameter' field but haven't been able to discern and pattern or effect for when this is applicable.
• I also see examples of $ds-other-data-sources being listed here but don't understand how the chaining process works.

DS Editor > Sorting & Limiting > Required URL Parameter

• How and when does one use this field?

DS Editor > Output Options > Parameter Output

• Can anyone shed some light on how and when to use this? It's for chaining DS together, correct? If so, how and to what effect?

Above items relationship to Page 'URL Parameters'?

• Are the URL Parameters set specifically in response to the variables in the DS (i.e. should they just mirror the DS parameters and/or 'required url parameter') or are they used for other purposes as well?

Sorry for the litany of questions; I'm probably asking the same thing four times ;) If the above questions are a quagmire of chasing my own tail, feel free to set me straight on a simple overview for how it all works. Thanks again in advance for help and insights.

Best, Clayton

I just realized that I think one small thing that may be adding to the confusion is that the {$param}s from the DS 'Filter Results' section don't show up in the Debug 'Params' section unless they've also been declared as 'URL Parameters' in the Page (at least I think this is what's happening...)

Is this the case or are the DS {$param}s still being passed as parameters to the page irrespective even if they don't show up in the Debug 'Params' menu?

After reading your well thought-out and beautifully formatted piece, my answers will seem rather inadequate in comparison. I'm in a rush to finish some things but I don't want to wait until I'm done before I tackle your questions. So here goes:

The curly brace syntax, similar to XSLT's AVT (Attribute Value Template), is a way to instruct the system to "evaluate this". So say, $colour has the value red, the syntax {$colour} will evaluate to red. Prior to Symphony 2, parameters are automatically evaluated but this has a limitation. The new way allow something like this:

bright-{$colour}

This will evaluate to bright-red.

The problem with this approach is that there are actually 3 ways of representing a parameter. Well, actually there is only one, but the context in which it's used can be confusing. We have:

1. The name of the parameter. i.e. name, colour, size, etc.
2. The parameter. i.e. $name.
3. The value of the parameter. Value of $colour is red.
4. Evaluating the parameter. {$colour} => red.

Page -> URL Parameters

The idea of URL Parameters have not changed since Symphony 1.0. This is a typical declaration of URL Parameters:

name/size/colour

In this instance, Symphony is looking for a list of parameter names you want for your page, hence the omission of the dollar sign ($). This creates 3 parameters for a page, $name, $size and $colour. Assigning values via the URL will assign them to their respective parameters.

DS -> Filtering

When filtering in the data source editor, the filter inputs look for literal values. For example, to filter by a date:

2008-09-21

This will return you all entries matching the above date. However, one extra feature for the data source filter is the ability to first evaluate parameters into literal values:

2008-{$month}-21

If $month is 02, the evaluated string becomes: 2008-02-21.

DS -> Required Parameter

Required parameter is a new feature for the data source editor. It allows the system to decide if a data source should return a result based on what parameters are deemed as "required". For example:

$colour

In this instance, Symphony is looking for parameters (not parameter names). If you put the above in the input field, you are instructing the data source to only return a result if $colour is set (have a value).

I've ran out of time. If somebody haven't had the chance to explain the DS Param Output before I do, I'll post up a quick explanation to them.

Before I explain how DS param output works, we need to first look at some of the other new features of data source filtering:

Enumeration

In some instances, you may want your data source to be filtered by a different parameter or value if the main parameter is not set:

{$size:large}

The colon syntax denotes enumeration. The above says, if $size is not set, the value would then be the literal string, large.

You can also do multiple enumeration:

{$a:$b:5}

This says, if $a is not set, the value is $b. If $b is not set, the value is 5. If no parameters are set and no literal string is declared as a fallback, the result would be an empty string.

Union

You can filter and grab more than one item:

apple, banana, custard, dragon-fruit

This says, grab all entries that are in apple, banana, custard and dragon-fruit.

Intersection

You can filter by items with multiple qualities:

red+blue

This says, grab any entries that are both red and blue.

Allen,

Thank you very much for the kind words and time taken for such a quick and detailed response. I'll need to read through this several times to let it soak in properly but it definitely helps provide a better understanding of what all can be done.

One light bulb in particular that just clicked on is the effect of what direction you conceive the information to be flowing. I've been thinking in terms of 1) data into the system (sections / custom fields), 2) data parsed into relevant XML (data sources, events), and then 3) converting XML into XHTML for browser display (utilities and pages.) You're mention of the DS taking a value from the page to affect the query via a parameter (which I guess I knew, but was thinking of as the params flowing from DS to Page instead) makes a lot more sense in this context.

I'm sure I'll have a bit more understanding, and likely a few more questions, upon gleaning this information closer but here are a couple of quickies -

• Enumeration, et all looks very cool. Can it also be utilized within the Page 'URL Parameters' field? (I.e. instead of param-a/param-1 could one use param-a:param-b/param-1?)

• Regarding Union, you mention -

  You can filter and grab more than one item: apple, banana, custard, dragon-fruit This says, grab all entries that are in apple, banana, custard and dragon-fruit.

Do you mean apple... custard AND dragon-fruit (as in the royal 'and'† ;) or is this more of a OR where any entry with any one of the values will be returned?

Many thanks again for your help. It is greatly appreciated.

Best, Clayton

† I have no idea what 'the royal and' even means although I wish I would have thought of it as a band name had I ever thought to start a band.

So to clarify the notion of data flow, I like to throw out a little phrase I use quite often (and religiously), "Page is king".

The flow from a data perspective is as follows:

Page -> Data Source -> XSLT -> (x)HTML

A page is like a shell that encompasses data sources, events, parameters and XSLT. This is also reflected by the ?debug page (I'll explain this later).

A page is the provider of parameters. A page designates what parameters are available to be assigned from the URL. Take the following as an example, the page settings of:

Page Name: Shirts
URL Param: name/colour/size

With an URL Supplied as:

http://yoursite.com/shirts/koala/blue/medium/

Will return the following parameters - you can check this via ?debug -> Parameters.

$current-page = shirts
$name = koala
$colour = blue
$size = medium

The ?debug -> Parameters page is an important one. Any parameters shown on the page are accessible by any data source and XSLT.

Enumeration, et all looks very cool. Can it also be utilized within the Page 'URL Parameters' field? (I.e. instead of param-a/param-1 could one use param-a:param-b/param-1?)

Enumeration is only available on data source filter fields. It doesn't quite make sense on page parameters since parameters would only ever be set or not set. Take your example for instance:

param-a:param-b/param-1

If I supply the page with the following URL:

http://yoursite.com/yourpage/apple/banana/

the values would be:

$param-a = apple
$param-1 = banana

If I supply the page with the following URL (i.e. without any parameter values):

http://yoursite.com/yourpage/

the values would be:

$param-a = ''
$param-1 = ''

In your hypothetical situation where enumeration works on URL Parameters, $param-a would not be set, so $param-b would kick in. However, $param-b does not have a value also, so both $param-a and $param-b would be empty. In fact there would not be an instance where $param-b has a value.

The only way enumeration might work on URL Parameters is if you supply it with something like this (again, this is hypothetical):

param-a:apple/param-1

In this instance, if the url supplied was:

http://yoursite.com/yourpage/

The values would be:

$param-a = 'apple'
$param-1 = ''

Since $param-a has no values set, it would enumerate to apple. However, this also has a problem. Since URLs are sequential, for $param-a to have an empty value (so it would enumerate to apple), $param-1 must never be set.

I hope the above clarifies things more than it confuses.

Regarding Union, you mention - Do you mean apple... custard AND dragon-fruit (as in the royal 'and'† ;) or is this more of a OR where any entry with any one of the values will be returned?

The use of comma as separators (Union) acts as an OR operator. i.e. any entry with any one of the values will be returned.

The use of plus as separators (Intersection) acts as an AND operator. i.e only entries with all of the values will be returned.

Do you mean apple... custard AND dragon-fruit (as in the royal 'and'† ;) or is this more of a OR where any entry with any one of the values will be returned?

These links might be helpful:

• Discussion about the semantics of these operators
• URL params article on Chaotic Pattern

Thanks for the additional clarification Allen. That helps.

Enumeration, et all looks very cool. Can it also be utilized within the Page 'URL Parameters' field? (I.e. instead of param-a/param-1 could one use param-a:param-b/param-1?)

It doesn't quite make sense on page parameters since parameters would only ever be set or not set.

Yeah, sorry, this clicked in as an obvious 'duh' after sleeping on it a bit. (Either thankfully, or pathetically, I'm now dreaming in Symphony ;) Again, I think I was getting mixed up in terms of which direction the parameters are being declared and utilized. 'Page is king' helps clear this up a bit.

These links might be helpful...

Cool, thanks Scott.

I feel like a giddy school girl with how cool and simple it is (once it starts to click) to work with XSLT and Symphony. This certainly helps shed some light on things.

Back to the pillow fights... I imagine I'll be back soon with more bruises ;)

Best, Clayton

Data source parameter output

When I said "page is king" and the notion that page is the provider of all things for the family, it's not entirely true. But before you call me a liar, screaming across the neighbours yard realising your whole perception of reality is in ruins, I did it for clarity's sake - to ease you into the advanced topic of data source parameter output. For you see, data sources can also provide parameters.

Parameter Pool is the unofficial term we use within the Symphony development team to denote the accessible parameters for a given page (?debug -> Parameters).

When you set your data source to output as a parameter, it sets the following to the parameter pool:

$ds-name = "value-1, value-2, value-3"

To put it in context, say that you have a data source named "Entries" and it is limited by 3 entries. If you select the system id as the parameter output, you might get something like this:

$ds-entries = "243, 268, 349"

Remember, anything in the parameter pool can be accessed by XSLT and data sources. Incidentally, this is an excellent way for one data source to filter by another data source's result.

For example, you could have a data source that grabs all comments that belong to entries 243, 268 or 349.

I did it for clarity's sake - to ease you into the advanced topic of data source parameter output.

Thanks Allen, any and all easing is much appreciated ;)

When you set your data source to output as a parameter, it sets the [result] to the parameter pool

Cool, this is all starting to make sense (the newbie said optimistically...)

Thanks again Allen, Clayton

Well done Allen. I'll make sure to reference this thread while I write the data source portion of the user guide.

Is it possible to apply math to the value of {$param} ?

I have an Announcements section with a Published date field and a Expires date field.

I have two DS: Current Announcements and Expired Announcements

The Current Announcements are filtered as:

Expiration Date: {$today} to 2010-01-01

The Expired Announcements are filtered as:

Expiration Date: 1910-01-01 to {$today}

As you can see an announcement expired $today, the announcement will be both Current and Expired DS.

Instead I'd like to make it so that if it expires $today, it is still in the Current DS but excluded from the Expired DS.

Thoughts?

As you can see an announcement expired $today, the announcement will be both Current and Expired DS.

There are a few solutions for this on the not-too-distant horizon.

1. The $today param (or perhaps a different param) should represent the exact current time, so that ranges using it work correctly.
2. Each part of the current time could be accessible on its own, e.g. {$current-year}/{$current-month}/1.
3. An upcoming DS editor improvement is the ability to choose which "filter type" a particular filter rule should use, such as exact match, substring match, date range, etc. An eventual goal is for the extension API to allow custom filter types, so a "Math" type as you suggest could be made.

I'm trying to use enumeration in a DS filter:

{$current-entry:$ds-section-index}

where the first is a URL param and the second is a DS output.

But it doesn't seem to be working (it acts like the filter isn't there). Either param by itself does work. I should be able to use enumeration in DS filters, right?

@ashooner: This should be working. Check the value of $ds-section-index on the debug page - if it's empty, then when $current-entry is also empty, the filter will act like it's not there. Otherwise this might be a bug.

thanks for a lot of the clarification guys. didn't fully realize how powerful the ds filtering was in s2.

edit. However, i was trying to do an Intersection operator but it wasn't filtering images associated with the entry i was filtering. is this due to the structure of the section links?

@scott

sorry for the delay. No bug, my mistake.

Is there a way to filter in a DS when a parameter is empty or some sort of negative filter? I have a "featured" check box and only want that information to show up on one page. However, with my current setup, anything that is "featured" is being included on all pages. How would I limit this info to be shown on the pages I want?