Skip to content

HOW_TO_ADD_NEW_TOOL.md

Latest commit

 

History

History
449 lines (356 loc) · 12.9 KB

HOW_TO_ADD_NEW_TOOL.md

File metadata and controls

449 lines (356 loc) · 12.9 KB

How to Add a New Tool

📋 Quick Start Checklist

  • Create the JSP file
  • Add tool to tools-database.json
  • Add tool to sidebar.jsp (if needed)
  • Implement modern UI following TOOL_PAGE_IMPLEMENTATION_GUIDE.md
  • Add SEO metadata
  • Test functionality
  • Test mobile responsiveness
  • Test dark/light themes
  • Verify search indexing

Step-by-Step Guide

Step 1: Create the JSP File

  1. Choose a filename

    • Use descriptive, lowercase names with hyphens
    • Examples: my-new-tool.jsp, advanced-calculator.jsp
    • Place in src/main/webapp/

  2. Create the file structure

    <%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8" %>
<!DOCTYPE html>
<html lang="en">
<head>
    <!-- Include modern head components -->
    <%@ include file="modern/components/seo-head.jsp" %>
    <%@ include file="modern/components/nav-header.jsp" %>
</head>
<body>
    <!-- Your tool content here -->
    
    <!-- Include footer and scripts -->
    <%@ include file="modern/components/footer.jsp" %>
</body>
</html>

  3. Reference existing tools

    • Look at CipherFunctions.jsp for a complete example
    • Check modern/templates/tool-page-base.jsp for base structure
    • Review modern/examples/tool-page-example.jsp for patterns

Step 2: Add Tool to Database

  1. Open src/main/webapp/modern/data/tools-database.json

  2. Add your tool entry in the tools array:

    {
  "name": "Your Tool Name",
  "url": "your-tool.jsp",
  "category": "Appropriate Category",
  "keywords": "keyword1 keyword2 keyword3",
  "description": "Your Tool Name - Free online [category] tool"
}

  3. Choose the correct category from existing categories:

    • Security & PKI
    • Cryptography
    • Network Tools
    • Data Converters
    • DevOps & Infrastructure
    • Developer Tools
    • Blockchain & Crypto
    • File Sharing
    • Finance
    • Mathematics
    • Chemistry
    • Physics
    • Machine Learning
    • Media Tools
    • Document Tools
    • Productivity
    • Health
    • Legal & Compliance

  4. Update metadata:

    • Increment totalTools count
    • Update lastUpdated timestamp
    • Ensure category exists in categories array (add if new)

  5. Example entry:

    {
  "name": "Advanced JSON Parser",
  "url": "advanced-json-parser.jsp",
  "category": "Developer Tools",
  "keywords": "json parser validator beautifier developer tools",
  "description": "Advanced JSON Parser - Free online developer tools tool"
}

Step 3: Add to Sidebar (Optional)

If you want the tool in the sidebar navigation:

  1. Open src/main/webapp/sidebar.jsp

  2. Find the appropriate category section

  3. Add your tool link:

    <li><a href="your-tool.jsp">Your Tool Name</a></li>

Step 4: Implement Modern UI

Follow the TOOL_PAGE_IMPLEMENTATION_GUIDE.md for detailed implementation:

Key Requirements:

  1. Include Modern Components

    <!-- In <head> -->
<%@ include file="modern/components/seo-head.jsp" %>

<!-- In <body> -->
<%@ include file="modern/components/nav-header.jsp" %>
<%@ include file="modern/components/seo-tool-page.jsp" %>

  2. Use Design System CSS

    <link rel="stylesheet" href="<%=request.getContextPath()%>/modern/css/design-system.css">
<link rel="stylesheet" href="<%=request.getContextPath()%>/modern/css/tool-page.css">

  3. Include Common Utilities

    <script src="<%=request.getContextPath()%>/modern/js/tool-utils.js"></script>

  4. Choose Layout (see Layout Decision Guide in TOOL_PAGE_IMPLEMENTATION_GUIDE.md):

    • Single Column: Most tools (sequential workflow)
    • Two Column: Side-by-side input/output
    • Three Column: Complex tools with multiple inputs/outputs

  5. Add Result Placeholder

    <div id="resultArea" class="result-area">
    <div class="result-placeholder">
        <span class="placeholder-icon">✨</span>
        <p class="placeholder-text">Results will appear here</p>
    </div>
