Skip to content

Commit

Permalink
LUAFDN-1247 - fix docs deploy (#323)
Browse files Browse the repository at this point in the history 
Closes LUAFDN-1247.

docs deploy is a year old and doesn't have latest markdown extensions
  • Loading branch information
RoFlection Bot committed Sep 22, 2022
1 parent 1fd4626 commit 4173349
Show file tree
Hide file tree
Showing 3 changed files with 301 additions and 300 deletions.
334 changes: 167 additions & 167 deletions docs/migrating-from-1x/convert-legacy-conventions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,52 +41,52 @@ In Roact 17, the equivalent mechanisms use a new concept called a "root" to more

Since the root needs to access a Roblox `Instance` in order to attach to it, these functions are exported through the `ReactRoblox` package, also known as a "renderer". A renderer takes the abstract descriptions of UI generated by React components and turns them into a concrete UI element tree. You can think of the `ReactRoblox` package as the semantic equivalent of the `react-dom` package in the React JS ecosystem.

=== "Legacy Roact"
```lua
local PlayerGui = game:GetService("Players").LocalPlayer.PlayerGui
local Roact = require(Packages.Roact)
#### Legacy Roact
```lua
local PlayerGui = game:GetService("Players").LocalPlayer.PlayerGui
local Roact = require(Packages.Roact)

local roactTree = Roact.mount(Roact.createElement("TextLabel", {
Text = "Hello world!",
}, PlayerGui)
local roactTree = Roact.mount(Roact.createElement("TextLabel", {
Text = "Hello world!",
}, PlayerGui)

task.wait(3)
task.wait(3)

roactTree = Roact.update(roactTree, Roact.createElement("TextLabel", {
Text = "Hello Roblox!",
})
roactTree = Roact.update(roactTree, Roact.createElement("TextLabel", {
Text = "Hello Roblox!",
})

task.wait(3)
task.wait(3)

Roact.unmount(roactTree)
```
Roact.unmount(roactTree)
```

=== "Roact 17"
```lua hl_lines="2-3 5-8 10-11 13 17 23"
local PlayerGui = game:GetService("Players").LocalPlayer.PlayerGui
local React = require(Packages.React)
local ReactRoblox = require(Packages.ReactRoblox)
#### Roact 17
```lua hl_lines="2-3 5-8 10-11 13 17 23"
local PlayerGui = game:GetService("Players").LocalPlayer.PlayerGui
local React = require(Packages.React)
local ReactRoblox = require(Packages.ReactRoblox)

-- Roact 17 roots will take full ownership of the instance provided to them,
-- so we should not create a root using PlayerGui directly
local container = Instance.new("Folder")
container.Parent = PlayerGui
-- Roact 17 roots will take full ownership of the instance provided to them,
-- so we should not create a root using PlayerGui directly
local container = Instance.new("Folder")
container.Parent = PlayerGui

local root = ReactRoblox.createRoot(container)
root:render(Roact.createElement("TextLabel", {
Text = "Hello world!",
})
local root = ReactRoblox.createRoot(container)
root:render(Roact.createElement("TextLabel", {
Text = "Hello world!",
})

task.wait(3)
task.wait(3)

root:render(Roact.createElement("TextLabel", {
Text = "Hello Roblox!",
})
root:render(Roact.createElement("TextLabel", {
Text = "Hello Roblox!",
})

task.wait(3)
task.wait(3)

root:render(nil)
```
root:render(nil)
```

!!! warning
The `createBlockingRoot` and `createLegacyRoot` functions will opt out of concurrent rendering, a feature of Roact 17 that allows smooth, scalable UI by dividing units of work across multiple frames when large amounts of UI changes are needed. We always recommend using `createRoot` unless you know what you're doing.
Expand Down Expand Up @@ -114,89 +114,89 @@ Legacy Roact went out of its way to let all prop keys be valid for component dev

You can index `props.children` to refer to the children provided to a component, and use `ref` as a key to an element to provide a ref to it.

=== "Legacy Roact"
```lua
local FocusButton = Roact.Component:extend("FocusButton")

function FocusButton:init()
self.ref = Roact.createRef()
end

function FocusButton:render()
return Roact.createElement("Button", {
Size = self.props.Size,
[Roact.Ref] = self.ref
}, self.props[Roact.Children])
end

function FocusButton:didMount()
GuiService.SelectedObject = self.ref.current
end
```

=== "Roact 17"
```lua hl_lines="10 11"
local FocusButton = Roact.Component:extend("FocusButton")

function FocusButton:init()
self.ref = Roact.createRef()
end

function FocusButton:render()
return Roact.createElement("Button", {
Size = self.props.Size,
ref = self.ref
}, self.props.children)
end

function FocusButton:didMount()
GuiService.SelectedObject = self.ref.current
end
```
#### Legacy Roact
```lua
local FocusButton = Roact.Component:extend("FocusButton")

function FocusButton:init()
self.ref = Roact.createRef()
end

function FocusButton:render()
return Roact.createElement("Button", {
Size = self.props.Size,
[Roact.Ref] = self.ref
}, self.props[Roact.Children])
end

function FocusButton:didMount()
GuiService.SelectedObject = self.ref.current
end
```

#### Roact 17
```lua hl_lines="10 11"
local FocusButton = Roact.Component:extend("FocusButton")

function FocusButton:init()
self.ref = Roact.createRef()
end

function FocusButton:render()
return Roact.createElement("Button", {
Size = self.props.Size,
ref = self.ref
}, self.props.children)
end

function FocusButton:didMount()
GuiService.SelectedObject = self.ref.current
end
```

### Context.Consumer

Legacy Roact treats the special `Context.Consumer` component generated by `createContext` more like a typical component with a single prop (`render`) as its prop interface. React JS, on the other hand, uses a slightly abbreviated structure.

The `Context.Consumer` component expects _no_ props and a _single_ child, where the child is the same mapping function that would be provided as the `render` prop in legacy Roact.

=== "Legacy Roact"
```lua
local ThemeContext = Roact.createContext(nil)

-- ...

local function Button(props)
return Roact.createElement(ThemeContext.Consumer, {
render = function(theme)
return Roact.createElement("TextButton", {
BackgroundColor3 = theme.ButtonColor,
Text = props.text,
[Roact.Event.Activated] = props.onActivated,
})
end
})
end
```

=== "Roact 17"
```lua hl_lines="6-7 14"
local ThemeContext = Roact.createContext(nil)

-- ...

local function Button(props)
return Roact.createElement(ThemeContext.Consumer, nil,
function(theme)
return Roact.createElement("TextButton", {
BackgroundColor3 = theme.ButtonColor,
Text = props.text,
[Roact.Event.Activated] = props.onActivated,
})
end
)
end
```
#### Legacy Roact
```lua
local ThemeContext = Roact.createContext(nil)

-- ...

local function Button(props)
return Roact.createElement(ThemeContext.Consumer, {
render = function(theme)
return Roact.createElement("TextButton", {
BackgroundColor3 = theme.ButtonColor,
Text = props.text,
[Roact.Event.Activated] = props.onActivated,
})
end
})
end
```

#### Roact 17
```lua hl_lines="6-7 14"
local ThemeContext = Roact.createContext(nil)

-- ...

local function Button(props)
return Roact.createElement(ThemeContext.Consumer, nil,
function(theme)
return Roact.createElement("TextButton", {
BackgroundColor3 = theme.ButtonColor,
Text = props.text,
[Roact.Event.Activated] = props.onActivated,
})
end
)
end
```

!!! info
Roact 17 has a compatibility layer that will allow either structure to work as expected. If you'd like to see warnings that will help you migrate, enable the [`__COMPAT_WARNINGS__` global](../configuration.md#compatwarnings).
Expand All @@ -207,73 +207,73 @@ Legacy Roact treats fragments as a special kind of rendered object, distinct fro

In Roact 17, however, fragments are nothing more than a special component type. Your component should return a single element with the `React.Fragment` component type, with the children provided as the element's children.

=== "Legacy Roact"
```lua
local function LabeledButton(props)
return Roact.createFragment({
Button = Roact.createElement("ImageButton", {
Image = props.buttonIcon,
}),
Label = Roact.createElement("TextLabel", {
Text = props.labelText,
}),
})
end
```

=== "Roact 17"
```lua hl_lines="2"
local function LabeledButton(props)
return React.createElement(React.Fragment, nil, {
Button = React.createElement("ImageButton", {
Image = props.buttonIcon,
}),
Label = React.createElement("TextLabel", {
Text = props.labelText,
}),
})
end
```
#### Legacy Roact
```lua
local function LabeledButton(props)
return Roact.createFragment({
Button = Roact.createElement("ImageButton", {
Image = props.buttonIcon,
}),
Label = Roact.createElement("TextLabel", {
Text = props.labelText,
}),
})
end
```

#### Roact 17
```lua hl_lines="2"
local function LabeledButton(props)
return React.createElement(React.Fragment, nil, {
Button = React.createElement("ImageButton", {
Image = props.buttonIcon,
}),
Label = React.createElement("TextLabel", {
Text = props.labelText,
}),
})
end
```

### ReactRoblox.createPortal

Legacy Roact uses a special `Roact.Portal` component to represent a portal. In Roact 17, we align with upstream and export the `ReactRoblox.createPortal` function.

Portals are considered to be a feature with renderer-specific functionality since they attach directly to a host instance. Any APIs that interact directly with Roblox Instances will be exported via `ReactRoblox` in order to maintain the renderer abstraction.

=== "Legacy Roact"
```lua
local PlayerGui = game:GetService("Players").LocalPlayer.PlayerGui

local function Modal(props)
return Roact.createElement(Roact.Portal, {
target = PlayerGui,
}, {
Modal = Roact.createElement("ScreenGui", {}, {
Label = Roact.createElement("TextButton", {
Text = "Click me to close!",
[Roact.Event.Activated] = props.onClose,
})
#### Legacy Roact
```lua
local PlayerGui = game:GetService("Players").LocalPlayer.PlayerGui

local function Modal(props)
return Roact.createElement(Roact.Portal, {
target = PlayerGui,
}, {
Modal = Roact.createElement("ScreenGui", {}, {
Label = Roact.createElement("TextButton", {
Text = "Click me to close!",
[Roact.Event.Activated] = props.onClose,
})
})
end
```

=== "Roact 17"
```lua hl_lines="4 11"
local PlayerGui = game:GetService("Players").LocalPlayer.PlayerGui

local function Modal(props)
return ReactRoblox.createPortal({
Modal = Roact.createElement("ScreenGui", {}, {
Label = Roact.createElement("TextButton", {
Text = "Click me to close!",
[Roact.Event.Activated] = props.onClose,
})
})
end
```

#### Roact 17
```lua hl_lines="4 11"
local PlayerGui = game:GetService("Players").LocalPlayer.PlayerGui

local function Modal(props)
return ReactRoblox.createPortal({
Modal = Roact.createElement("ScreenGui", {}, {
Label = Roact.createElement("TextButton", {
Text = "Click me to close!",
[Roact.Event.Activated] = props.onClose,
})
}, PlayerGui)
end
```
})
}, PlayerGui)
end
```

### Roact.oneChild

Expand Down
Loading

0 comments on commit 4173349

Please sign in to comment.