Skip to content
This repository was archived by the owner on Nov 19, 2024. It is now read-only.

Add Layout XML Standard (new branch) #1078

Closed
wants to merge 2 commits into from
Closed

Add Layout XML Standard (new branch) #1078

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
08ac1ff
Create a standard for XML files
JesseMaxwell Jan 10, 2017
23550d7
Update to clarify that the focus is layout XML
JesseMaxwell Jan 10, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions guides/v2.1/coding-standards/xml-coding-standard.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
---
layout: default
group: coding-standards
subgroup: Coding standards
title: Layout XML Coding Standards
menu_title: Layout XML Coding Standards
menu_order: 100
contributor_name: SwiftOtter Studios
contributor_link: https://swiftotter.com/
version: 2.1
github_link: coding-standards/xml-coding-standard.md
---

# Layout XML Coding Standard

### Name attribute

The `name` attribute should adhere to the guidelines listed below. The `name` attribute should:

- Be unique to the project.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can not be enforced without a more specific rule (add namespace?)

- Use a namespace approach where each child block's name contains its parent's name as well.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cons:

  • @benmarks : it is a duplication of the structure. Layout structure can be modified ()
  • @okorshenko : reusable declarations (renderer lists) will not be able to follow this approach
  • will mix structure of blocks and multi-word block names (example: i want to call my bllock "my.block")

Pros:

  • @buskamuza : will allow to see the original place of a block.
  • @okorshenko : improves unique block naming

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding for the record (this is the salient point):

Use a namespace approach where each child block's name contains its parent's name

Because block names exist in the global layout scope, this isn't a "namespace approach"; rather, it's a hierarchy approach.

- Have segments separated by a `.` (period).
- Be all lowercase.
- Never use `_` (underscores).

*Example:*

```xml
<block name="header">
<block name="header.right">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Name" should not describe the position of a block. It should explain its purpose. We should add it as one of the rules.

<block name="header.right.search">
<block name="header.right.search.autocomplete" />
</block>
</block>
</block>
```

### As attribute

The `as` attribute should follow the guidelines below. The value of `as`:

- Only needs to be unique to the block that contains it.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@benmarks : With current implementation, this one can be confusing for block substitution scenario (when we add a block with same alias to substitute a other child)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have an internal goal of having this complete tonight (12-Jun), but it will be a couple more days. Thanks again for proposing.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do we expect in this scenario? I'd leave the statement as is.

- Should be as concise as possible, but with enough clarity to be understood within the block.
- Can use an `_` (underscore) as a separator.
- Should only be added if necessary.
- Should be all lowercase.


*Example:*

```xml
<block name="header">
<block name="header.right" as="right_actions">
<block name="header.right.search" as="search">
<block name="header.right.search.autocomplete" as="autocomplete" />
</block>
</block>
</block>
```