</div>

  6. Implement Error Handling

    // Use tool-utils.js functions
ToolUtils.showError('Error message', 'resultArea');
ToolUtils.showSuccess('Success message', 'resultArea');

Step 5: Add SEO Metadata

  1. Include SEO Component

    <%@ include file="modern/components/seo-tool-page.jsp" %>

  2. Pass Parameters (in your JSP):

    <%
    String toolName = "Your Tool Name";
    String toolDescription = "Detailed description of what your tool does";
    String toolCategory = "Developer Tools";
    String toolKeywords = "keyword1, keyword2, keyword3";
%>
<jsp:include page="modern/components/seo-tool-page.jsp">
    <jsp:param name="toolName" value="<%=toolName%>"/>
    <jsp:param name="toolDescription" value="<%=toolDescription%>"/>
    <jsp:param name="toolCategory" value="<%=toolCategory%>"/>
    <jsp:param name="toolKeywords" value="<%=toolKeywords%>"/>
    <jsp:param name="toolImage" value="logo.png"/> <!-- Optional: defaults to logo.png -->
</jsp:include>

    Image Parameter Options:

    • "logo.png" (default) - Uses /images/site/logo.png
    • "custom-image.png" - Uses /images/site/custom-image.png
    • "/images/custom/path.png" - Absolute path from site root
    • "https://example.com/image.png" - Full URL

  3. Add JSON-LD Schema (automatically included via seo-tool-page.jsp)

Step 6: Add Related Tools (Optional)

Include related tools section at the bottom of your tool page:

<%@ include file="modern/components/related-tools.jsp" %>

Or with parameters:

<jsp:include page="modern/components/related-tools.jsp">
    <jsp:param name="currentToolUrl" value="your-tool.jsp"/>
    <jsp:param name="category" value="Developer Tools"/>
    <jsp:param name="limit" value="6"/>
</jsp:include>

Step 7: Add Support Section (Optional)

Include support section for donations/social:

<%@ include file="modern/components/support-section.jsp" %>

Step 8: Testing Checklist

Before deploying, test:

Functionality

  • Tool works correctly
  • Form submission works
  • Error handling displays properly
  • Success messages appear
  • Copy to clipboard works
  • Share URL works
  • URL parameters load correctly

UI/UX

  • Mobile responsive (test on phone)
  • Tablet layout works
  • Desktop layout works
  • Dark mode works
  • Light mode works
  • Icons display correctly
  • Animations work smoothly
  • Loading states appear

SEO & Performance

  • Page title is correct
  • Meta description is present
  • JSON-LD schema validates
  • Page loads quickly
  • No console errors
  • Images optimized

Navigation

  • Tool appears in search results
  • Tool appears in category menu
  • Tool appears in mobile drawer
  • Tool link works from navigation

Accessibility

  • Keyboard navigation works
  • Screen reader compatible
  • ARIA labels present
  • Focus management works
  • Color contrast sufficient

Quick Reference

File Locations

File Location
Tool JSP src/main/webapp/your-tool.jsp
Tools Database src/main/webapp/modern/data/tools-database.json
Sidebar src/main/webapp/sidebar.jsp
Implementation Guide TOOL_PAGE_IMPLEMENTATION_GUIDE.md
SEO Guide src/main/webapp/modern/SEO_IMPLEMENTATION_GUIDE.md

Common Components

Component Path Purpose
SEO Head modern/components/seo-head.jsp Meta tags, CSS, fonts
Navigation modern/components/nav-header.jsp Header navigation
SEO Tool Page modern/components/seo-tool-page.jsp Tool-specific SEO
Related Tools modern/components/related-tools.jsp Related tools section
Support Section modern/components/support-section.jsp Support/donation section

CSS Files

File Purpose
modern/css/design-system.css Design tokens, variables
modern/css/tool-page.css Tool page styles
modern/css/navigation.css Navigation styles
modern/css/dark-mode.css Dark theme styles

JavaScript Files

File Purpose
modern/js/tool-utils.js Common utilities (copy, share, errors)
modern/js/dark-mode.js Theme switching
modern/js/search.js Search functionality
modern/js/categories-menu.js Category navigation

