Help for package hypothesis

Type:

Package

Title:

Wrapper for 'hypothes.is'

Version:

1.1.0

Maintainer:

Krystian Igras <krystian8207@gmail.com>

Description:

Add, share and manage annotations for 'Shiny' applications and R Markdown documents via 'hypothes.is'.

License:

MIT + file LICENSE

Encoding:

UTF-8

Imports:

rlang, magrittr, glue, htmlwidgets, jsonlite, htmltools, purrr (≥ 1.0.0), httr

Suggests:

shiny, testthat (≥ 3.0.0), withr, mockery, knitr, rmarkdown, pkgdown

RoxygenNote:

7.2.3

Config/testthat/edition:

VignetteBuilder:

knitr

NeedsCompilation:

Packaged:

2023-07-19 13:45:01 UTC; krystiai

Author:

Krystian Igras [cre, aut], Adam Foryś [ctb], Hypothes.is Project and contributors [cph] (hi_embed.js)

Repository:

CRAN

Date/Publication:

2023-07-20 22:20:02 UTC

R wrapper for hypothes.is

Description

R wrapper for hypothes.is

Operate with annotation

Description

Operate with annotation

Usage

annotation(
  annotation_id,
  action = c("fetch", "update", "delete", "flag", "hide", "show", "create"),
  ...,
  api_path = get_hs_host(),
  api_key = NULL
)

Arguments

annotation_id

Annotation ID

action

Action to process, Default: 'fetch' Hide and show action needs moderator permissions.

...

Parameters for update annotation action, more information in hypothesis documentation

api_path

The hypothesis API path, can be specify by 'hypothesis.api.api_path' option or 'HYPOTHESIS_API_PATH' environment variable. Default: 'https://hypothes.is/api/'.

api_key

User api key, generated on the platform.

Source

https://h.readthedocs.io/en/latest/api-reference/v1/

Examples

## Not run: 
annotation("annotation_id")
annotation("annotation_id", action = "update", text = "updated text")
annotation("annotation_id", action = "flag")
annotation("annotation_id", action = "hide")
annotation("annotation_id", action = "show")
annotation(
  action = "create",
  uri = "https://r-world-devs.github.io/hypothesis/articles/hypothesis-api.html",
  text = "test"
)

## End(Not run)

Request parameters

Description

Request parameters

Arguments

api_path

The hypothesis API path, can be specify by 'hypothesis.api.api_path' option or 'HYPOTHESIS_API_PATH' environment variable. Default: 'https://hypothes.is/api/'.

endpoint

API request endpoint

type

API request type

api_key

User api key, generated on the platform.

Convert character string to JSON

Description

Allows to include raw JS code in JSON object.

Usage

as_json(x)

Arguments

x

Character storing JS code or object.

Details

Along with json_verbatim = TRUE argument of toJSON makes passing the code to JSON object possible.

Value

A character of class 'json'. The output can be used to store bare JS element withing JSON object.

Examples

# Function stored as text
jsonlite::toJSON(
  list(fun = "function(x) {console.log(x);}"),
  auto_unbox = TRUE, json_verbatim = TRUE
)
# Function stored as raw JS object
jsonlite::toJSON(
  list(fun = as_json("function(x) {console.log(x);}")),
  auto_unbox = TRUE, json_verbatim = TRUE
)

Get a list of groups

Description

Get a list of groups

Usage

get_groups(
  authority = NULL,
  document_uri = NULL,
  expand = NULL,
  api_path = get_hs_host(),
  api_key = NULL
)

Arguments

authority

Filter returned groups to this authority. Default: main instance authority.

document_uri

Document URI - only retrieve public (i.e. non-private) groups that apply to a given document URI.

expand

One or more relations to expand for a group resource Optional: 'organization, scopes'

api_path

The hypothesis API path, can be specify by 'hypothesis.api.api_path' option or 'HYPOTHESIS_API_PATH' environment variable. Default: 'https://hypothes.is/api/'.

api_key

User api key, generated on the platform.

