[DOCU-77] Creating a custom control Created: 13/Dec/10  Updated: 29/Aug/11  Resolved: 29/Aug/11

Status: Closed
Project: Documentation
Component/s: content
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Neutral
Reporter: Antti Hietala Assignee: Suzanne Deprez
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

Improve the Creating a custom control article. http://documentation.magnolia-cms.com/cookbook/creating-a-custom-control.html

Resources:



 Comments   
Comment by Suzanne Deprez [ 29/Jun/11 ]

Changes were activated.

Comment by Antti Hietala [ 20/Jul/11 ]

Reviewed.

Creating a custom control

  • Start with an introduction. Why and when do I need a custom control? List three examples of custom controls that work with Magnolia and explain what problem they solved. Motivate the reader.

Use existing controls

  • "There are two types of provided controls that can be used: module and DAM." Why such a division? DAM control is provided by the STK module so how is it different from other module controls?
  • "Configuration > /modules/module_name/controls" Notation rules for paths are now in Documentation Style Guide. Please apply.
  • "The modules that include controls..." I think it's enough to mention adminInterface and standard-templating-kit as examples of modules that provide controls. Drop the Magnolia CMS version number as we would need to keep updating it.
  • In "To create a customized control":
    • Step 2 is difficult to understand. Where should I create the content node? The screenshot does not highlight the content node. How should I name the content node?
    • Step 2: Are the bullets alternatives to each other? Custom control wiki page suggests they are. Not clear here.
    • Step 2, bullet 2: "as shown in the image above" The image immediately above does not show the controls folder. Which image does the text refer to?
    • Step 2, bullet 2: "The new control can then be used anywhere by adding a content node to a dialog for a control with a child node controlType with a value set to the name of the new control." Complicated sentence, hard to follow.
  • "Custom Control Training provides additional information...". Readers don't have access to the training namespace in the wiki. Only people who paid to attend the training do. So you can't link there. The wiki page has good content and is well written, such as "1. Subclass the most alike existing dialog control." That is a clear idea for the reader to follow. Replicate.
  • "A DialogInclude customization example is also provided." What is DialogInclude? Why should I use it? What problem does it solve? Can't just link to something without explaining the benefit/relevance/difference/uniqueness...
  • "Discussions of the following examples..." Nice list. Make it clear that these are not ready-made examples or official docs. Some are just forum posts. Perception of bad documentation stems partly from not making clear the difference between official docs and community-contributed content.

Create a new control

  • Isn't this procedure exactly the same as in "Use existing module control" above? If so, is the whole existing vs. new control structure moot?

User comments

  • What do you think the user who commented "Maybe a screenshot of JCR structure should help" wants to see? What detail about custom controls would a JCR view make easier to understand?
Comment by Suzanne Deprez [ 28/Jul/11 ]

Was not able to find auto complete search control in wiki. Added other known controls to the introduction.

My intent was to differentiate because there are differences in how to customize a dam control vs. other controls. I've reworked that section to hopefully improve.

I've reworked the "To create a customized control" procedure. The bullets actually were alternatives in showing how to specify a customized control class in AdminCentral.

I think the JCR comment is basically asking for some AdminCentral screenshots showing where/how controls are set. I think the added screenshots will help.

Activated changes.

Generated at Mon Feb 12 01:05:42 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.