Skip to content

Commit

Permalink
Merge splitter-panes-2241 into production (#2245)
Browse files Browse the repository at this point in the history 
* docs(splitter): Revamp Panes article

* Update components/splitter/panes.md

Co-authored-by: Iva Stefanova Koevska-Atanasova <[email protected]>

* Update components/splitter/panes.md

Co-authored-by: Iva Stefanova Koevska-Atanasova <[email protected]>

* Update common-features/dimensions.md

Co-authored-by: Iva Stefanova Koevska-Atanasova <[email protected]>

* Update components/splitter/overview.md

Co-authored-by: Iva Stefanova Koevska-Atanasova <[email protected]>

* Update components/splitter/overview.md

Co-authored-by: Iva Stefanova Koevska-Atanasova <[email protected]>

* Update components/splitter/panes.md

Co-authored-by: Iva Stefanova Koevska-Atanasova <[email protected]>

* polish vocabulary and grammar

---------

Co-authored-by: Dimo Dimov <[email protected]>
Co-authored-by: Iva Stefanova Koevska-Atanasova <[email protected]>
  • Loading branch information
@github-actions @dimodi @ikoevska
3 people authored Jul 18, 2024
1 parent 25a1b34 commit 586fe70
Show file tree
Hide file tree
Showing 8 changed files with 344 additions and 151 deletions.
29 changes: 19 additions & 10 deletions common-features/dimensions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,19 +10,27 @@ position: 7

# Dimensions

This article explains how dimensional properties like `Width` and `Height`, `Top` and `Left` work in the Telerik UI for Blazor suite to set size and position.
This article explains how dimensional properties like `Width`, `Height`, `Top` and `Left` work in Telerik UI for Blazor to set size and position.

Properties that denote **dimensions and positions are** simple **string properties** that are not parsed by our code. You can provide **valid CSS values** to them. For example, `100px` or `50%` are valid options. This provides you with flexibility without limiting options. At the time of writing there is no `Unit` type in the underlying framework.
## Basics

The string you provide is usually rendered within an inline `style` attribute, so you must make sure to provide a valid value that will not break other options. You do not need to include a semicolon (`;`).
Component parameters for dimensions and positions are usually `string` properties that are not parsed the Telerik components. You can set any [valid CSS unit](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units). For example, `100px`, `50%`, or `80vw` are all valid options. At the time of writing there is no `Unit` type in the underlying framework.

For elements with **special positioning** (`Top` and `Left` properties), keep in mind that if the parent elements have special CSS positioning, it will affect the position of the component. If you experience issues, inspect the rendered HTML to see what elements are present and what their CSS rules are.
The string you provide is usually rendered as an inline `style` attribute, so you must provide a valid value that will not break other options. You do not need to include a semicolon (`;`) in the parameter value.

When setting **percentage values** (such as `100%` or `50%`), keep in mind the following - according to the web standards, elements which have their height set in percentage require that the height of their parent is also explicitly set. This requirement applies recursively until either an element with a pixel height or the html element is reached. Elements that are 100% high should not have margins, paddings, borders, or sibling elements.
## Percentages

When setting **percentage dimensions** to elements with **special positioning** (such as `Width` of a Window or the popup `Width` of a dropdown), their parent element in the DOM determines the rendered size.
When setting percentage values like `100%` or `50%`, keep in mind the following: web standards require elements with percentage heights to have a parent with an explicit height. This requirement applies recursively until either an element with a pixel height or the `html` element is reached.

>tip You can use dimensions in percent (such as `Width="100%"`) to make the components responsive - so they will fit in your layout and let the layout adjust with viewport sizes or other application logic.
Elements that are 100% high should not have margins, paddings, borders, or sibling elements, unless you set a [`box-sizing:border-box`](https://developer.mozilla.org/en-US/docs/Web/CSS/box-sizing) CSS style to them.

When setting percentage dimensions to elements with special positioning (such as `Width` of a Window or the popup `Width` of a DropDownList), their parent element in the DOM determines the resulting component dimensions.

## Position

When using positioning parameters, for example `Top` or `Left`, the component placement may be affected by CSS styles on the component's parent. If you experience issues, [inspect the rendered HTML to see what elements are present and what their CSS styles are]({%slug themes-override%}#tools).

>tip You can set dimensions in percentage (such as `Width="100%"`) to make the components responsive and let them resize according to the app layout and browser viewport. A lot of components expand to 100% width by default, for example, the Grid, Form, Scheduler, Spreadsheet, all input components, and others.
## Examples

Expand All @@ -42,7 +50,6 @@ The examples here showcase different units and examples of using them to set dim

![Blazor Basic Width Settings](images/basic-width-settings.png)


>caption Using auto width to have an element adjust to its contents
````CSHTML
Expand All @@ -69,7 +76,6 @@ The examples here showcase different units and examples of using them to set dim
![Blazor Auto Size For Dropdown](images/auto-size-for-dropdown.png)



>caption Position is controlled by the parent element with special positioning
````CSHTML
Expand All @@ -85,6 +91,9 @@ The examples here showcase different units and examples of using them to set dim
</TelerikWindow>
````


![Blazor Parent Element Offset](images/parent-element-offset.png)

## See Also

* [Themes]({%slug themes-built-in%})
* [Override Theme Styles]({%slug themes-override%})
Binary file removed components/splitter/images/nested-splitter-result.png
View file
Binary file not shown.
Binary file removed components/splitter/images/splitter-overview.gif
View file
Binary file not shown.
7 changes: 4 additions & 3 deletions components/splitter/orientation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -97,10 +97,11 @@ Sometimes you need to create a more complex layout that includes both horizontal
</div>
````

>caption The result from the code snippet above
## Next Steps

![Nested splitters can create complex layout](images/nested-splitter-result.png)
* [Manage the Splitter state]({%slug splitter-state%})
* [Handle Splitter events]({%slug splitter-events%})

## See Also

* [Live Demo: Splitter Orientation](https://demos.telerik.com/blazor-ui/splitter/orientation)
* [Live Demo: Splitter Orientation](https://demos.telerik.com/blazor-ui/splitter/orientation)
105 changes: 45 additions & 60 deletions components/splitter/overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,72 +12,55 @@ position: 0

The <a href="https://www.telerik.com/blazor-ui/splitter" target="_blank">Blazor Splitter component</a> lets you divide a portion of the page into several pieces that the user can resize and collapse. This provides real estate management for the app and the end user so they can focus on the content that is important in their current task. You can also [save and load its state]({%slug splitter-state%}), and respond to [events]({%slug splitter-events%}).

## Creating Splitter for Blazor
## Creating Blazor Splitter

1. Declare the `<TelerikSplitter>` tag
1. Add the `<TelerikSplitter>` tag.
1. Set the `Width` and `Height` parameters in any valid CSS unit. See [Splitter Parameters](#splitter-parameters) for more information about the component behavior when dimensions are not set.
1. Inside the `<SplitterPanes>` child tag, add the desired `<SplitterPane>` tags to create sections of content.
1. Inside each `<SplitterPane>`, add the desired content as HTML markup or other components.
1. Configure the panes. For example, [set their `Size`, `Min`, `Max`, `Collapsible`, and `Resizable` parameters]({%slug splitter-panes%}#pane-parameters). By default, Splitter panes are resizable, but not collapsible.

1. Optionally, set the `Width` and `Height` parameters to the desired values. Otherwise, the component size will be controlled by the content and [size]({%slug splitter-size%}) of the panes.
>caption Basic Splitter
* You can use values in percent (setting them to `100%` is very common) so that the splitter will take up the entire size of its container. See the [Dimensions]({%slug common-features/dimensions%}) article for more details on what units you can use and how dimensions in percent work.

1. Inside the `<SplitterPanes>` child tag, add the desired [`<SplitterPane>`]({%slug splitter-panes%}) tags to create the sections of content.
````CSHTML
<TelerikSplitter Orientation="@SplitterOrientation.Horizontal"
Width="80%"
Height="200px">
<SplitterPanes>
1. Inside each `<SplitterPane>`, add the desired content - be that HTML or components.
<SplitterPane Size="100px" Min="50px" Max="150px" Collapsible="true">
Left pane. Users can collapse it or resize it between 50px and 150px.
</SplitterPane>
1. Optionally, set the desired settings for the individual Panes - such as initial, min and max size, whether the user can collapse and resize the pane.
<SplitterPane Collapsible="false">
Middle pane, which cannot be collapsed.
</SplitterPane>
>caption Splitter that takes 100% of its container and shows the main features of its panes
<SplitterPane Collapsed="true" Collapsible="true" Resizable="false" Size="100px">
Right pane that is 100px wide and initially collapsed. Users cannot resize it.
</SplitterPane>
````CSHTML
This example shows how the splitter can fill up the entire container (marked with a red border) and the main features of the component and its panes.
<div style="width: 500px; height: 300px; border: 1px solid red;">
<TelerikSplitter Width="100%" Height="100%" Orientation="@SplitterOrientation.Horizontal">
<SplitterPanes>
<SplitterPane Size="100px" Min="50px" Max="150px" Collapsible="true">
<div>left sidebar. Can be collapsed and can be resized between 50px and 150px.</div>
</SplitterPane>
<SplitterPane Collapsible="false">
<div>right hand side pane - content. You cannot collapse this pane so it is always visible.</div>
</SplitterPane>
<SplitterPane Collapsed="true" Collapsible="true" Resizable="false" Size="100px">
<div>Third pane that is initially collapsed and is not resizable.</div>
</SplitterPane>
</SplitterPanes>
</TelerikSplitter>
</div>
</SplitterPanes>
</TelerikSplitter>
````

>caption Splitter functionality in action
![overview of the splitter functionality](images/splitter-overview.gif)

>tip The following sample app shows how to create a 100%-high page layout with a Splitter that includes a header, footer, and sidebar: <a href="https://github.com/telerik/blazor-ui/tree/master/splitter/use-100-percent-viewport" target="_blank">How to make the Splitter take up 100% of the viewport</a>.
## Panes

Тhe Panes are the building blocks of the Splitter. Each Pane controls its own behaviors such as the ability to change its size and collapse. [Read more about the Splitter Panes...]({%slug splitter-panes%})

## Size

You can control the Splitter size through its `Width` and `Height` parameters. Additionally, the component allows you specify the desired size for each pane. [Read about for the Splitter sizing specifics...]({%slug splitter-size%})
Тhe Panes are the building blocks of the Splitter. Each pane controls its own behaviors such as the ability to change its size and collapse. [Read more about the Splitter Panes...]({%slug splitter-panes%})

## Orientation

The Splitter Panes can be stacked in horizontal or vertical direction. [Read more about how to configure the Splitter orientation...]({%slug splitter-orientation%})
The Splitter panes can stack horizontally or vertically. [Read more about how to configure the Splitter orientation...]({%slug splitter-orientation%})

## State

The Splitter allows you to save its state and programmatically control it. [Read more about the Splitter State...]({%slug splitter-state%})
The Splitter allows you to save its state and programmatically control it. [Read more about the Splitter state...]({%slug splitter-state%})

## Events

The Splitter generates events that you can handle to further customize the component behavior and respond to the user actions. [Read more about the Blazor Menu events...]({%slug splitter-events%})
The Splitter fires events that you can handle to further customize the component behavior and respond to the user actions. [Read more about the Blazor Splitter events...]({%slug splitter-events%})

## Splitter Parameters

Expand All @@ -87,12 +70,13 @@ Check the [Splitter API Reference ](/blazor-ui/api/Telerik.Blazor.Components.Tel

@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)

| Attribute | Type and Default Value | Description |
|----------|----------|----------|
| `Class` | `string` | The CSS class that renders on the main wrapping element of the component.
| `Height` | `string` | The height of the Splitter. See the [Dimensions]({%slug common-features/dimensions%}) article for more details on what units you can use and how dimensions in percent work.
| `Orientation` | `SplitterOrientation` enum <br/> (`SplitterOrientation.Horizontal`) | Whether the content will be split up (how the panes will stack) horizontally or vertically.
| `Width`| `string` | The width of the Splitter. See the [Dimensions]({%slug common-features/dimensions%}) article for more details on what units you can use and how dimensions in percent work.
| Parameter | Type | Description |
| --- | --- | --- |
| `AriaLabel` | `string` | The `aria-label` attribute of the splitbars elements (`<div class="k-splitbar">`). |
| `Class` | `string` | The CSS class that renders on the Splitter element (`<div class="k-splitter">`). |
| `Height` | `string` | The height style of the Splitter. See the [Dimensions]({%slug common-features/dimensions%}) article for details on what units you can use and how percentage dimensions work. If not set, the Splitter will shrink and expand, according to the [pane sizes]({%slug splitter-panes%}#pane-size) and content. |
| `Orientation` | `SplitterOrientation` enum <br/> (`SplitterOrientation.Horizontal`) | Whether the content will be split up (how the panes will stack) horizontally or vertically. |
| `Width`| `string` | The width style of the Splitter in any [valid CSS unit]({%slug common-features/dimensions%}). If not set, the Splitter will expand horizontally to 100%. |

## Splitter Reference and Methods

Expand All @@ -107,7 +91,6 @@ Add a reference to the component instance to use the [Splitter methods](/blazor-
<TelerikButton OnClick="@GetSplitterState">Get Splitter State</TelerikButton>
<TelerikSplitter @ref="@SplitterRef"
Width="400px"
Height="200px">
<SplitterPanes>
<SplitterPane>
Expand All @@ -120,22 +103,24 @@ Add a reference to the component instance to use the [Splitter methods](/blazor-
</TelerikSplitter>
@code {
Telerik.Blazor.Components.TelerikSplitter SplitterRef { get; set; }
private TelerikSplitter? SplitterRef { get; set; }
void GetSplitterState()
private void GetSplitterState()
{
var currState = SplitterRef.GetState();
var splitterState = SplitterRef?.GetState();
}
}
````

## Next Steps

* [Explore the various Splitter Pane options]({%slug splitter-panes%})
* [Configure the Splitter Size]({%slug splitter-size%})
* [Explore the Splitter pane settings]({%slug splitter-panes%})
* [Set the Splitter orientation]({%slug splitter-orientation%})
* [Manage the Splitter state]({%slug splitter-state%})
* [Handle Splitter events]({%slug splitter-events%})

## See Also

* [Live Demo: Splitter](https://demos.telerik.com/blazor-ui/splitter/overview)
* [Splitter API Reference](/blazor-ui/api/Telerik.Blazor.Components.TelerikSplitter)
* [SplitterPane API Reference](/blazor-ui/api/Telerik.Blazor.Components.SplitterPane)
* [Live Demo: Splitter](https://demos.telerik.com/blazor-ui/splitter/overview)
* [Splitter API Reference](/blazor-ui/api/Telerik.Blazor.Components.TelerikSplitter)
* [SplitterPane API Reference](/blazor-ui/api/Telerik.Blazor.Components.SplitterPane)
Loading

0 comments on commit 586fe70

Please sign in to comment.