Source

https://h.readthedocs.io/en/latest/api-reference/v1/

Fetch profile information for the currently-authenticated user.

Description

Fetch profile information for the currently-authenticated user.

Usage

get_profile(api_path = get_hs_host(), api_key = NULL)

Arguments

api_path

The hypothesis API path, can be specify by 'hypothesis.api.api_path' option or 'HYPOTHESIS_API_PATH' environment variable. Default: 'https://hypothes.is/api/'.

api_key

User api key, generated on the platform.

Fetch the groups for which the currently-authenticated user is a member.

Description

Fetch the groups for which the currently-authenticated user is a member.

Usage

get_profile_groups(api_path = get_hs_host(), api_key = NULL)

Arguments

api_path

The hypothesis API path, can be specify by 'hypothesis.api.api_path' option or 'HYPOTHESIS_API_PATH' environment variable. Default: 'https://hypothes.is/api/'.

api_key

User api key, generated on the platform.

Operate with group

Description

Operate with group

Usage

group(
  group_id,
  action = c("fetch", "update", "fetch_members"),
  ...,
  api_path = get_hs_host(),
  api_key = NULL
)

Arguments

group_id

Group ID

action

Action to process, Default: 'fetch'

...

Parameters for update group information, more details can be found in hypothesis documentation.

api_path

The hypothesis API path, can be specify by 'hypothesis.api.api_path' option or 'HYPOTHESIS_API_PATH' environment variable. Default: 'https://hypothes.is/api/'.

api_key

User api key, generated on the platform.

Source

https://h.readthedocs.io/en/latest/api-reference/v1/

Examples

## Not run: 
group("group_id")
group("group_id", action = "update", name = "updated text", description = "desc")
group("group_id", action = "fetch_members")

## End(Not run)

Handle hypothesis request

Description

Handle hypothesis request

Usage

hs_api_handler(
  ...,
  api_path = get_hs_host(),
  endpoint = NULL,
  type = NULL,
  api_key = NULL
)

Arguments

...

Parameter for request function

api_path

The hypothesis API path, can be specify by 'hypothesis.api.api_path' option or 'HYPOTHESIS_API_PATH' environment variable. Default: 'https://hypothes.is/api/'.

endpoint

API request endpoint

type

API request type

api_key

User api key, generated on the platform.

Branding configuration

Description

Configuration for custom annotations branding. See more at: branding.

Usage

hypothesisBranding(
  accentColor,
  appBackgroundColor,
  ctaBackgroundColor,
  ctaTextColor,
  selectionFontFamily,
  annotationFontFamily
)

Arguments

accentColor

Css-valid color value defining sidebar accent.

appBackgroundColor

Css-valid color value defining sidebar background.

ctaBackgroundColor

Css-valid color value defining main call-to-action button background.

ctaTextColor

Css-valid color value defining font color used inside of the call-to-action buttons.

selectionFontFamily

Css-valid color value defining font family used for annotation selection popup.

annotationFontFamily

Css-valid color value defining font family used for annotation popup.

Value

Named list object storing provided arguments.

Turn On/Off Annotations Feature

Description

Generates button that allows to turn on and turn off annotations tool.

Usage

hypothesisOnOff(
  initShow = TRUE,
  labelShow = "Enable Annotations",
  labelHide = "Disable Annotations"
)

Arguments

initShow

Define initial state of annotations. When FALSE, annotations are turned off.

labelShow, labelHide

Label to be shown in the button when annotations are hidden and shown respectively.

Value

A 'button' shiny.tag object, responsible for enabling/disabling of the package functionality.

Hypothesis Service Configuration

Description

A list of alternative annotation services which the client should connect. For more information visit: services.

Usage

hypothesisServices(
  apiUrl,
  authority,
  grantToken,
  allowLeavingGroups,
  enableShareLinks,
  groups,
  icon,
  onLoginRequest,
  onLogoutRequest,
  onSignupRequest,
  onProfileRequest,
  onHelpRequest
)

Arguments

