Custom macros are a powerful feature in CMS development that extend the functionality of custom hooks, allowing CMS Administrators to execute scripts manually without needing a triggering event. ​ This capability is particularly useful for automating labor-intensive processes and enhancing the maintenance of CMS websites. ​ 

What are Custom Macros? ​ 

Custom macros are scripts that can be triggered manually from the CMS interface, specifically from Administration > Maintenance > Custom Hooks > Custom Macros. ​  

Custom macros are defined in the custom hooks file located at [Drive:]\[path-to-cms-site-instance]\App_Data\xml\Custom in your CMS. The file is visible from within the CMS at Administration > Maintenance > Custom Hooks > Hooks - but can only be edited directly by opening the file with an editor from the file system. 

Creating Custom Macros 

Within the custom hooks file, custom macros are placed at the bottom after the #endregion comment. By default, the CMS automatically provides the following custom macros as samples: 

• Send a Message 
  When executed, the custom macro function sends a simple message to the CMS. 
• Count 
  When executed, the custom macro function runs a count, starting from one and ending at twenty. 

These can be used to help guide you in creating new custom macros of your own. 

The following template is used to create custom macros. 

public void MyFunction(IUserWriteSession session) {} 

The name and description will appear in the CMS next to the Execute button. Change them to help identify the purpose of your macro. 

 The function name should be unique within your macros and always takes the IUserWriteSession parameter. 

Create as many macros as necessary, save the custom hooks file, and the macros will display in the macro area of the CMS on next refresh of the browser. 

Messaging in Custom Macros ​ 

Custom macros can utilize the CSAPI's messaging system, which is also new in Ingeniux CMS 10.6, to send alerts to users. ​ The session.CustomMessenger.Alert() method is commonly used, allowing developers to communicate with users without interrupting their actions. ​ This method takes parameters for the title, message content, and an optional boolean to send the message to all users. 

Considerations for Custom Macros ​ 

When developing custom macros, it's important to consider the following: 

Hardcoding: Scripts may need to reference specific CMS elements, which can change over time. ​ Thorough testing and error logging are essential to handle potential issues. ​ 

User Input: Since custom macros do not have direct user input fields, developers may need to use settings files or other methods to gather necessary information from users. 

Examples of Custom Macros ​ 

Custom macros can significantly streamline tasks. ​ For instance, a macro can fill in missing components across multiple pages based on a template from the home page, or create an entire information architecture from an XML document. ​ These examples demonstrate how macros can automate repetitive tasks, saving time and reducing errors. ​ 

Use Cases 

Bulk Updates to Content 

• Use Case: Updating a specific field across hundreds of pages. 
• Task Automated: A macro could update a field without manual edits to each page. 
• Example Action: Locate pages that were created without a site control and fill in the proper site control for the page. 

XML-Based Information Architecture Generation 

• Use Case: Rapidly creating a new site structure. 
• Task Automated: A macro could import an XML file representing a site structure and use it to build out the CMS site tree with appropriate taxonomy, schemas, and pages. 
• Example Action: Generate a multi-level site tree from an XML file, complete with preconfigured page types. 

Content Archiving 

• Use Case: Archiving old or unused content. 
• Task Automated: A macro could search for pages that haven't been updated within a set timeframe and move them to an "Archived" section in the CMS or flag them for review. 
• Example Action: Identify pages older than 2 years and update their status, workstate, location in the Site Tree or taxonomy to mark them as archived. 

Automated Workflows 

• Use Case: Automating repetitive publishing or maintenance workflows. 
• Task Automated: A macro could perform a series of actions, such as checking the status of pages, publishing approved ones, and notifying users of any errors. 
• Example Action: Publish all pages marked "Ready for Publishing" in a specific section and send alerts if any fail. 

Conclusion 

Custom macros offer a flexible and efficient way to enhance CMS functionality. ​ By allowing scripts to be executed manually, they provide a solution to the limitations of custom hooks. ​ With the ability to interact with the CSAPI and send messages to users, custom macros are a valuable tool for automating complex tasks and maintaining CMS websites. ​ Developers can unlock their full potential by exploring CSAPI documentation and training resources. ​