View source for Core2 functions

{{Warn|text=The code for core2 is still under construction, so the information on this page may become outdated without warning.}}

{{Note|text=Obligatory disclaimer about this document being in-process.}}

Core2 functions:

= core classes =

== int ==

    function builtin zeropad(int digits) : string
    "Return the integer as a string formatted at least \$digits characters long, left-padded with zeroes.";

    function builtin compare(int n) : int
    "Compare one integer with another. Returns a negative number if n is less than the subject, positive if greater or zero if the two are numerically equal.";

== string ==

    function builtin index(string sub) : int
    "Returns the index of the first instance of \$sub in string.";
    
    function builtin index(string sub, int position) : int
    "Returns the index of the first instance of \$sub in string, starting from \$position";
    
    function builtin substr(int start, int length) : string
    "Returns up to \$length characters from string, skipping \$start characters from the beginning.";

    function builtin ends_with (string sub) : bool
    "Returns true if string ends in \$sub";

    function builtin starts_with (string sub) : bool
    "Returns true if string begins with \$sub";

    function builtin contains (string sub) : bool
    "Return true if string contains \$sub";

    function builtin replace(string find, string replace) : string
    "Replace all instances of \$find with \$replace. Case sensitive."; 
    
    function builtin split (string sub) : string[]
    "Return an array of strings split by \$sub";
    
    function builtin lower : string
    "Returns string in lower case.";

    function builtin upper : string
    "Returns string in upper case";

    function builtin upperfirst : string
    "Return string with the first character capitalized.";

    function builtin length() : int
    "Return the number of characters in the string.";

    function builtin repeat(int n) : string
    "Returns the string repeated n times";

    function builtin compare(string s) : int
    "Compare one string with another. Returns a negative number if n is alphabetically before the subject, positive if greater or zero if the two are equal. Note that this function currently does a simple ASCII compare, not a proper unicode-aware sort.";

    function builtin css_string() : string
    "Returns the string escaped and quoted as a CSS string literal, safe for insertion into a stylesheet.";

    function builtin css_keyword() : string
    "If the string is syntactically valid as a CSS keyword (only letters and spaces) returns it, else returns an empty string.";

    function builtin css_keyword_list() : string
    "Analyses the string as a space-separated list of CSS keywords and returns a string containing the items that are syntactically acceptable.";

    function builtin css_keyword(string[] allowed) : string
    "Same as [method[string.css_keyword()]] except also imposes a whitelist of valid keywords given in \$allowed.";

    function builtin css_keyword_list(string[] allowed) : string
    "Same as [method[string.css_keyword_list()]] except also imposes a whitelist of valid keywords given in \$allowed.";

    function builtin css_length_value() : string
    "If the string contains a valid CSS length value, returns a canonical version. Else returns an empty string.";

    function builtin css_url_value : string
    "If the string contains a valid HTTP or HTTPS URL it is returned. Otherwise, an empty string is returned.";

== Color ==

  function builtin Color(string s) : Color "Constructor for color class.  Lets you make a Color object from a string of form #rrggbb";
  function builtin set_hsl (int h, int s, int v) "Set the HSL value for a color class.";

  function builtin red(int r) "Set the red value. (0-255)";
  function builtin green(int g) "Set the green value. (0-255)";
  function builtin blue(int b) "Set the blue value. (0-255)";
  function builtin red() : int "Get the red value.";
  function builtin green() : int "Get the green value.";
  function builtin blue() : int "Get the blue value.";

  function builtin hue(int h) "Set the hue value. (0-255)";
  function builtin saturation(int s) "Set the saturation value. (0-255)";
  function builtin lightness(int v) "Set the lightness value. (0-255)";
  function builtin hue() : int "Get the hue value. (0-255)";
  function builtin saturation() : int "Get the saturation value. (0-255)";
  function builtin lightness() : int "Get the lightness value. (0-255)";

  function builtin clone() : Color "Returns identical color.";
  function builtin lighter() : Color "Returns a new color with lightness increased by 30.";
  function builtin lighter(int amt) : Color "Returns a new color with lightness increased by amount given.";
  function builtin darker() : Color "Returns a new color with lightness decreased by 30.";
  function builtin darker(int amt) : Color "Returns a new color with lightness decreased by amount given.";
  function builtin inverse() : Color "Returns inverse of color.";
  function builtin average(Color other) : Color "Returns color averaged with \$other color.";
  function builtin blend(Color other, int value) : Color "Returns color blended with \$other color by percentage value (int between 0 and 100).";