apiUrl, authority, grantToken, allowLeavingGroups, enableShareLinks, groups, icon, onLoginRequest, onLogoutRequest, onSignupRequest, onProfileRequest, onHelpRequest

Arguments defining external hypothesis services.

Value

Named list object storing provided arguments.

Search for annotations

Description

Search for annotations

Usage

search_annotations(
  limit = 20L,
  sort = c("updated", "created", "group", "id", "user"),
  search_after = NULL,
  offset = 0,
  order = c("desc", "asc"),
  uri = NULL,
  uri.parts = NULL,
  wildcard_uri = NULL,
  user = NULL,
  group = NULL,
  tags = NULL,
  any = NULL,
  quote = NULL,
  references = NULL,
  text = NULL,
  api_path = get_hs_host(),
  api_key = NULL
)

Arguments

limit

The maximum number of annotations to return.

sort

Available values : updated, created, group, id, user, Default: 'updated'

search_after

Define a start point for a subset (page) of annotation search results. Example: 2023-01-01T10:00:00.000000+00:00

offset

The number of initial annotations to skip in the result set.

order

The order in which the results should be sorted. Default: 'desc'

uri

Limit the results to annotations matching the specific URI or equivalent URIs. URI can be a URL (a web page address) or a URN representing another kind of resource such as DOI (Digital Object Identifier) or a PDF fingerprint.

uri.parts

Limit the results to annotations containing the given keyword (tokenized chunk) in the URI.

wildcard_uri

Limit the results to annotations whose URIs match the wildcard pattern.

user

Limit the results to annotations made by the specified user. Example: 'user=acct:username@hypothes.is'

group

Limit the results to annotations made in the specified group (by group ID).

tags

Limit the results to annotations tagged with the specified value. Example: tags=artificial,intelligence

any

Limit the results to annotations who contain the indicated keyword in any of the following field: 'quote, tags, text, url'

quote

Limit the results to annotations that contain this text inside the text that was annotated.

references

Returns annotations that are replies to this parent annotation ID.

text

Limit the results to annotations that contain this text in their textual body.

api_path

The hypothesis API path, can be specify by 'hypothesis.api.api_path' option or 'HYPOTHESIS_API_PATH' environment variable. Default: 'https://hypothes.is/api/'.

api_key

User api key, generated on the platform.

Source

https://h.readthedocs.io/en/latest/api-reference/v1/

Use hypothesis annotations

Description

Function used to initialize hypothesis annotations in Shiny app or R Markdown document.

Usage

useHypothesis(
  openSidebar = TRUE,
  showHighlights = c("whenSidebarOpen", "always", "never"),
  theme = c("classic", "clean"),
  branding = hypothesisBranding(),
  sidebarAppUrl = NULL,
  onLayoutChange = as_json("tryHideHypothesis"),
  services = hypothesisServices(),
  enableExperimentalNewNoteButton = NULL,
  usernameUrl = NULL,
  externalContainerSelector = NULL,
  focus = NULL,
  requestConfigFromFrame = NULL,
  assetRoot = NULL,
  notebookAppUrl = NULL,
  enableShareLinks = FALSE,
  ...
)

Arguments

openSidebar

Set to TRUE if annotations sidebar should be opened in initial state.

showHighlights

Configure when annotated text should be highlighted. "whenSidebarOpen" highlights content only when annotations sidebar is open (default). The remaining options are "always" and "never".

theme

Annotations sidebar theme. Available options "classic" (default) and "clean".

branding

Configure annotations tool branding (e.g. sidebar background). See hypothesisBranding for possible options.

sidebarAppUrl, onLayoutChange, services, enableExperimentalNewNoteButton, usernameUrl, externalContainerSelector, focus, requestConfigFromFrame, assetRoot, notebookAppUrl, enableShareLinks

Extra arguments used for external services configuration and assets configuration. Visit config for more details.

...

Extra arguments passed to client configuration.

Value

A list of class 'shiny.tag.list' storing the package JS/CSS dependencies.