Skip to content

Commit

Permalink
Describe the IHeader interface and related properties (#7157)
Browse files Browse the repository at this point in the history
* Describe the IHeader interface and related properties

* rename inheritWidthFrom value "page" -> "container";

---------

Co-authored-by: OlgaLarina <olga.larina.dev@gmail.com>
  • Loading branch information
RomanTsukanov and OlgaLarina committed Oct 16, 2023
1 parent 8555f01 commit cfcd396
Show file tree
Hide file tree
Showing 5 changed files with 144 additions and 8 deletions.
4 changes: 4 additions & 0 deletions docs/sidebar.json
Original file line number Diff line number Diff line change
Expand Up @@ -240,6 +240,10 @@
"Name": "ITheme",
"Title": "ITheme"
},
{
"Name": "IHeader",
"Title": "IHeader"
},
{
"Name": "ICustomQuestionTypeConfiguration",
"Title": "ICustomQuestionTypeConfiguration"
Expand Down
4 changes: 2 additions & 2 deletions src/cover.ts
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ export class Cover extends Base {
this.contentClasses = new CssClassBuilder()
.append("sv-conver__content")
.append("sv-conver__content--static", this.inheritWidthFrom === "survey" && !!surveyWidthMode && surveyWidthMode === "static")
.append("sv-conver__content--responsive", this.inheritWidthFrom === "page" || (!!surveyWidthMode && surveyWidthMode === "responsive"))
.append("sv-conver__content--responsive", this.inheritWidthFrom === "container" || (!!surveyWidthMode && surveyWidthMode === "responsive"))
.toString();
}
private updateBackgroundImageClasses(): void {
Expand Down Expand Up @@ -122,7 +122,7 @@ export class Cover extends Base {

public cells: CoverCell[] = [];
@property() public height: number;
@property() public inheritWidthFrom: "survey" | "page";
@property() public inheritWidthFrom: "survey" | "container";
@property() public textAreaWidth: number;
@property() public textGlowEnabled: boolean;
@property() public overlapEnabled: boolean;
Expand Down
11 changes: 11 additions & 0 deletions src/survey.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1168,6 +1168,17 @@ export class SurveyModel extends SurveyElementCore
@property() loadingBodyCss: string;
@property() containerCss: string;
@property({ onSet: (newValue, target: SurveyModel) => { target.updateCss(); } }) fitToContainer: boolean;
/**
* Specifies whether the survey header uses only basic appearance settings or applies advanced settings from the survey theme.
*
* Possible values:
*
* - `"basic"` (default)\
* A basic header view applies only the [`title`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#title), [`description`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#description), and logo-related properties ([`logo`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#logo), [`logoPosition`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#logoPosition), etc.).
*
* - `"advanced"`\
* An advanced header view applies the same properties as the basic view, plus [header settings](https://surveyjs.io/form-library/documentation/api-reference/iheader) from the [survey theme](https://surveyjs.io/form-library/documentation/api-reference/itheme#header). The advanced view features a more flexible header layout, a capability to specify a background image, and other settings that give a more professional look to the survey header.
*/
@property({
onSet: (newValue, target: SurveyModel) => {
if (newValue === "advanced") {
Expand Down
125 changes: 123 additions & 2 deletions src/themes.ts
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ export interface ITheme {
*/
backgroundOpacity?: number;
/**
* An object with survey header settings.
* An object with [advanced survey header settings](https://surveyjs.io/form-library/documentation/api-reference/iheader). Applies when `SurveyModel`'s [`headerView`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#headerView) property is set to `"advanced"`.
*/
header?: IHeader;
/**
Expand All @@ -67,19 +67,140 @@ export interface ITheme {
cssVariables?: { [index: string]: string };
}

/**
* A survey header configuration interface.
*
* An `IHeader` object configures advanced survey header appearance settings. To apply them, you need to assign the object to the [`header`](https://surveyjs.io/form-library/documentation/api-reference/itheme#header) property of your theme configuration and set `SurveyModel`'s [`headerView`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#headerView) property to `"advanced"`.
*/
export interface IHeader {
/**
* The height of the survey header in pixels.
*
* Default value: 256
*/
height: number;
inheritWidthFrom: "survey" | "page";
/**
* A string value that specifies whether the header spans the width of the survey or that of the survey container.
*
* Possible values:
*
* - `"survey"` (default)\
* The header width is the same as the survey width.
* - `"container"`\
* The header width is the same as the survey container width.
*
* @see [SurveyModel.width](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#width)
* @see [SurveyModel.widthMode](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#widthMode)
*/
inheritWidthFrom: "survey" | "container";
/**
* The width of the header area that contains the survey [title](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#title) and [description](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#description), measured in pixels.
*
* Default value: 512
*/
textAreaWidth: number;

// textGlowEnabled: boolean;

/**
* A Boolean value that specifies whether the header overlaps the survey content.
*
* Default value: `false`
*/
overlapEnabled: boolean;
/**
* An image to display in the background of the header. Accepts a base64 or URL string value.
*/
backgroundImage: string;
/**
* A value from 0 to 1 that specifies how transparent the [background image](#backgroundImage) should be: 0 makes the image completely transparent, and 1 makes it opaque.
*/
backgroundImageOpacity: number;
/**
* A string value that specifies how to resize a [background image](#backgroundImage) to fit it into the header.
*
* Possible values:
*
* - `"cover"` (default)\
* Scales the image to the smallest possible size that fills the header. The image preserves its aspect ratio but can be cropped if the header's proportions differ from that of the element.
* - `"fill"`\
* Stretches the image to fill the entire header.
* - `"contain"`\
* Scales the image to the largest possible size without cropping or stretching it.
* - `"tile"`\
* Tiles as many copies of the image as needed to fill the entire header.
*/
backgroundImageFit: "cover" | "fill" | "contain" | "tile";
/**
* A string value that specifies the logo position within the header in the horizontal direction.
*
* Possible values:
*
* - `"right"` (default)
* - `"left"`
* - `"center"`
*
* To specify a logo, set `SurveyModel`'s [`logo`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#logo) property.
*/
logoPositionX: HorizontalAlignment;
/**
* A string value that specifies the logo position within the header in the vertical direction.
*
* Possible values:
*
* - `"top"` (default)
* - `"bottom"`
* - `"middle"`
*
* To specify a logo, set `SurveyModel`'s [`logo`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#logo) property.
*/
logoPositionY: VerticalAlignment;
/**
* A string value that specifies the survey title position within the header in the horizontal direction.
*
* Possible values:
*
* - `"left"` (default)
* - `"right"`
* - `"center"`
*
* To specify a survey title, set `SurveyModel`'s [`title`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#title) property.
*/
titlePositionX: HorizontalAlignment;
/**
* A string value that specifies the survey title position within the header in the vertical direction.
*
* Possible values:
*
* - `"bottom"` (default)
* - `"top"`
* - `"middle"`
*
* To specify a survey title, set `SurveyModel`'s [`title`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#title) property.
*/
titlePositionY: VerticalAlignment;
/**
* A string value that specifies the survey description position within the header in the horizontal direction.
*
* Possible values:
*
* - `"left"` (default)
* - `"right"`
* - `"center"`
*
* To specify a survey description, set `SurveyModel`'s [`description`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#description) property.
*/
descriptionPositionX: HorizontalAlignment;
/**
* A string value that specifies the survey description position within the header in the vertical direction.
*
* Possible values:
*
* - `"bottom"` (default)
* - `"top"`
* - `"middle"`
*
* To specify a survey description, set `SurveyModel`'s [`description`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#description) property.
*/
descriptionPositionY: VerticalAlignment;
}
8 changes: 4 additions & 4 deletions tests/coverTests.ts
Original file line number Diff line number Diff line change
Expand Up @@ -69,8 +69,8 @@ QUnit.test("cover maxWidth",
cover.survey = new SurveyModel({ widthMode: "static", width: "500" });
assert.equal(cover.maxWidth, "500px", "survey.maxWidth is static");

cover.inheritWidthFrom = "page";
assert.equal(cover.maxWidth, false, "inheritWidthFrom is page");
cover.inheritWidthFrom = "container";
assert.equal(cover.maxWidth, false, "inheritWidthFrom is container");
}
);

Expand All @@ -89,8 +89,8 @@ QUnit.test("contentClasses",
cover.survey.widthMode = "static";
assert.equal(cover.contentClasses, "sv-conver__content sv-conver__content--static", "survey.widthMode is static");

cover.inheritWidthFrom = "page";
assert.equal(cover.contentClasses, "sv-conver__content sv-conver__content--responsive", "inheritWidthFrom is page");
cover.inheritWidthFrom = "container";
assert.equal(cover.contentClasses, "sv-conver__content sv-conver__content--responsive", "inheritWidthFrom is container");
}
);

Expand Down

0 comments on commit cfcd396

Please sign in to comment.