Simple Example

Let's start with a simple example. Imagine topic called SharedMembersSampleTopic1. In this topic, you might define a couple of properties:

 Color: red
 Size: large

Now, if you wanted to refer to these properties, you could always do it by explicitly referencing the properties like this:

 ||The color is @@topics.SharedMembersSampleTopic1.Color@@||

producing:

Or Functions Perhaps

You could also define a function instead of a literal property in SharedMembersSampleTopic1. For example, you could add:

 WhatTimeIsIt:{ DateTime.Now }

and then use this WikiTalk to show the results of using this function:

 ||The time is @@topics.SharedMembersSampleTopic1.WhatTimeIsIt@@||

producing:

Using the WithFunction

This technique of explicity naming the topic containing the shared members works OK in a case where you only need one or two members. On the other hand, if you're writing a longer stretch of WikiTalk and you don't want to have to say topics.SharedMembersSampleTopic1.[something] everytime, this is inconvenient.

The with function is used to bring all of the members (properties and functions) in another topic into scope for a block of WikiTalk. For example, the above example that shows the current time could be rewritten as follows:

 ||The time is @@
 with (topics.SharedMembersSampleTopic1)
 {
         WhatTimeIsIt
 }
 @@||

producing the same result:

This use of the with function says, in essence, inside the given block of code, make all of the members of topics.SharedMembersSampleTopic1 be "in scope" so that I don't have to name where they come from.

Using the WithProperty

The WithFunction is helpful. But the WithProperty is even more helpful. Using the WithProperty on a page allows you to declare one or more topics that should be available for all of the WikiTalk in the topic containing the WithProperty. For example, by adding a WithProperty to this page that references SharedMembersSampleTopic1, I could bring all the members from that "shared library" into scope for the current topic. This would let me avoid needing to either explicity reference the topic as in the simple examples at the top of this discussion and would also let me avoid needing to use the WithFunction.

The WithProperty is a regular multi-valued WikiPageProperty that includes a list of topics to "include." So, to include all the members from SharedMembersSampleTopic1, I would say:

 With: SharedMembersSampleTopic1

Note: the name of this property is case-sensitive; it needs a capital 'W'

To see this in action, you can look at the WithPropertyDemo (and be sure to look at the source code for the topic).

This approach is also used here on FlexWiki with the ReflectionLibrary and over on Derek's Bliki with the BlikiLibrary -- DerekLakin [2004-Oct-28]

I notice that the sample WhatTimeIsIt property on the WithPropertyDemo WikiPage page is declared as such:

 WhatTimeIsIt: { DateTime.Now }

Is there a difference between using curly braces and using the @@ syntax? For example-

 WhatTimeIsIt: @@DateTime.Now@@

The With reference to SharedMembersSampleTopic1 appears to evaluate the content inside the curly braces as a WikiTalkExpression. Moreover, is the use of {} over @@ intentional, and in which scenarios is one more appropriate than the other?

It seems to me that when you use a section such as WhatTimeIsIt: as a function the entire content is evaluated as a single statement, as if there was @@ @@ around it, so adding the {}'s tells it that it is a block.