Example: Complete Tool Page

<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8" %>
<%
    String toolName = "My New Tool";
    String toolDescription = "A tool that does something useful";
    String toolCategory = "Developer Tools";
    String toolKeywords = "tool, utility, developer";
%>
<!DOCTYPE html>
<html lang="en">
<head>
    <%@ include file="modern/components/seo-head.jsp" %>
    
    <jsp:include page="modern/components/seo-tool-page.jsp">
        <jsp:param name="toolName" value="<%=toolName%>"/>
        <jsp:param name="toolDescription" value="<%=toolDescription%>"/>
        <jsp:param name="toolCategory" value="<%=toolCategory%>"/>
        <jsp:param name="toolKeywords" value="<%=toolKeywords%>"/>
        <jsp:param name="toolImage" value="logo.png"/> <!-- Optional -->
    </jsp:include>
    
    <link rel="stylesheet" href="<%=request.getContextPath()%>/modern/css/design-system.css">
    <link rel="stylesheet" href="<%=request.getContextPath()%>/modern/css/tool-page.css">
</head>
<body>
    <%@ include file="modern/components/nav-header.jsp" %>
    
    <main class="tool-page-container">
        <div class="tool-page-header">
            <h1 class="tool-page-title"><%=toolName%></h1>
            <p class="tool-page-description"><%=toolDescription%></p>
            <div class="tool-badges">
                <span class="tool-badge">Free</span>
                <span class="tool-badge">No Registration</span>
            </div>
        </div>
        
        <div class="tool-page-content">
            <form id="toolForm" class="tool-form">
                <div class="form-group">
                    <label for="inputField">Input Field</label>
                    <input type="text" id="inputField" class="form-input" required>
                </div>
                
                <button type="submit" class="btn-primary">Process</button>
            </form>
            
            <div id="resultArea" class="result-area">
                <div class="result-placeholder">
                    <span class="placeholder-icon">✨</span>
                    <p class="placeholder-text">Results will appear here</p>
                </div>
            </div>
        </div>
    </main>
    
    <%@ include file="modern/components/related-tools.jsp" %>
    <%@ include file="modern/components/support-section.jsp" %>
    
    <script src="<%=request.getContextPath()%>/modern/js/tool-utils.js"></script>
    <script src="<%=request.getContextPath()%>/modern/js/dark-mode.js"></script>
    <script>
        document.getElementById('toolForm').addEventListener('submit', function(e) {
            e.preventDefault();
            const input = document.getElementById('inputField').value;
            
            // Your tool logic here
            const result = processInput(input);
            
            // Display result
            ToolUtils.showResult(result, 'resultArea');
        });
    </script>
</body>
</html>

Troubleshooting

Tool not appearing in search

  • ✅ Check tools-database.json entry is correct
  • ✅ Verify URL matches exactly
  • ✅ Clear browser cache
  • ✅ Check console for errors

Tool not in navigation menu

  • ✅ Verify category exists in categories array
  • ✅ Check tool count matches
  • ✅ Hard refresh browser (Ctrl+Shift+R)

Styling issues

  • ✅ Include all required CSS files
  • ✅ Check CSS file paths are correct
  • ✅ Verify design system variables are loaded

Functionality not working

  • ✅ Check JavaScript console for errors
  • ✅ Verify tool-utils.js is loaded
  • ✅ Test in different browsers
  • ✅ Check jQuery is loaded (if using)

Need Help?

  • 📖 Read TOOL_PAGE_IMPLEMENTATION_GUIDE.md for detailed implementation
  • 📖 Read src/main/webapp/modern/SEO_IMPLEMENTATION_GUIDE.md for SEO details
  • 🔍 Check existing tools like CipherFunctions.jsp for examples
  • 🎨 Review modern/templates/tool-page-base.jsp for base structure

Summary

  1. Create JSP file → src/main/webapp/your-tool.jsp
  2. Add to database → tools-database.json
  3. Add to sidebar → sidebar.jsp (optional)
  4. Implement UI → Follow TOOL_PAGE_IMPLEMENTATION_GUIDE.md
  5. Add SEO → Use seo-tool-page.jsp component
  6. Test everything → Use testing checklist
  7. Deploy → Verify in production

That's it! Your tool is now part of the system. 🎉