= Site-core classes =

== Date == 

    function builtin day_of_week() : int
    "Returns the day of the week this date falls on, from Sunday=1 to Saturday=7";

    function builtin date_format () : string
    "Returns date formatted as normal.  /// SeeAlso: siteapi.core1.dateformats";

    function builtin date_format (string fmt) : string
    "Returns date formatted as indicated by \$fmt.  One of: short, med, long, med_day, long_day.  Or a custom format.  Default is 'short'. /// SeeAlso: siteapi.core1.dateformats";

    function builtin date_format (string fmt, bool linkify) : string
    "Returns date formatted in the same way as calling date_format(string fmt), but with day, month, and year as links to the corresponding archive pages.";

    function builtin compare(Date d) : int
    "Compare two dates. Returns a negative number if d is before the subject in time, positive if it is after, or zero if the two dates are equal. When comparing a Date with a DateTime, the time on the bare Date value is assumed to be midnight.";

    function builtin compare(DateTime d) : int
    "Compare two dates. Returns a negative number if d is before the subject in time, positive if it is after, or zero if the two dates are equal. When comparing a Date with a DateTime, the time on the bare Date value is assumed to be midnight.";

== DateTime (sub of Date) ==

    function builtin time_format () : string
    "Returns time formatted as normal.  /// SeeAlso: siteapi.core1.dateformats";

    function builtin time_format (string fmt) : string
    "Returns time formatted as indicated by \$fmt, or normal if blank.  /// SeeAlso: siteapi.core1.dateformats";

== Image ==

    function builtin set_url (string url)
    "Sets the URL, doing any necessary escaping.";

    function print ()
    "Print an HTML tag for this Image";

    function print (string alttext)
    "Print an HTML tag for this Image with given alttext";

    function print (string{} opts)
    "Print the HTML for an image, Supported keys are 'href' to create a link to the image source
     and 'a_attr' which adds attributes to the anchor tag if a link is to be printed.";

    function as_string () : string
    "Return the HTML tag for this image";

    function as_string (string alttext) : string
    "Return an HTML tag for this Image with given alttext";

    function as_string (string{} opts) : string
    "Return the HTML for an image, Supported keys are 'href' to create a link to the image source
     and 'a_attr' which adds attributes to the anchor tag if a link is to be printed.";

== Link/Button ==

    function print_button
    "Output this Link as a clickable button using [member[Link.icon]]";

    function as_string() : string
    "Return the button HTML link.";

== ItemRange ==

  function builtin url_of(int n) : string "Returns the URL to use to link to the nth item";

  function print () "Prints the item range links";

  function print(string labeltext) "Prints the item range links with the given \$labeltext";

= DW-specific classes =

== CommentInfo ==

    function print
    "Print all comment related links";
    function print_readlink
    "Print the formatted link to the 'Read Comments' view";
    function print_postlink
    "Print the formatted link to the 'Post Comments' view";

== UserLite ==

    function builtin equals(UserLite u) : bool "Returns true if the two user objects refer to the same user. Use this rather than comparing usernames, since usernames aren't globally unique.";
    function builtin ljuser() : string "Returns an LJ user tag for the user.";
    function builtin ljuser(Color link_color) : string "Returns an LJ user tag for the user.  The color of the link will be link_color.";
    function builtin get_link(string key) : Link "Returns a link based on the given key, or null if the link is unavailable";
    function base_url () : string "Returns URL of user's journal.";
    function tag_manage_url () : string "Returns URL to user's tag management page.";
    function print_linkbar() "Print the link bar for this user/journal. Deprecated, use print_interaction_links.";
    function print_interaction_links() "Print the interaction links for this user/journal.";
    function as_string() : string;
    function print ();

== User (sub of UserLite) ==

    function print_userpic() [fixed] "Print the userpic for this user";

