Adding settings to breadcrumb gadgets
You can add properties to the breadcrumbs gadget to allow you to control additional aspects of its behavior while editing a page or page template. For example, you might want to add an option to hide the breadcrumbs gadget when on the home page.
You can use this same approach to add other settings to other gadgets.
To add settings to a breadcrumbs gadget, follow these steps:
- Enable theme overrides and download the theme files.
- We'll create a new version of the gadget, preserving the original version, just in case. Under the /Gadgets folder within the downloaded theme files, create a BreadCrumbsAlternative folder.
- Copy all content from the /Gadgets/BreadCrumbs folder to the new /Gadgets/BreadCrumbsAlternative folder.
- Open the /Gadgets/BreadCrumbsAlternative/MainConfig.cfg file and edit the gadget description, so we can easily tell the difference between normal and alternative gadgets. The file should now look something like this:
<Gadget> <Title>Breadcrumbs Alternative</Title> <ShortTitle></ShortTitle> <Description>Current location within the menu hierarchy - alternative version</Description> <Icon>BreadCrumbsIcon.png</Icon> <IconSmall>BreadCrumbsIconSmall.png</IconSmall> <Module>BreadCrumbsModule</Module> <ClassName>WaGadgetBreadcrumbs</ClassName> <Dedication>Navigational</Dedication> </Gadget>
- Next, let's add the new setting to the gadget settings layout config file. Open SettingsLayout.cfg within the /Gadgets/BreadCrumbsAlternative folder, then add – before all other sections under
<SettingsLayout> – the following section:
<Section title="New Settings"> <Control settingName="ShowOnHome" title="Show gadget on home page" titlePosition="Left" titleWidth="247"/> </Section>
Here, we define the ShowOnHome field and set its alignment, title, and the title's width.
- Now, its time to define the new setting type. To do so, we'll create a Settings.cfg file within the Gadgets/BreadCrumbsAlternative folder consisting of the following code:
<Settings> <Setting name="ShowOnHome" type="boolean" defaultValue="true" initialValue="true" width="20"/> </Settings>
Here, we define ShowOnHome as boolean (it can be true or false and graphically represented by a checkbox), set its default value and initial value, and specify the width of its checkbox. Note we use the same names as in SettingsLayout.cfg.
- Next, we need to connect the setting to the gadget's HTML code. To do so, open GadgetTemplate.tpl within the Gadgets/BreadCrumbsAlternative folder for editing.
- All elements for building a chain of breadcrumb links are stored in Model.Items collection. If we have only one item in a collection, it means that we're at root level – the home page – and we can check the option we added to the gadget settings. We should render items only if item is not the only one in the items collection, or if it is the only item but the Show on home page option is checked. We'll add this condition checking in the beginning of our iterator cycle, so that the entire gadget code will look like this::
<$control.StyledWrappers(GadgetBegin = "true", GadgetTitleBegin = "true", GadgetTitleText = Model.Appearance.Title, GadgetTitleEnd = "true", GadgetBodyBegin = "true")$>
<$if (!it.IsSingleItem || Model.Settings.ShowOnHome)$>
<$control.StyledWrappers(GadgetBodyEnd = "true", GadgetEnd = "true")$>
- Save the changes you have made to the GadgetTemplate.tpl file.
- Upload all new and modified files and folders to the appropriate folder under the Theme_Overrides folder on your site from the Files screen or using WebDAV.
- Log out of admin mode then log back in.
- Return to the Theme overrides screen and rebuild the theme.
You can now open a page for editing and find the new gadget in the gadgets list under Custom Group.
After dragging the gadget to the page, you can modify the new gadget settings.