| This page is divided in two sections, the first section is a formal description of xml within the <wm:SlidingMenu ...> element. The second section is a description of basic principles for .Net (written in C#) databinding. Each section have a synopsis, some semi-code and a discussion of the semi-code. |
|
SlidingMenu XML markup |
|
| The semi-code below is a description of the structure of tags
within a <wm:SlidingMenu> element. (You can also see
SlidingMenu XSD background for IntelliSense, however IntelliSense do not at all support the w3 recommendations
and as such, the XSD is not a sufficient description of the SlidingMenu
tag structure). The semi-code do not describe the attributes of the SlidingMenu XML markup, these you can find under Elements Documentation. While you can have as many <wm:SlidingMenu> tags on
a Web Form page as you like, the figures in brackets {} show the number of
valid elements within a specific <wm:SlidingMenu> structure. |
|
Semi-code |
Semi-code discussion |
| 0. | <wm:SlidingMenu id="[some id]" runat="server" style="[some style]"> | | 1. | | <SlidingMenuStyle [some attributes] /> {0,1} | | 2. | | <GroupHeaderStyle [some attributes] /> {0,1} | | 3. | | <GroupCanvasStyle [some attributes] /> {0,1} | | 4. | | <AddManualGroup> {0,*} | | 5. | | | <GroupHeaderStyle [some attributes] /> {0,1} | | 6. | | | <GroupCanvasStyle [some attributes] /> {0,1} | | 7. | | | <GroupHeader> {1} | | 8. | | | | [header content] | | 9. | | | </GroupHeader> | | 10. | | | <GroupCanvas> {1} | | 11. | | | | [canvas content] | | 12. | | | </GroupCanvas> | | 13. | | </AddManualGroup> | | 14. | | <DataBound> {0,1} | | 15. | | | <HeaderTemplate> {1} | | 16. | | | | [header content] | | 17. | | | </HeaderTemplate> | | 18. | | | <CanvasTemplate> {1} | | 19. | | | | [canvas content] | | 20. | | | </CanvasTemplate> | | 21. | | </DataBound> | | 22. | | <AddManualGroup> {0,*} | | 23. | | | <GroupHeaderStyle [some attributes] /> {0,1} | | 24. | | | <GroupCanvasStyle [some attributes] /> {0,1} | | 25. | | | <GroupHeader> {1} | | 26. | | | | [header content] | | 27. | | | </GroupHeader> | | 28. | | | <GroupCanvas> {1} | | 29. | | | | [canvas content] | | 30. | | | </GroupCanvas> | | 31. | | </AddManualGroup> | | 32. | </wm:SlidingMenu> |
|
| At line 1, <SlidingMenuStyle ... />, you see that SlidingMenu global styles can be defined 0 or 1 times and must be directly beneath the <wm:SlidingMenu> opening tag. |
| At line 2, <GroupHeaderStyle ... />, you see that it is possible to define default styles for all GroupHeaders (so you don't need to write styles for each Group). Then the element is set here, the GroupHeaderStyle is said to be set at top-level. |
| At line 4, <AddManualGroup>, you see it is possible to start declaring 0 or more manual Groups |
| At line 5, <GroupHeaderStyle ... />, you see that is is possible to define styles for the GroupHeader of this Group. Then the element is set here, the GroupHeaderStyle is said to be set at group-level. If a specific style is not set at group-level, say BorderWidth, SlidingMenu will substitute with the BorderWidth defined at the top-level GroupHeaderStyle (and if not defined there, SlidingMenu will fall back on SlidingMenu internal default values, see Elements Documentation). |
| At line 7, <GroupHeader>, you see that inside an <AddManualGroup> element, there must be 1 and only 1 <GroupHeader> element, that is: a Group always have 1 GroupHeader. |
| At line 8, [header content], you can have ANY HTML and ANY ASP WebControl and even new SlidingMenues (though you would probably not put SlidingMenues in the GroupHeader, it is more likely that you want SlidingMenues in the GroupCanvas). |
| At line 14, <DataBound>, you see that there can be 0 or 1 DataBound element, that is: SlidingMenu can have a maximum of 1 datasource. From the overall structure (line 4, 14 and 22) you can see that if you have a DataBound element, this element can be ANYWHERE among its AddManualGroup siblings or put opposite: AddManualGroup elements can be added arbitrary together with an eventually DataBound element. |
| At line 15, <HeaderTemplate>, you see that there must be 1 and only 1 HeaderTemplate element within the DataBound element. The DataBound element is explained in more details in the next section - SlidingMenu DataBinding. |
|
|
|
|
|
SlidingMenu DataBinding |
|
| If you have not worked with .Net databinding before, you should not read further. If you have already worked a little with .Net databinding, hang on and you will learn some basic principles of .Net databinding here. Databinding SlidingMenu is identical to databinding other .Net WebControls. |
|
| I think it is fair to say, that then working with .Net databinding, most people will normally have an XML part and a C# (or VB.NET) part. The XML part will define layout through templates and the C# part will bind elements in the templates to the data of the datasource. This is anyway the scenario I will show here. Therefore this section is divided in an XML part and a C# part. |
|
Semi-code XML part | Semi-code XML part discussion |
| 0. | <wm:SlidingMenu id="MySM" runat="server"> | | 1. | | <DataBound> | | 2. | | | <HeaderTemplate> | | 3. | | | | <asp:Label id="lblHeader" runat="server" /> | | 4. | | | </HeaderTemplate> | | 5. | | | <CanvasTemplate> | | 6. | | | | <asp:Label id="lblCanvas" runat="server" /> | | 7. | | | </CanvasTemplate> | | 8. | | </DataBound> | | 9. | </wm:SlidingMenu> |
|
| In the C# code you will connect a datasource with the DataBound element. Then upon calling
.DataBind() each of the template elements (<HeaderTemplate> and
<CanvasTemplate>) will be instantiated as .Net ITemplate objects for each item in the data source -
if you have a DataRowCollection with 10 DataRow's, these templates (template = ITemplate object) will be
instantiated 10 times. Everything inside the templates will be added as
Control's to the templates Controls collection. The header template on line 2 will be instantiated 10 times,
and the asp:Label WebControl on line 3 will be instantiated each time and added to the header template objects collection of Controls, so each of the 10 header templates will have a Controls collection with one Label Control. The asp:Label on line 3 is however not the only WebControl that will be added to the header templates Controls collection, all the whitespaces will be instantiated as Literal WebControls and also added to each header templates Controls collection.
|
|
|
|
| The following is the .Net (written in C#) principles of databinding in general and SlidingMenu specifically.
The 5 most important elements in any WebControls databinding support is listed below and then
you are finish reading the code discussion, you will also understand the description of these
elements. |
| property DataSource | | there must of course be a
data source, in SlidingMenu the data source must be an
IEnumerable, in this example I will use a DataRowCollection.
Other examples of classes in the .Net Framework API, class
library, that implements IEnumerable is DataTableCollection, [Sql|OleDb]DataAdapter,
[Sql|OleDb]DataReader, Array, ArrayList, BaseCollection (and therefore all kinds of Collections), Cache, DataView, DataViewManager, XmlNode, XmlNodeList and many more... |
| method DataBind() | | after DataSource is initialized, you call DataBind() to raise GroupDataBound events on each item in the data source. |
| event GroupDataBound | | then DataBind() is called, GroupDataBound event is raised for each item in the data source, eg. each DataRow in the DataRowCollection. |
| delegate SlidingMenuGroupEventHandler | | but how to capture these events. With the SlidingMenuGroupEventHandler delegate you hook up a listener function that will be called each time the GroupDataBound event is raised, that is: the listener function will be called upon each DataRow in the DataRowCollection. |
| EventArgs SlidingMenuGroupEventArgs | | this object is transfered by the GroupDataBound event to your listener function, this object holds information about the specific event eg. the index of the DataRow (in the DataRowCollection) on which the event was raised. |
|
|
Semi-code C# part |
| 0. | public class MyPage : System.Web.UI.Page | | 1. | { | | 2. | | ... | | 3. | | //declaring MySM as a variable of type SlidingMenu | | 4. | | protected Webmodelling.Controls.Menues.SlidingMenu MySM; | | 5. | | ... | | 6. | | private void Page_Load(object sender, System.EventArgs e) | | 7. | | { | | 8. | | | ... | | 9. | | | //delegate the GroupDataBound event to the listener function MySM_GroupDataBound (each time GroupDataBound is raised, MySM_GroupDataBound is called | | 10. | | | MySM.GroupDataBound += new Webmodelling.Controls.Menues.SlidingMenuGroupEventHandler(MySM_GroupDataBound); | | 11. | | | MySM.DataSource = [IEnumerable]; //setting a data source, eg. a DataRowCollection (myDataTable.Rows) | | 12. | | | MySM.DataBind(); //raise the GroupDataBound event on each DataRow in the DataRowCollection | | 13. | | | ... | | 14. | | } | | 15. | | | | 16. | | //the listener function (also called event handler) must have this predifined signature, notice the SlidingMenuGroupEventArgs | | 17. | | protected void MySM_GroupDataBound(object sender, Webmodelling.Controls.Menues.SlidingMenuGroupEventArgs e) | | 18. | | { | | 19. | | | DataRowCollection drcSource = (DataRowCollection)MySM.DataSource; //getting a reference to the data source, here a DataRowCollection | | 20. | | | | | 21. | | | //the SlidingMenuGroupEventArgs e GroupHeader property is a reference to the header template instantiated upon the current DataRow | | 22. | | | Label lblHeader = (Label)e.GroupHeader.FindControl("lblHeader"); | | 23. | | | Label lblCanvas = (Label)e.GroupCanvas.FindControl("lblCanvas"); | | 24. | | | | | 25. | | | //the SlidingMenuGroupEventArgs e also have a GroupIndex property, which is the index of the DataRow that this function is currently called upon | | 26. | | | lblHeader.Text = (string)drcSource[e.GroupIndex]["myField1"]; | | 27. | | | lblCanvas.Text = (string)drcSource[e.GroupIndex]["myField2"]; | | 28. | | | | | 29. | | | //if the header text have a special value [some value], then do some different style | | 30. | | | if ((string)drcSource[e.GroupIndex]["myField1"] == "[some value]") | | 31. | | | { | | 32. | | | | //the GroupHeader property of the SlidingMenuGroupEventArgs of course have a reference to the Style object for that GroupHeader | | 33. | | | | e.GroupHeader.GroupHeaderStyle.Height = "30px"; | | 34. | | | | e.GroupHeader.GroupHeaderStyle.OpenThisGroupAtStartup = true; | | 35. | | | } | | 36. | | } | | 37. | } |
|
|
Semi-code C# part discussion |
| At line 4 the SlidingMenu instance MySM is declared. Look at the Semi-code XML part line 0, there I gave the SlidingMenu the Id="MySM" (the actually instantiation of MySM happens then ASP.NET parse the XML/HTML, line 4 is only declaring a variable). |
At line 10 an eventhandler "MySM_GroupDataBound"
is hooked up (delegated) as a listener for the SlidingMenu GroupDataBound
event through instantiating a delegate class "SlidingMenuGroupEventHandler". The
eventhandler name "MySM_GroupDataBound" can be any name, but the naming
convention is [Control instance name]_[event name].
Alternatively to write the code on line 10 yourself, it is also possible to double click the GroupDataBound
event in the Event properties for a SlidingMenu. Simply in design-view
choose a SlidingMenu, view the Properties window and set it in Event mode
and double click the GroupDataBound - Visual Studio will now delegate the event
automatically (you can see it in the InitializeComponent function inside the
"Web Form Designer generated code"). If you choose to let Visual Studio hook up
the event automatically, Visual Studio will at the same time also write the
eventhandler signature on line 17 (but you still have to provide the body of
the eventhandler - line 19 to 34 - of course). |
At line 11 I have set the data source, this data source must implement the IEnumerable Interface. A lot of data oriented classes of .Net do that, eg. the DataRowCollection. Line 11 could therefore look like:
MySM.DataSource = myDataTable.Rows; |
| At line 12 the most important concept is exposed, the databinding. Then you call DataBind() on any ASP.NET Control supporting data binding (and any 3. party WebControl that follow this scheme), internally in the Control, there will be a loop on the data source - if the data source is a DataRowCollection, the WebControl will loop through each DataRow of the DataRowCollection and for each DataRow raise the GroupDataBound event (the name of the event is different for each WebControl) and construct an object of basic type EventArgs (SlidingMenu - SlidingMenuGroupEventArgs) holding information relevant to the current item (DataRow) in the data source (DataRowCollection), making this information available in the event handler function, which you write yourself. |
| At line 17 throughout line 36 you have the event handler (the listener function). Line 17 is actually the signature of the event handler and this signature cannot be changed (except for the name MySM_GroupDataBound), the signature is defined by SlidingMenu or more precisely the SlidingMenuGroupEventHandler delegate, however the SlidingMenuGroupEventHandler delegate follow the standard rules of .Net delegates. |
| I want to talk a little more about the SlidingMenuGroupEventArgs you see in the event handler signature. This object contains several references of information connected to the current data item (DataRow). In general .Net databinding event handling, the two most important references the EventArgs parameter holds is the Item and the Item.ItemIndex. SlidingMenu departs slightly from this naming standard (it is not impossible to follow it and indeed the code have already been made, but it does not fit the concepts of the SlidingMenu very well). Instead the ItemIndex is a direct property of the SlidingMenuGroupEventArgs as well as the references to the templates within one Group are direct properties of the SlidingMenuGroupEventArgs. |
| At line 22 I find the Label Control within the header template instantiated for the current data item (DataRow). Remember both the <HeaderTemplate> & <CanvasTemplate> is instantiated for each item (DataRow) in the data source. |
|
| The C# semi-code above describes only the basics about databinding, it can be far more complex, eg. the
Databind Example in How to Code is in detail discussing a complex example
there the CanvasTemplate is used as a naming container for a serie of
DataGrid's, one DataGrid for each item in the SlidingMenu DataSource.
These DataGrid's each have their own data source, though connected to the data
source of the SlidingMenu through a relational key structure. Otherwise you can search the Examples Section for more advanced databinding. |
|