== EntryLite ==

    function print_text() [fixed]
        "Print the entry text. Doesn't print anything in some contexts, such as on a month view or in a collapsed comment.";
    function builtin get_link (string key) : Link "Get a link to some action related to this entry or comment. You can iterate over [member[EntryLite.link_keyseq]] to get keys to pass in here to produce a 'toolbar' of links.";
    function builtin get_plain_subject () : string "For Entries that can contain HTML subjects, this returns the subject without HTML.  Comments can't have HTML in subjects, so this is equivalent to just using \$.subject.  The returned 'plain' subject may still contain HTML entities, so don't do substring chops on it either.";
    function builtin get_tags_text () : string "Returns a string containing a div of class 'ljtags' with the tags for the entry.  If there are no tags on the entry, returns a blank string.  The string is formatted according to the 'text_tags' property.";
    function print_userpic() [fixed] "Print the userpic for this entry or comment";
    function print_linkbar() "Print the link bar for this entry or comment. Deprecated. Use print_management_links()";
    function print_item_linkbar() "Print the item link bar for this entry or comment. Deprecated. Use print_interaction_links()";
    function print_management_links() "Print the links to manage this entry or comment. (Screen, freeze, track, etc)";
    function print_interaction_links() "Print the links to interact with this entry or comment. (Post a comment etc)";
    function print_time () [fixed] "Print the time of this post, with most useful information for user, and with tooltip for more.";
    function print_time (string datefmt, string timefmt) [fixed] "Print the time of the post, with customized date/time formats.";
    function time_display () : string "Show the time of this post, with most useful information for user, and with tooltip for more.";
    function time_display (string datefmt, string timefmt) : string "time_display, with customized date/time formats.";
    function builtin formatted_subject (string{} opts) : string "formats subject - outputs subject as html-link, gets hash of attributes - class and(or) style ";
    function print_subject () [fixed] "Print the formatted subject for this entry or comment";
    function print_subject (string{} opts) [fixed] "Print the formatted subject for this entry or comment, gets hash of attributes - class and(or) style ";

== Entry (sub of EntryLite) ==

    function print_metatypes() "Print the metatype (security, age restricion) icons for this entry";
    function print_metatypes(bool icon, bool info) "Print the metatype (security, age restricion) information for this entry";

    function print_item_linkbar(string target) "Print the item link bar for this entry or comment with target. Deprecated. Use print_interaction_links instead.";
    function print_interaction_links(string target) "Print the links to interact with this entry or comment, with target.";

    function print_tags() "Print the tags for this entry.";
    function print_metadata ();
    function builtin plain_subject () : string
        "Return entry's subject as plain text, with all HTML removed.";

    function print_link_next() "Print the link to the next entry in this journal.";
    function print_link_prev() "Print the link to the previous entry in this journal.";
    function builtin viewer_sees_ebox() [fixed] : bool
    "True if opaque horizontal site-specific content boxes between entries should be displayed to the user.";
    function builtin print_ebox() [fixed]
    "Prints a small horizontal bar of site-specific content between entries in a journal.";

== Comment (sub of EntryLite) ==

    function builtin print_multiform_check "Prints the select checkbox in CSS class 'ljcomsel' with DOM id 'ljcomsel_\$talkid' for a multi-action form started with [method[EntryPage.print_multiform_start()]].";

    function builtin print_reply_link(string{} opts) "Prints a link to reply to the comment. You may specify the link text in the 'linktext' option, and the link CSS class in 'class'. You may also specify the url of an image to use as a button in 'img_url'.";

    function builtin print_reply_container() "Prints the area in which the quickreply box will go. If no container is available, quickreply will not work.";

    function builtin print_reply_container(string{} opts) "Prints the area in which the quickreply box will go. You may 'class' which will be the CSS class used by the container. If no container is available, quickreply will not work.";

    function builtin expand_link () : string "Returns a link to expand a collapsed comment. Uses the value of the 'text_comment_expand' property as the text. Will not work in untrusted layers.";
    function builtin expand_link (string{} opts) : string "Returns a link to expand a collapsed comment. Can pass options 'text', 'title', 'class', and 'img_url' (and other 'img_*' options). Will not work in untrusted layers.";

    function builtin print_expand_link () : string "Prints a link to expand a collapsed comment. Uses the value of the 'text_comment_expand' property as the text.";
    function builtin print_expand_link (string{} opts) : string "Prints a link to expand a collapsed comment. Can pass options 'text', 'title', 'class', and 'img_url' (and other 'img_*' options).";
    function print_time (string datefmt, string timefmt, bool edittime) "Same as EntryLite::print_time, except can pass in if we want the edit time or not.";
    function time_display (string datefmt, string timefmt, bool edittime) : string "Same as EntryLite::time_display, except can pass in if we want the edit time or not.";
    function print_edittime () "Print the time that this comment was edited, with most useful information for user.  Empty string if the comment hasn't been edited.";
    function print_edittime (string datefmt, string timefmt) "print_edittime, with customized date/time formats.";
    function edittime_display () : string "Show the time that this comment was edited, with most useful information for user.  Empty string if the comment hasn't been edited.";
    function edittime_display (string datefmt, string timefmt) : string "edittime_display, with customized date/time formats.";

    function print_edit_text () "Print the text that says when this comment was edited.";

    function print_poster()
    "Output a line of text which says who posted a comment (just \"user\", or \"user posting in somejournal\")";

