Config files explained

Config-files explained

Figuring out all the possibilities you can do with Config-files might be tedious process. This small guide gets you started on adding and removing items to/from the GUI. For the complete config-file you can refer to any extension contained in this project.

Adding new items

It is quite flexible where and how you add your extensions to the GUI using the config-files. For the same reason it might take a while to figure out all the possibilities you can do. The common use cases are described below.

To Context Menus

<ext:contextmenus>
	<ext:add>
		<ext:extension name="NameOfExtension" assignid="" insertbefore="NameOfControl">
			<ext:menudeclaration>
			<!-- Creates Context Menu item that expands to one more other menu items e.g. Publishing -> Publish / Unpublish -->
				<cmenu:ContextMenuItem id="uniqueId1" name="Title of Expanding Menu Item">
					<cmenu:ContextMenuItem id="uniqueId2" name="Title of Command Under Menu Item" command="NameOfTheCommand1"/>
				</cmenu:ContextMenuItem>
			<!-- Creates Context Menu item on the first level -->
			<cmenu:ContextMenuItem id="uniqueId3" name="Title Of Command" command="NameOfTheCommand2"/>
			</ext:menudeclaration>
			<!-- Apply-element contains the views to which the extension should be inserted -->
			<ext:apply>
				<ext:view name="NameOfView"/>
			</ext:apply>
		</ext:extension>
	</ext:add>
</ext:contextmenus>

To Ribbon-toolbar

<ext:ribbontoolbars>
	<ext:add>
		<ext:extension pageid="NameOfTab" groupid="NameOfGroup" name="Subtitle of Ribbon-button" assignid="UniqueId" insertbefore="UniqueIdOfSomeButton">
			<ext:command>NameOfCommand</ext:command>
			<ext:title>Tooltip text for Ribbon-button</ext:title>
			<!-- Apply-element contains the views (and controls) to which the extension should be inserted -->
			<ext:apply>
				<ext:view name="NameOfView">
					<ext:control id="NameOfControl"/>
				</ext:view>
			</ext:apply>
		</ext:extension>
	</ext:add>
</ext:ribbontoolbars>

Add references to your implementation of extension

So now all you need to do is to add references to your code in the config-file.

<cfg:groups>
	<cfg:group name="YourExtensions.Extension">
		<cfg:fileset>
			<cfg:file type="script">/client/commands/YourExtensionLogic.js</cfg:file>
			<cfg:file type="style">/client/dependencies/styles/YourExtensionStyle.css</cfg:file>
			<cfg:file type="script">/client/dependencies/jquery.js</cfg:file>
		</cfg:fileset>
		<cfg:dependencies>
		    <!-- Dependencies to other groups, either custom built or standard ones -->
			<cfg:dependency>Tridion.Web.UI.Editors.CME</cfg:dependency>
			<cfg:dependency>Tridion.Web.UI.Editors.CME.commands</cfg:dependency>
			<!-- Resources could contain jQuery, stylesheets etc. which are now included in this group -->
			<cfg:dependency>YourExtensions.Resources</cfg:dependency>
		</cfg:dependencies>
	</cfg:group>
</cfg:groups>

...And to map the commands to the implementations

<commands>
	<cfg:commandset id="YourExtensions.Commands">
	    <!-- "YourExtensions" is namespace and YourCommand is a function that returns a class instance of your command. -->
		<cfg:command name="YourCommand" implementation="YourExtensions.YourCommand"/>
	</cfg:commandset>
</commands>

Removing existing items

From Context Menus

The easiest and most flexible way to remove items from context menus is to extend an existing control and create some logic to _isAvailable-function. When the function returns false the command will be removed from the context-menu. The simplest case is described below (the command is hidden always):

    YourExtension.prototype._isAvailable = function (selection, pipeline) {
       return false;
    };

From Ribbon-toolbar

Contrary to context menu-items you can't remove the items from Ribbon-toolbar conditionally from JS-code (they only get disabled). Only way to remove them is to use the config-file.

<ext:ribbontoolbars>
   <ext:remove>
      <ext:extension id="IdOfExtension" name="NameOfExtension">
         <!-- Apply-element contains the views (and controls) from which the extension should be removed -->
         <ext:apply>
            <ext:view name="NameOfView">
               <ext:control id="IdOfControl" />
            </ext:view>
            <!-- If you want to remove the same extension from several views or controls just add more view/control-elements -->
         <ext:apply>
      </ext:extension>
   </ext:remove>
</ext:ribbontoolbars>

Extending existing items

Extending existing commands is a breeze. The steps to create an extension that extends some existing command are exactly the same as building a new extension with one exception. Instead of using ext:add-element you just add one or more elements under ext:commandextensions and define what to extend and with which command.

<ext:commandextensions>
   <ext:commands>		
      <ext:command name="CommandThatYouWantToExtend" extendingcommand="TheCommandThatExtends" />
   </ext:commands>
   <ext:dependencies>
      <cfg:dependency>CommandsExtensions.Commandset</cfg:dependency>
   </ext:dependencies>
</ext:commandextensions>

How to figure out the IDs of elements

The easiest way to check the values of names/IDs is to inspect HTML. The pictures below show where you should look for them.

<ext:remove>
   <ext:extension id="PreviewBtn" name="PreviewBtn">
      <ext:apply>
         <ext:view name="PageView">
            <ext:control id="ItemToolbar" />
         </ext:view>
      <ext:apply>
   </ext:extension>
</ext:remove>

Another example:

<ext:add>
	<ext:extension pageid="HomePage" groupid="EditGroup" name="View In Staging" assignid="ViewInStagingBtn" insertbefore="PreviewBtn">
		<ext:command>ViewInStaging</ext:command>
		<ext:title>View In Staging</ext:title>
		<ext:apply>
			<ext:view name="DashboardView">
				<ext:control id="DashboardToolbar"/>
			</ext:view>
		</ext:apply>
	</ext:extension>
</ext:add>