Skip to content

Add hinting #152

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add hinting #152

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ca9c1da
Add hints to the lab spec
stellamazeika Apr 20, 2023
01c07c9
Fix merge conflicts
stellamazeika Apr 20, 2023
2ffb3ce
Fix Merge Conflict
stellamazeika Apr 20, 2023
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
119 changes: 25 additions & 94 deletions html/html-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ Renders pre-formatted and syntax-highlighted code blocks.
* `noWrap: boolean`

By default, code blocks wrap their contents. Setting this attribute will
make code blocks *not* wrap text within themselves. Instead, a horizontal
make code blocks _not_ wrap text within themselves. Instead, a horizontal
scrollbar will appear to view the full contents.

* `tabTitle: string|null`
Expand All @@ -77,11 +77,6 @@ Renders pre-formatted and syntax-highlighted code blocks.

Use this property to set this block as "output", instead of "input".

* `templated: boolean`

Allows the use of templated variables in this code block. See
[Templated Variables](#templated-variables) below.

#### Indentation

Code block indentation is determined by the amount of indentation preceding the
Expand Down Expand Up @@ -136,90 +131,6 @@ Would be rendered as:
}
```

#### Escaping Content

The contents of code blocks must be
[HTML-escaped](https://www.w3.org/International/questions/qa-escapes#use) in
order to render correctly.

This is most relevant for HTML/XML content, for example:

```html
<ql-code-block language="html">
&lt;h1&gt;What is a monad?&lt;/h1&gt;
&lt;p&gt;A monad is just a monoid in the category of endofunctors.&lt;/p&gt;
&lt;img src="monad.png" alt="Monad diagram"&gt;
</ql-code-block>
```

will render as:

![example preview](./images/ql-code-block-01.png)

#### Templated Variables

Much like [\<ql-variable>](#ql-variable), Lab outputs such as usernames,
passwords, project IDs, etc. can be rendered directly within code blocks using
the `templated` attribute.

Code blocks marked as `templated` will allow the usage of triple curly braces
within the code content. The curly braces must contain the output `key` to be
rendered, and optionally may contain a `placeholder` that is rendered before the
lab is started and data is available.

```
{{{key}}}
{{{key|placeholder}}}
```

For example, say you want to use the user's username and password in a snippet
of Python. See the following example:

```html
<ql-code-block language="python" templated>
def init_api():
# Logs into Cool API with your username {{{user_1.username}}}
api = CoolApi.login(
'{{{user_1.username|your_username}}}',
'{{{user_1.username|your_password}}}',
)
return api
</ql-code-block>
```

When the lab page is first opened, only the placeholders will be shown:

![example preview](./images/ql-code-block-02.png)

After the lab has been started and provisioned, the code block will be updated
to include the lab outputs:

![example preview](./images/ql-code-block-03.png)

### Markdown Syntax (GitHub integration only)

Code blocks can be rendered with Markdown using triple back ticks:

~~~
```javascript
console.log('hello world!');
```
~~~

Code block properties can be easily utilized in Markdown as well:

~~~
```python output noWrap
print('this will be styled as an output code block and will not wrap lines.')
```
~~~

When rendering a code block through Markdown, HTML-escaping the contents is not
necessary and will be handled automatically.

Also, Markdown code blocks without an explicit `language` specified will be
rendered with `language="plaintext"`.

#### Examples

Two tabs of code blocks, one with a custom title.
Expand Down Expand Up @@ -265,9 +176,8 @@ Result:

### `<ql-variable>`

Much like a [templated \<ql-code-block>](#templated-variables), Lab outputs such
as usernames, passwords, project IDs, etc. can be rendered directly within lab
instructions using the `<ql-variable>` component.
Lab outputs such as usernames, passwords, project IDs, etc. can be rendered
directly within lab instructions using the `<ql-variable>` component.

#### Attributes for `<ql-variable>`

Expand Down Expand Up @@ -339,8 +249,29 @@ Result (lab started, same as the previous example):

![example preview](./images/ql-variable-03.png)

### `<ql-activity-tracking>`
## `<ql-hint>`
Copy link
Contributor

Choose a reason for hiding this comment

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

I think these changes should happen in google3, then Copybara will copy it over to here. https://source.corp.google.com/piper///depot/google3/cloud/training/qwiklabs/content_bundle/g3doc/html/html-spec.md


Renders the content contained in the tags as a button labeled "Need a Hint?".
When the lab is running, the learner can click the button to view the content
contained within. `<ql-hint>` tags work with most pieces of the static content
without any additional work, however we currently do not support dynamic content,
including any activity tracking or `<ql-variable>` tags.

In particular: images, fragments and code blocks work just fine.

### Attributes for `<ql-hint>`

None

### Example

```Here is the description of a task you should do

<ql-hint>
And here, we go into depth about how to do it specifically
</ql-hint>```

## `<ql-activity-tracking>`
TODO: add documentation

### `<ql-multiple-choice-probe>`
Expand Down