== Redirector == 
{{Note|text=do we need this in doc?}}

    function start_form() "Starts an inline HTML form, then calls [method[Redirector.print_hiddens()]].  You can also make it yourself, using [member[Redirector.url]], if you need special form attributes.";
    function print_hiddens() "Prints the necessary hidden elements for a form.  Called automatically by [method[Redirector.start_form()]].";
    function end_form() "Prints a form close tag.";

    function builtin get_url(string redir_key) "Returns a GET URL, given a redir_key";

= Pages =

== Page ==

    function print
    "The main entry point that Dreamwidth calls. Layouts should override this to create HTML that's the
    same for all view types, and use \$this->title, \$this->head and \$this->body to include view-specific
    content into the template.";

    function print_title "Print the title for this particular page, such as \"Friends' Recent Entries\" for the friends view,
    or a date for the day view. Should be overridden in i18n layers. Ideally, layout layers should never override
    this.  See [method[Page.title()]].";

   function print_global_title;
   function print_global_subtitle;

    function view_title : string
    "Return a title for this particular page, such as \"Friends' Recent Entries\" for the friends view,
    or a date for the day view. Should be overridden in i18n layers. Ideally, layout layers should never override
    this.  See [method[Page.title()]].";

    function title : string
    "Return a relevant combination of [member[Page.global_title]] and [method[Page.view_title()]].  May be
    overridden in layout layers or left untouched for the core layer to handle.";

    function print_time
    "Print the time when the page was created.";

    function print_time (string datefmt, string timefmt)
    "Print the time when the page was created, with customized date/time formats.";

    function print_body
    "Call from [method[Page.print()]] to render parts of the view that are specific to the view, eg print
    the recent set of journal entries, recent friends entries, or rows of user information";

    function print_head [fixed]
    "Print server side supplied head content. This is a fixed function, so you can't override it. See
    [method[Page.print_custom_head()]] if you want to supply custom head content.";

    function builtin print_control_strip [fixed]
    "Prints a control strip for the user's convenience";

    function print_custom_head
    "Layers can override this to add extra HTML to the head section of the HTML document.
    Note that layouts are not intended to override this method.";

    function print_linklist
    "Print the list of UserLink objects specified by the user.";

    function print_entry(Entry e)
    "Output a journal entry. Layouts should override this and the inherited versions in RecentPage, FriendsPage
    and DayPage to change how entries display.";

    function print_entry_poster(EntryLite e)
    "Output a line of text which says who posted an entry (just \"user\", or \"user posting in somejournal\")";

    function builtin get_latest_month() : YearMonth
    "Returns information about the latest month the user posted (or the current month, if no posts), so that the page may include a mini-calendar or similar features.";

    function builtin visible_tag_list() : TagDetail[]
    "Returns an array of tags that the logged in user can see for the journal being viewed.";

    function builtin visible_tag_list(int limit) : TagDetail[]
    "Returns an array of tags that the logged in user can see for the journal being viewed, limited to the top \$limit tags by number of uses.";

    function builtin print_reply_link(string{} opts) "Prints a link to reply to the comment. You may specify the link text in the 'linktext' option, the link CSS class in 'class', and the target container in the 'target' option. You may also specify the url of an image to use as a button in 'img_url'.";

    function builtin print_reply_container(string{} opts) "Prints the area in which the quickreply box will go. Options you may specify are 'target' which will be the target id, and 'class' which will be the CSS class used by the container. If no container is available, quickreply will not work.";

    function print_navigation() [fixed] "Print out the page navigation links.";

    function print_module_group_primary
    "Prints first grouping of modules (such as a sidebar).";

    function print_module_group_secondary
    "Prints second grouping of modules (such as a sidebar).";

    function print_module_group_tertiary
    "Prints third grouping of modules (such as a sidebar).";

    function print_module_group_quaternary
    "Prints fourth grouping of modules (such as a sidebar).";
    
    function print_stylesheets
    "Prints all defined stylesheets, including default and user-defined ones.";

    function print_default_stylesheet
    "Prints the default stylesheet.";

    function builtin print_trusted(string key)
    "Prints a trusted string by key.";

