cscase
September 8th, 2013, 03:45
Hey all,
I've been reading about the new merge functionality in 3.0 and wanted to run a few questions by you, and maybe hopefully round up some of the information I've read in various different posts into one place as well as get some clarification on how this feature works so those learning about 3.0 can have a starting point. I can update this post to reflect the info that is provided, if you all agree that that is helpful. Or, if this is all found somewhere else and I've merely overlooked it, please point me in the right dir!
I am a newbie to fiddling around under FG's hood, so some of what follows may elicit facepalms from the more experienced among you. I ask for your patient forebearance! :P
The release notes say:
Developer - Ruleset Layering
Ruleset layering support added via use of importruleset tag within base.xml file. Higher layers override lower layer objects (font, framedef, windowclass, template, etc.). Lower layers will be checked for files referenced in higher layer, but not included in higher layer.
Attribute merging supported in templates.
New merge attribute supported by controls and templates. Applied at referencing layer, and overrides mergerule attribute used at referenced layer.
Valid control/template merge attribute values are: merge/join (default), add, resetandadd, replace, and delete
Valid panel/windowclass merge attribute values are: replace (default), join, and delete
Valid die/customdie merge attribute values are: replace (default) and delete
When merging windowclass objects, nested scripts are supported. (i.e. accessible via super variable, similar to controls)
When merging windowclass sheetdata, the name attribute will be used instead of the tag name for matching.
When merging windowclass sheetdata, insertbefore attribute added to define alternate control order other than appending newly merged controls to end of control order.
So, if I create a new ruleset and put <importruleset source="CoreRPG" /> into my base.xml, then I'll get what's in the CoreRPG for any and everything that I don't explicitly override with new code, much like if I were writing an extension. Right?
To override a particular item, we use <merge = " " /> tags in our new code to specify how the new objects are to interact with the old code, right?
So, does this mean we can make overrides at an object level? We can leave everything in a given file just the same as in Core, but override a single class definition? That means we don't have to replace an entire file just to make one change in it. Am I still following correctly?
Example 1: Suppose you want to make changes to a windowclass charsheet_main in the CoreRPG ruleset. In CoreRPG, that's located at \campaign\record_char_main.xml. So, for your changes:
Where will you put them? Do you create a file called record_char_main.xml, and put it in the campaign folder, so that it's in the same place as the class you are modifying?
In your newly created .xml file, will you put ONLY the xml header, root tags, and your new version of the windowclass, including merge tags?
What if your change was something very small, like adding a <nodrag /> to the existing class and not replacing it entirely?
Are there times when merging and/or replacing are going to happen implicitly, and no merge tag is needed? What if I just include a totally new version of a given file, with no mention of merge in it. Does FG sub the whole file for the original? Are merge tags only needed when you want to replace something smaller than an entire file?
Example 2: Let's say you want to modify not a class, but a .png or a .lua? Let's take for example the background on the desktop. To keep it simple and focused on what's new in 3.0, let's say you're not moving decal or frame coordinates or anything, and just say you slapped a new icon exactly within the area of the original decal.
So, you would put your new desktop.png in your own ruleset folder, creating the location \graphics\frames\ and putting it there. Right?
Since the file name is the same as it was in CoreRPG, are you immediately all set, or do you need to go in somewhere to specify that the desktop.png file in the new ruleset takes precedence?
Or to come from another angle, say you want to make some changes in manager_char.lua. Do you just drop in your new .lua file? This file is specified in Core's base.xml in line 96. Would you need to put something in your own base.xml to let FG know to expect a new version of this script? If so, what would that look like?
Merge types:
The release notes mention several types of merges. Not all of them are valid for every kind of object, as described.
Merge/add: This is the default, the notes say. Does this mean that to specify this type, we can just say <merge /> without including = " "?
<merge = "add">: I'm going to guess and say that this tells FG that you're adding a new object or whatever to the existing code. Es verdad?
<merge = "resetandadd">: Can anyone offer a quick definition for this one?
<merge = "replace">: I would imagine this means you are just straight replacing the given entity as described in the original ruleset with a new definition?
<merge = "delete">: This means you want the entity stricken from the rolls and not used in the ruleset?
Other?
Any other basic info that should be mentioned about this functionality?
I've been reading about the new merge functionality in 3.0 and wanted to run a few questions by you, and maybe hopefully round up some of the information I've read in various different posts into one place as well as get some clarification on how this feature works so those learning about 3.0 can have a starting point. I can update this post to reflect the info that is provided, if you all agree that that is helpful. Or, if this is all found somewhere else and I've merely overlooked it, please point me in the right dir!
I am a newbie to fiddling around under FG's hood, so some of what follows may elicit facepalms from the more experienced among you. I ask for your patient forebearance! :P
The release notes say:
Developer - Ruleset Layering
Ruleset layering support added via use of importruleset tag within base.xml file. Higher layers override lower layer objects (font, framedef, windowclass, template, etc.). Lower layers will be checked for files referenced in higher layer, but not included in higher layer.
Attribute merging supported in templates.
New merge attribute supported by controls and templates. Applied at referencing layer, and overrides mergerule attribute used at referenced layer.
Valid control/template merge attribute values are: merge/join (default), add, resetandadd, replace, and delete
Valid panel/windowclass merge attribute values are: replace (default), join, and delete
Valid die/customdie merge attribute values are: replace (default) and delete
When merging windowclass objects, nested scripts are supported. (i.e. accessible via super variable, similar to controls)
When merging windowclass sheetdata, the name attribute will be used instead of the tag name for matching.
When merging windowclass sheetdata, insertbefore attribute added to define alternate control order other than appending newly merged controls to end of control order.
So, if I create a new ruleset and put <importruleset source="CoreRPG" /> into my base.xml, then I'll get what's in the CoreRPG for any and everything that I don't explicitly override with new code, much like if I were writing an extension. Right?
To override a particular item, we use <merge = " " /> tags in our new code to specify how the new objects are to interact with the old code, right?
So, does this mean we can make overrides at an object level? We can leave everything in a given file just the same as in Core, but override a single class definition? That means we don't have to replace an entire file just to make one change in it. Am I still following correctly?
Example 1: Suppose you want to make changes to a windowclass charsheet_main in the CoreRPG ruleset. In CoreRPG, that's located at \campaign\record_char_main.xml. So, for your changes:
Where will you put them? Do you create a file called record_char_main.xml, and put it in the campaign folder, so that it's in the same place as the class you are modifying?
In your newly created .xml file, will you put ONLY the xml header, root tags, and your new version of the windowclass, including merge tags?
What if your change was something very small, like adding a <nodrag /> to the existing class and not replacing it entirely?
Are there times when merging and/or replacing are going to happen implicitly, and no merge tag is needed? What if I just include a totally new version of a given file, with no mention of merge in it. Does FG sub the whole file for the original? Are merge tags only needed when you want to replace something smaller than an entire file?
Example 2: Let's say you want to modify not a class, but a .png or a .lua? Let's take for example the background on the desktop. To keep it simple and focused on what's new in 3.0, let's say you're not moving decal or frame coordinates or anything, and just say you slapped a new icon exactly within the area of the original decal.
So, you would put your new desktop.png in your own ruleset folder, creating the location \graphics\frames\ and putting it there. Right?
Since the file name is the same as it was in CoreRPG, are you immediately all set, or do you need to go in somewhere to specify that the desktop.png file in the new ruleset takes precedence?
Or to come from another angle, say you want to make some changes in manager_char.lua. Do you just drop in your new .lua file? This file is specified in Core's base.xml in line 96. Would you need to put something in your own base.xml to let FG know to expect a new version of this script? If so, what would that look like?
Merge types:
The release notes mention several types of merges. Not all of them are valid for every kind of object, as described.
Merge/add: This is the default, the notes say. Does this mean that to specify this type, we can just say <merge /> without including = " "?
<merge = "add">: I'm going to guess and say that this tells FG that you're adding a new object or whatever to the existing code. Es verdad?
<merge = "resetandadd">: Can anyone offer a quick definition for this one?
<merge = "replace">: I would imagine this means you are just straight replacing the given entity as described in the original ruleset with a new definition?
<merge = "delete">: This means you want the entity stricken from the rolls and not used in the ruleset?
Other?
Any other basic info that should be mentioned about this functionality?