Skip to content

Commit 914f065

Browse files
csharpfritzcsharpfritz
authored
Add new components and samples for CheckBox, DropDownList, Panel, Pla… (#304)
1 parent 65b49e3 commit 914f065

11 files changed

Lines changed: 1055 additions & 57 deletions

File tree

‎.github/skills/documentation/SKILL.md‎

Lines changed: 316 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -391,6 +391,305 @@ When creating sample pages in `samples/AfterBlazorServerSide/Components/Pages/Co
391391
}
392392
```
393393

394+
## Creating Sample Pages for Components
395+
396+
**CRITICAL**: Every documented component MUST have a corresponding sample page in the AfterBlazorServerSide project.
397+
398+
### Sample Page Structure and Location
399+
400+
Samples are located in `samples/AfterBlazorServerSide/Components/Pages/ControlSamples/[ComponentName]/`
401+
402+
The folder structure mirrors the documentation categories:
403+
- **Editor Controls**: `ControlSamples/[ComponentName]/`
404+
- **Data Controls**: `ControlSamples/[ComponentName]/`
405+
- **Validation Controls**: `ControlSamples/[ComponentName]/` (or `ControlSamples/Validations/`)
406+
- **Navigation Controls**: `ControlSamples/[ComponentName]/`
407+
- **Login Controls**: `ControlSamples/[ComponentName]/`
408+
409+
### Sample File Naming Conventions
410+
411+
1. **Basic Sample**: `Index.razor` - The main/default sample for the component
412+
- Route: `@page "/ControlSamples/[ComponentName]"`
413+
414+
2. **Additional Scenarios**: `[ScenarioName].razor` - Named after what they demonstrate
415+
- Route: `@page "/ControlSamples/[ComponentName]/[ScenarioName]"`
416+
- Examples: `Style.razor`, `Events.razor`, `JavaScript.razor`
417+
418+
3. **Navigation Helper**: `Nav.razor` - Optional component listing all samples for this component
419+
- Used to navigate between multiple samples for the same component
420+
421+
### Sample Page Required Structure
422+
423+
Every sample page MUST include:
424+
425+
1. **Route**: `@page "/ControlSamples/[ComponentName]"` or `@page "/ControlSamples/[ComponentName]/[Scenario]"`
426+
2. **PageTitle**: `<PageTitle>[ComponentName] - [Scenario]</PageTitle>`
427+
3. **Heading**: `<h1>[ComponentName] Sample</h1>` or `<h2>[ComponentName] - [Scenario]</h2>`
428+
4. **Description**: Brief explanation of what the sample demonstrates
429+
5. **Demo Section**: Working component implementation
430+
6. **Code Display**: Showing the markup and code being used (optional but recommended)
431+
432+
### Sample Page Template
433+
434+
```razor
435+
@page "/ControlSamples/[ComponentName]"
436+
@page "/ControlSamples/[ComponentName]/[Scenario]"
437+
438+
<PageTitle>[ComponentName] Sample</PageTitle>
439+
440+
<h2>[ComponentName] - [Scenario Description]</h2>
441+
442+
<p>[Brief description of what this sample demonstrates]</p>
443+
444+
@* Optional: Navigation to other samples for this component *@
445+
<Nav />
446+
447+
@* The working demo *@
448+
<div class="demo-section">
449+
<[ComponentName]
450+
Property1="value"
451+
Property2="@someValue"
452+
OnEvent="HandleEvent" />
453+
</div>
454+
455+
@* Optional but recommended: Show the results or state *@
456+
@if (!string.IsNullOrEmpty(Message))
457+
{
458+
<div class="result">@Message</div>
459+
}
460+
461+
@code {
462+
private string Message = "";
463+
464+
private void HandleEvent()
465+
{
466+
Message = "Event handled!";
467+
}
468+
}
469+
470+
<hr />
471+
472+
@* Optional: Display the code being used *@
473+
<p>Code:</p>
474+
<code>
475+
&lt;[ComponentName] Property1="value" OnEvent="HandleEvent" /&gt;
476+
</code>
477+
```
478+
479+
### Creating Samples for Different Scenarios
480+
481+
When a component has multiple features to demonstrate, create separate sample pages:
482+
483+
```
484+
ControlSamples/
485+
Button/
486+
Index.razor # Basic button usage
487+
Style.razor # Styling examples
488+
JavaScript.razor # JavaScript integration
489+
Nav.razor # Navigation between samples
490+
```
491+
492+
Each scenario page should focus on ONE specific feature or use case.
493+
494+
## Linking Samples in Navigation
495+
496+
**CRITICAL**: After creating sample pages, they MUST be added to the navigation tree.
497+
498+
### Update NavMenu.razor
499+
500+
Location: `samples/AfterBlazorServerSide/Components/Layout/NavMenu.razor`
501+
502+
Add `<TreeNode>` entries under the appropriate category section:
503+
504+
```razor
505+
<TreeNode Text="[Category] Components">
506+
507+
@* For a component with a single sample *@
508+
<TreeNode Text="[ComponentName]" NavigateUrl="/ControlSamples/[ComponentName]" />
509+
510+
@* For a component with multiple samples *@
511+
<TreeNode Text="[ComponentName]" NavigateUrl="/ControlSamples/[ComponentName]" Expanded="false">
512+
<TreeNode Text="Basic Usage" NavigateUrl="/ControlSamples/[ComponentName]" />
513+
<TreeNode Text="[Scenario 1]" NavigateUrl="/ControlSamples/[ComponentName]/[Scenario1]" />
514+
<TreeNode Text="[Scenario 2]" NavigateUrl="/ControlSamples/[ComponentName]/[Scenario2]" />
515+
</TreeNode>
516+
517+
</TreeNode>
518+
```
519+
520+
**Navigation Categories**:
521+
- `<TreeNode Text="Editor Components">` - For editor controls
522+
- `<TreeNode Text="Data Components">` - For data-bound controls
523+
- `<TreeNode Text="Validation Components">` - For validators
524+
- `<TreeNode Text="Navigation Components">` - For navigation controls
525+
- `<TreeNode Text="Login Components">` - For login/authentication controls
526+
527+
**Ordering**: Add new components alphabetically within their category.
528+
529+
### Example NavMenu Updates
530+
531+
```razor
532+
@* Adding a new editor control *@
533+
<TreeNode Text="Editor Components">
534+
<TreeNode Text="Button" NavigateUrl="/ControlSamples/Button">
535+
<TreeNode Text="JavaScript Click" NavigateUrl="/ControlSamples/Button/JavaScript" />
536+
<TreeNode Text="Style" NavigateUrl="/ControlSamples/Button/Style" />
537+
</TreeNode>
538+
<TreeNode Text="Label" NavigateUrl="/ControlSamples/Label" /> @* New component *@
539+
<TreeNode Text="TextBox" NavigateUrl="/ControlSamples/TextBox" />
540+
</TreeNode>
541+
542+
@* Adding a new data control with multiple samples *@
543+
<TreeNode Text="Data Components">
544+
<TreeNode Text="GridView" NavigateUrl="/ControlSamples/GridView" Expanded="false">
545+
<TreeNode NavigateUrl="/ControlSamples/GridView" Text="Simple GridView" />
546+
<TreeNode NavigateUrl="/ControlSamples/GridView/AutoGeneratedColumns" Text="Autogenerated Columns" />
547+
<TreeNode NavigateUrl="/ControlSamples/GridView/TemplateFields" Text="Template Fields" />
548+
</TreeNode>
549+
</TreeNode>
550+
```
551+
552+
## Updating the Home Page Component List
553+
554+
**CRITICAL**: After creating samples, update the component list on the home page.
555+
556+
Location: `samples/AfterBlazorServerSide/Components/Pages/ComponentList.razor`
557+
558+
Add links to the appropriate category column:
559+
560+
```html
561+
<div class="col-md-3">
562+
<h3>[Category] Controls</h3>
563+
<ul>
564+
<li><a href="/ControlSamples/ExistingComponent">ExistingComponent</a></li>
565+
<li><a href="/ControlSamples/NewComponent">NewComponent</a></li> @* Add alphabetically *@
566+
<li><a href="/ControlSamples/OtherComponent">OtherComponent</a></li>
567+
</ul>
568+
</div>
569+
```
570+
571+
**Categories**:
572+
- **Editor Controls** - Simple UI components (Button, Label, TextBox, etc.)
573+
- **Data Controls** - Data-bound components (GridView, Repeater, DataList, etc.)
574+
- **Validation Controls** - Form validators
575+
- **Navigation Controls** - Menu, TreeView, SiteMapPath
576+
- **Login Controls** - Authentication/authorization components
577+
578+
**Ordering**: Add links alphabetically within each category.
579+
580+
## Updating the Repository README
581+
582+
**CRITICAL**: After documenting a component, update the main README.md at the repository root.
583+
584+
Location: `README.md` (repository root)
585+
586+
### For New Components
587+
588+
If adding a component that isn't already listed, add it to the appropriate category:
589+
590+
```markdown
591+
## Blazor Components for Controls
592+
593+
There are a significant number of controls in ASP.NET Web Forms, and we will focus on creating components in the following order:
594+
595+
- Editor Controls
596+
- [AdRotator](docs/EditorControls/AdRotator.md)
597+
- [Button](docs/EditorControls/Button.md)
598+
- [NewComponent](docs/EditorControls/NewComponent.md) <-- Add alphabetically with link
599+
- [TextBox](docs/EditorControls/TextBox.md)
600+
```
601+
602+
### For Existing Components (Adding Documentation)
603+
604+
If a component exists in the list without a documentation link, add the link:
605+
606+
```markdown
607+
Before:
608+
- CheckBoxList
609+
610+
After:
611+
- [CheckBoxList](docs/EditorControls/CheckBoxList.md)
612+
```
613+
614+
### README Categories
615+
616+
Match the category in the README to where you placed the documentation:
617+
- `Editor Controls` → `docs/EditorControls/`
618+
- `Data Controls` → `docs/DataControls/`
619+
- `Validation Controls` → `docs/ValidationControls/`
620+
- `Navigation Controls` → `docs/NavigationControls/`
621+
- `Login Controls` → `docs/LoginControls/`
622+
623+
**Ordering**: Keep components alphabetically sorted within each category.
624+
625+
## Complete Documentation Workflow
626+
627+
When documenting a new or existing component, follow this complete workflow:
628+
629+
### 1. Create Component Documentation
630+
- Location: `docs/[Category]/[ComponentName].md`
631+
- Follow the component documentation template
632+
- Include Web Forms and Blazor syntax comparisons
633+
- Document supported and unsupported features
634+
- Provide working code examples
635+
636+
### 2. Add to MkDocs Navigation
637+
- File: `mkdocs.yml`
638+
- Add entry under appropriate `nav:` section
639+
- Format: `- ComponentName: Category/ComponentName.md`
640+
- Maintain alphabetical order within category
641+
642+
### 3. Create Sample Page(s)
643+
- Location: `samples/AfterBlazorServerSide/Components/Pages/ControlSamples/[ComponentName]/`
644+
- Create `Index.razor` for basic usage
645+
- Create additional scenario pages as needed (Style.razor, Events.razor, etc.)
646+
- Follow sample page template and structure
647+
- Include `@page` directive with correct route
648+
- Add working component demonstration
649+
650+
### 4. Update Navigation Menu
651+
- File: `samples/AfterBlazorServerSide/Components/Layout/NavMenu.razor`
652+
- Add `<TreeNode>` entries under appropriate category
653+
- Include all sample pages for the component
654+
- Maintain alphabetical order within category
655+
656+
### 5. Update Home Page Component List
657+
- File: `samples/AfterBlazorServerSide/Components/Pages/ComponentList.razor`
658+
- Add link in appropriate category column
659+
- Link to the main sample page: `/ControlSamples/[ComponentName]`
660+
- Maintain alphabetical order within category
661+
662+
### 6. Update Repository README
663+
- File: `README.md` (root)
664+
- Add component with documentation link if new
665+
- Update existing component entry to include link if adding documentation
666+
- Format: `- [ComponentName](docs/Category/ComponentName.md)`
667+
- Maintain alphabetical order within category
668+
669+
### Example: Complete Workflow for "Label" Component
670+
671+
```bash
672+
# 1. Create documentation
673+
docs/EditorControls/Label.md
674+
675+
# 2. Update mkdocs.yml
676+
nav:
677+
- Editor Controls:
678+
- Label: EditorControls/Label.md
679+
680+
# 3. Create sample page
681+
samples/AfterBlazorServerSide/Components/Pages/ControlSamples/Label/Index.razor
682+
683+
# 4. Update NavMenu.razor
684+
<TreeNode Text="Label" NavigateUrl="/ControlSamples/Label" />
685+
686+
# 5. Update ComponentList.razor
687+
<li><a href="/ControlSamples/Label">Label</a></li>
688+
689+
# 6. Update README.md
690+
- [Label](docs/EditorControls/Label.md)
691+
```
692+
394693
## Quality Checklist
395694

396695
Before submitting documentation:
@@ -405,10 +704,20 @@ Before submitting documentation:
405704
- [ ] Spell-checked
406705

407706
Before submitting sample pages:
408-
- [ ] Includes both demo and source code sections
409-
- [ ] Code block exactly matches the demo
410-
- [ ] HTML entities properly encoded in code block
411-
- [ ] `@` symbols doubled in code block
412-
- [ ] Includes complete `@code` block with all handlers
413-
- [ ] Brief description explains what sample demonstrates
414-
- [ ] Sample is accessible from navigation or component list
707+
- [ ] Created in correct folder: `ControlSamples/[ComponentName]/`
708+
- [ ] Follows naming convention (Index.razor for main sample)
709+
- [ ] Includes `@page` directive with correct route
710+
- [ ] Includes `<PageTitle>` element
711+
- [ ] Has clear heading and description
712+
- [ ] Contains working component demonstration
713+
- [ ] Added to NavMenu.razor navigation tree
714+
- [ ] Added to ComponentList.razor home page
715+
- [ ] All samples for component are linked in navigation
716+
- [ ] Routes match navigation URLs exactly
717+
718+
Before submitting README updates:
719+
- [ ] Component added to or updated in correct category
720+
- [ ] Documentation link format: `[ComponentName](docs/Category/ComponentName.md)`
721+
- [ ] Alphabetically ordered within category
722+
- [ ] Link verified to work (file exists at that path)
723+
- [ ] Category matches documentation location

‎README.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ There are a significant number of controls in ASP.NET Web Forms, and we will foc
2828
- [Button](docs/EditorControls/Button.md)
2929
- Calendar
3030
- [CheckBox](docs/EditorControls/CheckBox.md)
31-
- CheckBoxList
31+
- [CheckBoxList](docs/EditorControls/CheckBoxList.md)
3232
- [DropDownList](docs/EditorControls/DropDownList.md)
3333
- FileUpload
3434
- [HiddenField](docs/EditorControls/HiddenField.md)
@@ -38,14 +38,14 @@ There are a significant number of controls in ASP.NET Web Forms, and we will foc
3838
- ImageMap
3939
- [Label](docs/EditorControls/Label.md)
4040
- [LinkButton](docs/EditorControls/LinkButton.md)
41-
- ListBox
41+
- [ListBox](docs/EditorControls/ListBox.md)
4242
- [Literal](docs/EditorControls/Literal.md)
4343
- Localize
4444
- MultiView
45-
- Panel
46-
- PlaceHolder
45+
- [Panel](docs/EditorControls/Panel.md)
46+
- [PlaceHolder](docs/EditorControls/PlaceHolder.md)
4747
- [RadioButton](docs/EditorControls/RadioButton.md)
48-
- RadioButtonList
48+
- [RadioButtonList](docs/EditorControls/RadioButtonList.md)
4949
- Substitution
5050
- Table
5151
- [TextBox](docs/EditorControls/TextBox.md)

‎samples/AfterBlazorServerSide/Components/Layout/NavMenu.razor‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,21 @@
1919
<TreeNode Text="JavaScript Click" NavigateUrl="/ControlSamples/Button/JavaScript" />
2020
<TreeNode Text="Style" NavigateUrl="/ControlSamples/Button/Style" />
2121
</TreeNode>
22+
<TreeNode Text="CheckBox" NavigateUrl="/ControlSamples/CheckBox">
23+
<TreeNode Text="Events" NavigateUrl="/ControlSamples/CheckBox/Events" />
24+
<TreeNode Text="Style" NavigateUrl="/ControlSamples/CheckBox/Style" />
25+
</TreeNode>
26+
<TreeNode Text="DropDownList" NavigateUrl="/ControlSamples/DropDownList" />
2227
<TreeNode Text="LinkButton" NavigateUrl="/ControlSamples/LinkButton">
2328
<TreeNode Text="JavaScript Click" NavigateUrl="/ControlSamples/LinkButton/JavaScript" />
2429
</TreeNode>
2530
<TreeNode Text="HyperLink" NavigateUrl="/ControlSamples/HyperLink" />
2631
<TreeNode Text="Literal" NavigateUrl="/ControlSamples/Literal" />
32+
<TreeNode Text="Panel" NavigateUrl="/ControlSamples/Panel" />
33+
<TreeNode Text="PlaceHolder" NavigateUrl="/ControlSamples/PlaceHolder" />
34+
<TreeNode Text="RadioButton" NavigateUrl="/ControlSamples/RadioButton" />
35+
<TreeNode Text="RadioButtonList" NavigateUrl="/ControlSamples/RadioButtonList" />
36+
<TreeNode Text="TextBox" NavigateUrl="/ControlSamples/TextBox" />
2737
</TreeNode>
2838
<TreeNode Text="Data Components">
2939

@@ -74,7 +84,8 @@
7484

7585
<TreeNode Text="Navigation Components">
7686

77-
<TreeNode Text="Menu" NavigateUrl="/ControlSamples/Menu" Expanded="true">
87+
<TreeNode Text="Menu" NavigateUrl="/ControlSamples/Menu" Expanded="false">
88+
<TreeNode Text="Databinding Sitemap" NavigateUrl="/ControlSamples/Menu/DatabindingSitemap" />
7889
</TreeNode>
7990

8091
<TreeNode Text="TreeView" NavigateUrl="/ControlSamples/TreeView" Expanded="false">

0 commit comments

Comments
 (0)