== EntryPage (sub of Page) ==

    function print_comment_section(Entry entry) "Prints comment section";
    function print_comments(Comment[] comments) "Prints comments";
    function print_comment(Comment comment) "Prints a full comment";
    function print_comment_partial(Comment comment) "Prints a collapsed comment";

== MessagePage (sub of Page) ==

    function print_message() [fixed] "Print the message. Call this rather than printing [member[MessagePage.message]] directly.";
    function print_links() "Print the links from the [member[MessagePage.links]] and [member[MessagePage.link_keyseq]] members. Layouts will probably want to override this.";

== YearWeek ==

    function print()
    "Print formatted week";

== YearMonth ==

    function builtin month_format () : string
    "Returns month formatted long (February 1980)  /// SeeAlso: siteapi.core1.dateformats";
    function builtin month_format (string fmt) : string
    "Returns time formatted as indicated by \$fmt, or 'long' if blank.  /// SeeAlso: siteapi.core1.dateformats";
    function builtin month_format (string fmt, bool link) : string
    "Returns time formatted in the same way as calling month_format(string fmt), but with month and year as links to the corresponding archive pages.";

== YearPage (sub of Page) ==

    function print_month(YearMonth m)
    "Print the calendar cell for the given month";

    function print_year_links()
    "Print the navigation links to move between years";

== MonthDay (sub of YearDay) ==

    function print_subjectlist
    "Print a list of entry summaries including subjects";

== ReplyForm ==

    function builtin print() "Prints the reply form";

= Built-in functions =

    function builtin eurl (string s) : string
    "URL escape";

    function builtin ehtml (string s) : string
    "Escapes all HTML tags and entities from the text";

    function builtin etags (string s) : string
    "Escapes all HTML tags (but not entities) from text";

    function builtin clean_url (string s) : string
    "Returns the given URL back if it's a valid URL.";

    function builtin rand (int high) : int
    "Returns a random integer between 1 and \$high, inclusive.";

    function builtin rand (int low, int high) : int
    "Returns a random integer between \$low and \$high, inclusive.";

    function builtin pageview_unique_string () : string
    "Returns a unique string for the remote user.";

    function builtin alternate (string a, string b) : string
    "With each call, this function will alternate between the two values and return one of them.
Useful for making tables whose rows alternate in background color.";

    function builtin zeropad (int n, int digits) : string
    "Returns the number padded with zeroes so it has the amount of digits indicated.";

    function builtin zeropad (string n, int digits) : string
    "Returns the number padded with zeroes so it has the amount of digits indicated.";

    function builtin striphtml (string s) : string
    "Similar to ehtml, but the HTML tags are stripped rather than escaped.";

    function builtin viewer_logged_in() : bool
    "Returns true if the user viewing the page is logged in. It's recommended that your page links to the site login page if the user isn't logged in.";

    function builtin viewer_is_owner() : bool
    "Returns true if the user viewing the page is both logged in, and is the owner of the content in question. Useful for returning links to manage information, or edit entries.";

    function builtin viewer_is_friend() : bool
    "Returns true if the user viewing the page is both logged in, and is a friend of the journal being viewed. Always returns false for communities, since they cannot have friends.";

    function builtin viewer_is_member() : bool
    "Returns true if the user viewing the page is both logged in, and is a member of the community being viewed. Always returns false for personal journals, since they cannot have members.";

    function builtin viewer_sees_control_strip [fixed] : bool
    "Returns true if reader will see the built in control strip.";

    function builtin control_strip_logged_out_userpic_css [fixed] : string
    "Returns CSS for the userpic div in the logged out version of the control strip.";

    function builtin control_strip_logged_out_full_userpic_css [fixed] : string
    "Returns CSS for the loggedout_userpic div in the logged out version of the control strip.";

    function builtin get_page () : Page
    "Gets the top-level [class[Page]] instance that Dreamwidth ran the [method[Page.print()]] method on.";

    function builtin get_url(string user, string view) : string
    "Returns a URL to the specified view for the specified user. Views use the same names as elsewhere. (recent, friends, archive, month, userinfo)";

    function builtin get_url(UserLite user, string view) : string
    "Returns a URL to the specified view for the specified user. Views use the same names as elsewhere. (recent, friends, archive, month, userinfo)";

    function builtin string(int i) : string
    "Return the given integer as a string";

    function builtin int(string s) : int
    "Convert the string to an integer and return";

    function builtin set_content_type(string text)
    "Set the HTTP Content-type response header (for example, if outputting XML). Must be called before printing any data.";

    function builtin get_plural_phrase(int n, string prop) : string
    "Picks the phrase with the proper plural form from those in the property \$prop, passing \$n to [function[lang_map_plural(int)]] to get the proper form for the current language, and then substituting the # character with \$n.  Also, returned string is HTML-escaped.";

    function builtin weekdays() : int[]
    "Integers representing the days of the week. This will start on Monday (2) or Sunday (1) depending on the property setting for start-of-week and go to Sunday (1) or Saturday (7)";

    function builtin PalItem(int index, Color c) : PalItem
    "Convenience constructor to make populating an array of PalItems (like in [function[palimg_modify(string,PalItem[])]]) easy.";

    function builtin UserLite(string username) : UserLite
    "Constructor for making a UserLite object from a username";

    function builtin palimg_modify(string filename, PalItem[] items) : string
    "Return a URL to the specified filename (relative to the palimg root) with its palette table altered, once for each provided [class[PalItem]].  Restrictions:  only 7 palette entries may be modified, and the PalItem indexes must be 0-15.";

    function builtin palimg_tint(string filename, Color bright) : string
    "Return a URL to the specified filename (relative to the palimg root) with its palette table tinted.  The given 'bright' color will be the new white, and darkest color remains black.";

    function builtin palimg_tint(string filename, Color bright, Color dark) : string
    "Return a URL to the specified filename (relative to the palimg root) with its palette table tinted.  The given 'bright' color will be the new white, and the given 'dark' color is the new black.";

    function builtin palimg_gradient(string filename, PalItem start, PalItem end) : string
    "Return a URL to the specified filename (relative to the palimg root) with its palette table made into a gradient.  All palette entries between the inclusive indexes of \$start and \$end will fade from the colors in \$start and \$end.  The palette indexes for the start and end can be between 0 and 255.";

    function builtin set_handler(string eventname, string[][] commands);

    function builtin userlite_base_url(UserLite ul) : string;

    function builtin start_css () "Declare that you're about to start printing out CSS that should be buffered, then later cleaned when you call end_css().  WARNING: this is not re-entrant.  You can't call start_css recursively.";

    function builtin end_css () "Declare that you're done printing CSS and the output thus buffered should be cleaned and printed.";

    function builtin journal_current_datetime() : DateTime
    "Returns the current datetime in the timezone of the journal being viewed.";

    function builtin style_is_active() : bool
    "Returns if the style (layout and theme) calling it is active based on a hook.  If hook isn't defined, returns true always.";

    function builtin htmlattr(string name, string value) : string
    "If the value isn't blank, return in HTML attribute format with a leading space.  HTML of name is not escaped.";

    function builtin htmlattr(string name, int value) : string
    "If the value isn't blank, return in HTML attribute format with a leading space.  HTML of name is not escaped.";


<i>(FIXME: resume after properties)</i>

[[Category: Styles]]